OpenJDK / jdk / jdk

--- a/src/java.base/share/classes/java/time/overview.html	Mon Dec 02 09:02:17 2019 -0500
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,169 +0,0 @@
-<!--
-/*
- * 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>