1c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer/* 2c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved. 3c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 5c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This code is free software; you can redistribute it and/or modify it 6c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * under the terms of the GNU General Public License version 2 only, as 7c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * published by the Free Software Foundation. Oracle designates this 8c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * particular file as subject to the "Classpath" exception as provided 9c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * by Oracle in the LICENSE file that accompanied this code. 10c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 11c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This code is distributed in the hope that it will be useful, but WITHOUT 12c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * version 2 for more details (a copy is included in the LICENSE file that 15c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * accompanied this code). 16c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 17c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * You should have received a copy of the GNU General Public License version 18c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 2 along with this work; if not, write to the Free Software Foundation, 19c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 21c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * or visit www.oracle.com if you need additional information or have any 23c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * questions. 24c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer */ 25c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer 26c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer/* 27c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This file is available under and governed by the GNU General Public 28c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * License version 2 only, as published by the Free Software Foundation. 29c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * However, the following notice accompanied the original version of this 30c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * file: 31c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 32c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Copyright (c) 2012, Stephen Colebourne & Michael Nascimento Santos 33c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 34c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * All rights reserved. 35c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 36c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Redistribution and use in source and binary forms, with or without 37c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * modification, are permitted provided that the following conditions are met: 38c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 39c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * * Redistributions of source code must retain the above copyright notice, 40c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * this list of conditions and the following disclaimer. 41c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 42c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * * Redistributions in binary form must reproduce the above copyright notice, 43c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * this list of conditions and the following disclaimer in the documentation 44c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * and/or other materials provided with the distribution. 45c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 46c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * * Neither the name of JSR-310 nor the names of its contributors 47c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * may be used to endorse or promote products derived from this software 48c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * without specific prior written permission. 49c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 50c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 51c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 52c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 53c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 54c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 55c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 56c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 57c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 58c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 59c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 60c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 61c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer */ 62c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer 63c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer/** 64c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 65c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The main API for dates, times, instants, and durations. 66c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 67c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 68c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The classes defined here represent the principle date-time concepts, 69c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * including instants, durations, dates, times, time-zones and periods. 70c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * They are based on the ISO calendar system, which is the <i>de facto</i> world 71c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * calendar following the proleptic Gregorian rules. 72c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * All the classes are immutable and thread-safe. 73c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 74c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 75c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Each date time instance is composed of fields that are conveniently 76c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * made available by the APIs. For lower level access to the fields refer 77c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * to the {@code java.time.temporal} package. 78c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Each class includes support for printing and parsing all manner of dates and times. 79c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Refer to the {@code java.time.format} package for customization options. 80c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 81c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 82c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The {@code java.time.chrono} package contains the calendar neutral API 83c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.chrono.ChronoLocalDate ChronoLocalDate}, 84c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.chrono.ChronoLocalDateTime ChronoLocalDateTime}, 85c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.chrono.ChronoZonedDateTime ChronoZonedDateTime} and 86c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.chrono.Era Era}. 87c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This is intended for use by applications that need to use localized calendars. 88c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * It is recommended that applications use the ISO-8601 date and time classes from 89c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * this package across system boundaries, such as to the database or across the network. 90c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The calendar neutral API should be reserved for interactions with users. 91c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 92c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 93c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <h3>Dates and Times</h3> 94c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 95c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.Instant} is essentially a numeric timestamp. 96c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The current Instant can be retrieved from a {@link java.time.Clock}. 97c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This is useful for logging and persistence of a point in time 98c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * and has in the past been associated with storing the result 99c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * from {@link java.lang.System#currentTimeMillis()}. 100c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 101c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 102c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.LocalDate} stores a date without a time. 103c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This stores a date like '2010-12-03' and could be used to store a birthday. 104c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 105c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 106c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.LocalTime} stores a time without a date. 107c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This stores a time like '11:30' and could be used to store an opening or closing time. 108c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 109c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 110c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.LocalDateTime} stores a date and time. 111c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This stores a date-time like '2010-12-03T11:30'. 112c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 113c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 114c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.ZonedDateTime} stores a date and time with a time-zone. 115c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This is useful if you want to perform accurate calculations of 116c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * dates and times taking into account the {@link java.time.ZoneId}, such as 'Europe/Paris'. 117c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Where possible, it is recommended to use a simpler class without a time-zone. 118c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The widespread use of time-zones tends to add considerable complexity to an application. 119c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 120c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 121c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <h3>Duration and Period</h3> 122c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 123c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Beyond dates and times, the API also allows the storage of periods and durations of time. 124c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * A {@link java.time.Duration} is a simple measure of time along the time-line in nanoseconds. 125c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * A {@link java.time.Period} expresses an amount of time in units meaningful 126c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * to humans, such as years or days. 127c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 128c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 129c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <h3>Additional value types</h3> 130c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 131c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.Month} stores a month on its own. 132c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This stores a single month-of-year in isolation, such as 'DECEMBER'. 133c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 134c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 135c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.DayOfWeek} stores a day-of-week on its own. 136c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This stores a single day-of-week in isolation, such as 'TUESDAY'. 137c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 138c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 139c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.Year} stores a year on its own. 140c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This stores a single year in isolation, such as '2010'. 141c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 142c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 143c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.YearMonth} stores a year and month without a day or time. 144c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This stores a year and month, such as '2010-12' and could be used for a credit card expiry. 145c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 146c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 147c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.MonthDay} stores a month and day without a year or time. 148c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This stores a month and day-of-month, such as '--12-03' and 149c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * could be used to store an annual event like a birthday without storing the year. 150c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 151c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 152c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.OffsetTime} stores a time and offset from UTC without a date. 153c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This stores a date like '11:30+01:00'. 154c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The {@link java.time.ZoneOffset ZoneOffset} is of the form '+01:00'. 155c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 156c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 157c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.OffsetDateTime} stores a date and time and offset from UTC. 158c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This stores a date-time like '2010-12-03T11:30+01:00'. 159c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This is sometimes found in XML messages and other forms of persistence, 160c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * but contains less information than a full time-zone. 161c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 162c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 163c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <h3>Package specification</h3> 164c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 165c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Unless otherwise noted, passing a null argument to a constructor or method in any class or interface 166c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown. 167c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The Javadoc "@param" definition is used to summarise the null-behavior. 168c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The "@throws {@link java.lang.NullPointerException}" is not explicitly documented in each method. 169c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 170c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 171c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * All calculations should check for numeric overflow and throw either an {@link java.lang.ArithmeticException} 172c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * or a {@link java.time.DateTimeException}. 173c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 174c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 175c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <h3>Design notes (non normative)</h3> 176c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 177c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The API has been designed to reject null early and to be clear about this behavior. 178c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * A key exception is any method that takes an object and returns a boolean, for the purpose 179c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * of checking or validating, will generally return false for null. 180c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 181c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 182c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The API is designed to be type-safe where reasonable in the main high-level API. 183c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Thus, there are separate classes for the distinct concepts of date, time and date-time, 184c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * plus variants for offset and time-zone. 185c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This can seem like a lot of classes, but most applications can begin with just five date/time types. 186c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <ul> 187c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <li>{@link java.time.Instant} - a timestamp</li> 188c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <li>{@link java.time.LocalDate} - a date without a time, or any reference to an offset or time-zone</li> 189c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <li>{@link java.time.LocalTime} - a time without a date, or any reference to an offset or time-zone</li> 190c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <li>{@link java.time.LocalDateTime} - combines date and time, but still without any offset or time-zone</li> 191c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <li>{@link java.time.ZonedDateTime} - a "full" date-time with time-zone and resolved offset from UTC/Greenwich</li> 192c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </ul> 193c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 194c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@code Instant} is the closest equivalent class to {@code java.util.Date}. 195c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@code ZonedDateTime} is the closest equivalent class to {@code java.util.GregorianCalendar}. 196c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 197c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 198c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Where possible, applications should use {@code LocalDate}, {@code LocalTime} and {@code LocalDateTime} 199c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * to better model the domain. For example, a birthday should be stored in a code {@code LocalDate}. 200c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Bear in mind that any use of a {@linkplain java.time.ZoneId time-zone}, such as 'Europe/Paris', adds 201c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * considerable complexity to a calculation. 202c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Many applications can be written only using {@code LocalDate}, {@code LocalTime} and {@code Instant}, 203c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * with the time-zone added at the user interface (UI) layer. 204c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 205c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 206c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The offset-based date-time types {@code OffsetTime} and {@code OffsetDateTime}, 207c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * are intended primarily for use with network protocols and database access. 208c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * For example, most databases cannot automatically store a time-zone like 'Europe/Paris', but 209c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * they can store an offset like '+02:00'. 210c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 211c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 212c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Classes are also provided for the most important sub-parts of a date, including {@code Month}, 213c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@code DayOfWeek}, {@code Year}, {@code YearMonth} and {@code MonthDay}. 214c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * These can be used to model more complex date-time concepts. 215c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * For example, {@code YearMonth} is useful for representing a credit card expiry. 216c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 217c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 218c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Note that while there are a large number of classes representing different aspects of dates, 219c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * there are relatively few dealing with different aspects of time. 220c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Following type-safety to its logical conclusion would have resulted in classes for 221c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * hour-minute, hour-minute-second and hour-minute-second-nanosecond. 222c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * While logically pure, this was not a practical option as it would have almost tripled the 223c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * number of classes due to the combinations of date and time. 224c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Thus, {@code LocalTime} is used for all precisions of time, with zeroes used to imply lower precision. 225c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 226c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 227c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Following full type-safety to its ultimate conclusion might also argue for a separate class 228c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * for each field in date-time, such as a class for HourOfDay and another for DayOfMonth. 229c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This approach was tried, but was excessively complicated in the Java language, lacking usability. 230c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * A similar problem occurs with periods. 231c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * There is a case for a separate class for each period unit, such as a type for Years and a type for Minutes. 232c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * However, this yields a lot of classes and a problem of type conversion. 233c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Thus, the set of date-time types provided is a compromise between purity and practicality. 234c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 235c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 236c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The API has a relatively large surface area in terms of number of methods. 237c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This is made manageable through the use of consistent method prefixes. 238c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <ul> 239c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <li>{@code of} - static factory method</li> 240c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <li>{@code parse} - static factory method focussed on parsing</li> 241c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <li>{@code get} - gets the value of something</li> 242c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <li>{@code is} - checks if something is true</li> 243c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <li>{@code with} - the immutable equivalent of a setter</li> 244c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <li>{@code plus} - adds an amount to an object</li> 245c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <li>{@code minus} - subtracts an amount from an object</li> 246c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <li>{@code to} - converts this object to another type</li> 247c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <li>{@code at} - combines this object with another, such as {@code date.atTime(time)}</li> 248c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </ul> 249c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 250c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * Multiple calendar systems is an awkward addition to the design challenges. 251c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The first principle is that most users want the standard ISO calendar system. 252c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * As such, the main classes are ISO-only. The second principle is that most of those that want a 253c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * non-ISO calendar system want it for user interaction, thus it is a UI localization issue. 254c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * As such, date and time objects should be held as ISO objects in the data model and persistent 255c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * storage, only being converted to and from a local calendar for display. 256c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The calendar system would be stored separately in the user preferences. 257c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 258c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 259c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * There are, however, some limited use cases where users believe they need to store and use 260c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * dates in arbitrary calendar systems throughout the application. 261c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * This is supported by {@link java.time.chrono.ChronoLocalDate}, however it is vital to read 262c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * all the associated warnings in the Javadoc of that interface before using it. 263c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * In summary, applications that require general interoperation between multiple calendar systems 264c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * typically need to be written in a very different way to those only using the ISO calendar, 265c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * thus most applications should just use ISO and avoid {@code ChronoLocalDate}. 266c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 267c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <p> 268c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The API is also designed for user extensibility, as there are many ways of calculating time. 269c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * The {@linkplain java.time.temporal.TemporalField field} and {@linkplain java.time.temporal.TemporalUnit unit} 270c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * API, accessed via {@link java.time.temporal.TemporalAccessor TemporalAccessor} and 271c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.temporal.Temporal Temporal} provide considerable flexibility to applications. 272c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * In addition, the {@link java.time.temporal.TemporalQuery TemporalQuery} and 273c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * {@link java.time.temporal.TemporalAdjuster TemporalAdjuster} interfaces provide day-to-day 274c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * power, allowing code to read close to business requirements: 275c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </p> 276c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * <pre> 277c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * LocalDate customerBirthday = customer.loadBirthdayFromDatabase(); 278c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * LocalDate today = LocalDate.now(); 279c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * if (customerBirthday.equals(today)) { 280c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * LocalDate specialOfferExpiryDate = today.plusWeeks(2).with(next(FRIDAY)); 281c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * customer.sendBirthdaySpecialOffer(specialOfferExpiryDate); 282c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * } 283c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 284c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * </pre> 285c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * 286c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer * @since JDK1.8 287c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauer */ 288c9dd3385ea6f927052783f42fb1282fb093e636eJoachim Sauerpackage java.time; 289