--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.base/share/classes/java/time/overview.html Tue Sep 12 19:03:39 2017 +0200
@@ -0,0 +1,169 @@
+<!--
+/*
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * This file is available under and governed by the GNU General Public
+ * License version 2 only, as published by the Free Software Foundation.
+ * However, the following notice accompanied the original version of this
+ * file:
+ *
+ * Copyright (c) 2008-2012, Stephen Colebourne & Michael Nascimento Santos
+ *
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * * Redistributions of source code must retain the above copyright notice,
+ * this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * * Neither the name of JSR-310 nor the names of its contributors
+ * may be used to endorse or promote products derived from this software
+ * without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+-->
+<body>
+ <p>
+ A new Date and Time API for Java.
+ The design includes a relatively large number of classes and methods,
+ however each follows a common design language, especially in method prefixes.
+ Once the prefixes are understood, the API is relatively simple to comprehend.
+ </p>
+ <p>
+ The Java Time API is composed of several packages, each with a primary function:
+ </p>
+ <p>
+ {@link java.time} contains the main API based on the ISO-8601 standard.
+ The classes defined here represent the principal date-time concepts,
+ including instants, durations, dates, times, time-zones and periods.
+ They are based on the ISO calendar system, which is the <i>de facto</i> world
+ calendar following the proleptic Gregorian rules.
+ All the classes are immutable and thread-safe.
+ </p>
+ <p>
+ {@link java.time.temporal} contains the API for accessing the fields and units
+ of date-time. Units are measurable, such as years, months and hours.
+ For example, the expression "2 hours later" uses the hours unit.
+ By contrast, fields are mini-calculations, defining a value.
+ For example, month-of-year, day-of-week and hour-of-day are all fields.
+ The set of supported units and fields can be extended by applications if desired.
+ </p>
+ <p>
+ {@link java.time.format} contains the API to print and parse fields into date-time
+ objects and to customize parsing and printing.
+ Formatters can be created in a variety of ways, including constants, patterns,
+ localized styles and a builder.
+ Formatters are immutable and thread-safe.
+ </p>
+ <p>
+ {@link java.time.zone} contains the API to handle time-zones.
+ Detailed information is made available about the rules of each time-zone.
+ </p>
+ <p>
+ {@link java.time.chrono} contains the basic part of the calendar neutral API
+ and alternate calendar systems.
+ This is intended for use by applications that need to use localized calendars.
+ Support is provided for the Hijrah, Japanese, Minguo, and Thai Buddhist Calendars.
+ </p>
+ <h3>Design notes</h3>
+ <p>
+ Where possible, the API avoids the use of null.
+ All methods define whether they accept or return null in the Javadoc.
+ As a general rule, methods do not accept or return null.
+ A key exception is any method that takes an object and returns a boolean, for the purpose
+ of checking or validating, will generally return false for null.
+ </p>
+ <p>
+ The API is designed to be type-safe where reasonable in the main high-level API.
+ Thus, there are separate classes for the distinct concepts of date, time and date-time, plus variants
+ for offset and time-zones. The core 7 date-time classes, plus Instant, handle the needs of most applications.
+ Further classes handle other combinations - year, year-month and month-day in a type-safe manner.
+ </p>
+ <p>
+ In a language like Java, the use of many different types tends to cause API bloat.
+ This is handled here through the use of common method naming patterns throughout the API.
+ The common prefixes are 'of', 'get', 'is', 'with', 'plus', 'minus', 'to' and 'at'.
+ See {@link java.time.LocalDate} for an example of each of these methods.
+ </p>
+ <p>
+ Following type-safety to its logical conclusion would result in more classes, especially for time -
+ hour-minute, hour-minute-second and hour-minute-second-nanosecond.
+ While logically pure, this was not possible in practice, as the additional classes would have
+ excessively complicated the API. Notably, there would be additional combinations at the offset
+ and date-time levels, such as offset-date-hour-minute.
+ To avoid this explosion of types, {@link java.time.LocalTime} is used for all precisions of time.
+ By contrast, some additional classes were used for dates, such as {@link java.time.YearMonth}.
+ This proved necessary, as the API for year-month is significantly different to that for a date, whereas
+ an absence of nanoseconds in a time can be approximated by returning zero.
+ </p>
+ <p>
+ Similarly, full type-safety might argue for a separate class for each field in date-time,
+ such as a class for HourOfDay and another for DayOfMonth.
+ This approach was tried, but was excessively complicated in the Java language, lacking usability.
+ A similar problem occurs with periods.
+ There is a case for a separate class for each period unit, such as a type for Years and a type for Minutes.
+ However, this yields a lot of classes and a problem of type conversion.
+ As such, general access to fields and units is not wrapped in a class.
+ </p>
+ <p>
+ Multiple calendar systems is an awkward addition to the design challenges.
+ The first principal is that most users want the standard ISO calendar system.
+ As such, the main classes are ISO-only. The second principal is that most of those that want a
+ non-ISO calendar system want it for user interaction, thus it is a UI localization issue.
+ As such, date and time objects should be held as ISO objects in the data model and persistent
+ storage, only being converted to and from a local calendar for display.
+ The calendar system would be stored separately in the user preferences.
+ </p>
+ <p>
+ There are, however, some limited use cases where users believe they need to store and use
+ dates in arbitrary calendar systems throughout the application.
+ This is supported by {@link java.time.chrono.ChronoLocalDate}, however it is vital to read
+ all the associated warnings in the Javadoc of that interface before using it.
+ In summary, applications that require general interoperation between multiple calendar systems
+ typically need to be written in a very different way to those only using the ISO calendar,
+ thus most applications should just use ISO and avoid {@code ChronoLocalDate}.
+ </p>
+ <p>
+ Throughout all of this, a key goal was to allow date-time fields and units to be defined by applications.
+ This has been achieved having tried many different designs.
+ </p>
+</body>