1 <!-- 2 /* 3 * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved. 4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 * 6 * This code is free software; you can redistribute it and/or modify it 7 * under the terms of the GNU General Public License version 2 only, as 8 * published by the Free Software Foundation. Oracle designates this 9 * particular file as subject to the "Classpath" exception as provided 10 * by Oracle in the LICENSE file that accompanied this code. 11 * 12 * This code is distributed in the hope that it will be useful, but WITHOUT 13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 * version 2 for more details (a copy is included in the LICENSE file that 16 * accompanied this code). 17 * 18 * You should have received a copy of the GNU General Public License version 19 * 2 along with this work; if not, write to the Free Software Foundation, 20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 * 22 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23 * or visit www.oracle.com if you need additional information or have any 24 * questions. 25 */ 26 27 /* 28 * This file is available under and governed by the GNU General Public 29 * License version 2 only, as published by the Free Software Foundation. 30 * However, the following notice accompanied the original version of this 31 * file: 32 * 33 * Copyright (c) 2008-2012, Stephen Colebourne & Michael Nascimento Santos 34 * 35 * All rights reserved. 36 * 37 * Redistribution and use in source and binary forms, with or without 38 * modification, are permitted provided that the following conditions are met: 39 * 40 * * Redistributions of source code must retain the above copyright notice, 41 * this list of conditions and the following disclaimer. 42 * 43 * * Redistributions in binary form must reproduce the above copyright notice, 44 * this list of conditions and the following disclaimer in the documentation 45 * and/or other materials provided with the distribution. 46 * 47 * * Neither the name of JSR-310 nor the names of its contributors 48 * may be used to endorse or promote products derived from this software 49 * without specific prior written permission. 50 * 51 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 52 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 53 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 54 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 55 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 56 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 57 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 58 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 59 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 60 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 61 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 62 */ 63 --> 64 <body> 65 <p> 66 A new Date and Time API for Java. 67 The design includes a relatively large number of classes and methods, 68 however each follows a common design language, especially in method prefixes. 69 Once the prefixes are understood, the API is relatively simple to comprehend. 70 </p> 71 <p> 72 The Java Time API is composed of several packages, each with a primary function: 73 </p> 74 <p> 75 {@link java.time} contains the main API based on the ISO-8601 standard. 76 The classes defined here represent the principal date-time concepts, 77 including instants, durations, dates, times, time-zones and periods. 78 They are based on the ISO calendar system, which is the <i>de facto</i> world 79 calendar following the proleptic Gregorian rules. 80 All the classes are immutable and thread-safe. 81 </p> 82 <p> 83 {@link java.time.temporal} contains the API for accessing the fields and units 84 of date-time. Units are measurable, such as years, months and hours. 85 For example, the expression "2 hours later" uses the hours unit. 86 By contrast, fields are mini-calculations, defining a value. 87 For example, month-of-year, day-of-week and hour-of-day are all fields. 88 The set of supported units and fields can be extended by applications if desired. 89 </p> 90 <p> 91 It also contains the basic part of the calendar neutral API. 92 This is intended for use by applications that need to use localized calendars. 93 Ensure that you read the class documentation of {@link java.time.temporal.ChronoLocalDate} 94 before using non-ISO calendar systems. 95 </p> 96 <p> 97 {@link java.time.format} contains the API to print and parse fields into date-time 98 objects and to customize parsing and printing. 99 Formatters can be created in a variety of ways, including constants, patterns, 100 localized styles and a builder. 101 Formatters are immutable and thread-safe. 102 </p> 103 <p> 104 {@link java.time.zone} contains the API to handle time-zones. 105 Detailed information is made available about the rules of each time-zone. 106 </p> 107 <p> 108 The {@link java.time.calendar} package contains alternate calendar systems. 109 This is intended for use by applications that need to use localized calendars. 110 Support is provided for the Hijrah, Japanese, Minguo, and Thai Buddhist Calendars. 111 </p> 112 <h3>Design notes</h3> 113 <p> 114 Where possible, the API avoids the use of null. 115 All methods define whether they accept or return null in the Javadoc. 116 As a general rule, methods do not accept or return null. 117 A key exception is any method that takes an object and returns a boolean, for the purpose 118 of checking or validating, will generally return false for null. 119 </p> 120 <p> 121 The API is designed to be type-safe where reasonable in the main high-level API. 122 Thus, there are separate classes for the distinct concepts of date, time and date-time, plus variants 123 for offset and time-zones. The core 7 date-time classes, plus Instant, handle the needs of most applications. 124 Further classes handle other combinations - year, year-month and month-day in a type-safe manner. 125 </p> 126 <p> 127 In a language like Java, the use of many different types tends to cause API bloat. 128 This is handled here through the use of common method naming patterns throughout the API. 129 The common prefixes are 'of', 'get', 'is', 'with', 'plus', 'minus', 'to' and 'at'. 130 See {@link java.time.LocalDate} for an example of each of these methods. 131 </p> 132 <p> 133 Following type-safety to its logical conclusion would result in more classes, especially for time - 134 hour-minute, hour-minute-second and hour-minute-second-nanosecond. 135 While logically pure, this was not possible in practice, as the additional classes would have 136 excessively complicated the API. Notably, there would be additional combinations at the offset 137 and date-time levels, such as offset-date-hour-minute. 138 To avoid this explosion of types, {@link java.time.LocalTime} is used for all precisions of time. 139 By contrast, some additional classes were used for dates, such as {@link java.time.temporal.YearMonth}. 140 This proved necessary, as the API for year-month is significantly different to that for a date, whereas 141 an absence of nanoseconds in a time can be approximated by returning zero. 142 </p> 143 <p> 144 Similarly, full type-safety might argue for a separate class for each field in date-time, 145 such as a class for HourOfDay and another for DayOfMonth. 146 This approach was tried, but was excessively complicated in the Java language, lacking usability. 147 A similar problem occurs with periods. 148 There is a case for a separate class for each period unit, such as a type for Years and a type for Minutes. 149 However, this yields a lot of classes and a problem of type conversion. 150 As such, general access to fields and units is not wrapped in a class. 151 </p> 152 <p> 153 Multiple calendar systems is an awkward addition to the design challenges. 154 The first principal is that most users want the standard ISO calendar system. 155 As such, the main classes are ISO-only. The second principal is that most of those that want a 156 non-ISO calendar system want it for user interaction, thus it is a UI localization issue. 157 As such, date and time objects should be held as ISO objects in the data model and persistent 158 storage, only being converted to and from a local calendar for display. 159 The calendar system would be stored separately in the user preferences. 160 </p> 161 <p> 162 There are, however, some limited use cases where users believe they need to store and use 163 dates in arbitrary calendar systems throughout the application. 164 This is supported by {@link java.time.temporal.ChronoLocalDate}, however it is vital to read 165 all the associated warnings in the Javadoc of that interface before using it. 166 In summary, applications that require general interoperation between multiple calendar systems 167 typically need to be written in a very different way to those only using the ISO calendar, 168 thus most applications should just use ISO and avoid {@code ChronoLocalDate}. 169 </p> 170 <p> 171 Throughout all of this, a key goal was to allow date-time fields and units to be defined by applications. 172 This has been achieved having tried many different designs. 173 </p> 174 </body>