src/share/classes/java/time/chrono/package-info.java
Print this page
@@ -1,7 +1,36 @@
/*
* 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) 2012, Stephen Colebourne & Michael Nascimento Santos
*
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -31,64 +60,100 @@
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/**
* <p>
- * Support for calendar systems other than the default ISO.
+ * Generic API for calendar systems other than the default ISO.
* </p>
* <p>
* The main API is based around the calendar system defined in ISO-8601.
- * This package provides support for alternate systems.
+ * However, there are other calendar systems, and this package provides basic support for them.
+ * The alternate calendars are provided in the {@link java.time.chrono} package.
+ * </p>
+ * <p>
+ * A calendar system is defined by the {@link java.time.chrono.Chronology} interface,
+ * while a date in a calendar system is defined by the {@link java.time.chrono.ChronoLocalDate} interface.
+ * </p>
+ * <p>
+ * It is intended that applications use the main API whenever possible, including code to read and write
+ * from a persistent data store, such as a database, and to send dates and times across a network.
+ * The "chrono" classes are then used at the user interface level to deal with localized input/output.
+ * See {@link java.time.chrono.ChronoLocalDate ChronoLocalDate}
+ * for a full discussion of the issues.
+ * </p>
+ * <p>
+ * Using non-ISO calendar systems in an application introduces significant extra complexity.
+ * Ensure that the warnings and recommendations in {@code ChronoLocalDate} have been read before
+ * working with the "chrono" interfaces.
* </p>
* <p>
* The supported calendar systems includes:
* </p>
* <ul>
- * <li>{@link java.time.calendar.HijrahChrono Hijrah calendar}</li>
- * <li>{@link java.time.calendar.JapaneseChrono Japanese calendar}</li>
- * <li>{@link java.time.calendar.MinguoChrono Minguo calendar}</li>
- * <li>{@link java.time.calendar.ThaiBuddhistChrono Thai Buddhist calendar}</li>
+ * <li>{@link java.time.chrono.HijrahChronology Hijrah calendar}</li>
+ * <li>{@link java.time.chrono.JapaneseChronology Japanese calendar}</li>
+ * <li>{@link java.time.chrono.MinguoChronology Minguo calendar}</li>
+ * <li>{@link java.time.chrono.ThaiBuddhistChronology Thai Buddhist calendar}</li>
* </ul>
+ *
+ * <h3>Example</h3>
* <p>
- * It is intended that applications use the main API whenever possible,
- * including code to read and write from a persistent data store,
- * such as a database, and to send dates and times across a network.
- * This package is then used at the user interface level to deal with
- * localized input/output.
- * See {@link java.time.temporal.ChronoLocalDate ChronoLocalDate}
- * for a full discussion of the issues.
+ * This example lists todays date for all of the available calendars.
* </p>
+ * <pre>
+ * // Enumerate the list of available calendars and print todays date for each.
+ * Set<Chronology> chronos = Chronology.getAvailableChronologies();
+ * for (Chronology chrono : chronos) {
+ * ChronoLocalDate<?> date = chrono.dateNow();
+ * System.out.printf(" %20s: %s%n", chrono.getId(), date.toString());
+ * }
+ * </pre>
*
- * <h3>Example</h3>
* <p>
- * This example creates and uses a date in a non-ISO calendar system.
+ * This example creates and uses a date in a named non-ISO calendar system.
* </p>
* <pre>
* // Print the Thai Buddhist date
- * ChronoLocalDate<ThaiBuddhistChrono> now1 = ThaiBuddhistChrono.INSTANCE.dateNow();
+ * ChronoLocalDate<?> now1 = Chronology.of("ThaiBuddhist").dateNow();
* int day = now1.get(ChronoField.DAY_OF_MONTH);
* int dow = now1.get(ChronoField.DAY_OF_WEEK);
* int month = now1.get(ChronoField.MONTH_OF_YEAR);
* int year = now1.get(ChronoField.YEAR);
- * System.out.printf(" Today is %s %s %d-%s-%d%n", now1.getChrono().getId(),
+ * System.out.printf(" Today is %s %s %d-%s-%d%n", now1.getChronology().getId(),
* dow, day, month, year);
+ * // Print today's date and the last day of the year for the Thai Buddhist Calendar.
+ * ChronoLocalDate<?> first = now1
+ * .with(ChronoField.DAY_OF_MONTH, 1)
+ * .with(ChronoField.MONTH_OF_YEAR, 1);
+ * ChronoLocalDate<?> last = first
+ * .plus(1, ChronoUnit.YEARS)
+ * .minus(1, ChronoUnit.DAYS);
+ * System.out.printf(" %s: 1st of year: %s; end of year: %s%n", last.getChronology().getId(),
+ * first, last);
+ * </pre>
*
- * // Enumerate the list of available calendars and print today for each
- * Set<Chrono<?>> chronos = Chrono.getAvailableChronologies();
- * for (Chrono<?> chrono : chronos) {
- * ChronoLocalDate<?> date = chrono.dateNow();
- * System.out.printf(" %20s: %s%n", chrono.getId(), date.toString());
- * }
+ * <p>
+ * This example creates and uses a date in a specific ThaiBuddhist calendar system.
+ * </p>
+ * <pre>
+ * // Print the Thai Buddhist date
+ * ThaiBuddhistDate now1 = ThaiBuddhistDate.now();
+ * int day = now1.get(ChronoField.DAY_OF_MONTH);
+ * int dow = now1.get(ChronoField.DAY_OF_WEEK);
+ * int month = now1.get(ChronoField.MONTH_OF_YEAR);
+ * int year = now1.get(ChronoField.YEAR);
+ * System.out.printf(" Today is %s %s %d-%s-%d%n", now1.getChronology().getId(),
+ * dow, day, month, year);
*
* // Print today's date and the last day of the year for the Thai Buddhist Calendar.
- * ChronoLocalDate<ThaiBuddhistChrono> first = now1
+ * ThaiBuddhistDate first = now1
* .with(ChronoField.DAY_OF_MONTH, 1)
* .with(ChronoField.MONTH_OF_YEAR, 1);
- * ChronoLocalDate<ThaiBuddhistChrono> last = first
+ * ThaiBuddhistDate last = first
* .plus(1, ChronoUnit.YEARS)
* .minus(1, ChronoUnit.DAYS);
- * System.out.printf(" %s: 1st of year: %s; end of year: %s%n", last.getChrono().getId(),
+ * System.out.printf(" %s: 1st of year: %s; end of year: %s%n", last.getChronology().getId(),
* first, last);
* </pre>
*
* <h3>Package specification</h3>
* <p>
@@ -101,6 +166,6 @@
* All calculations should check for numeric overflow and throw either an {@link java.lang.ArithmeticException}
* or a {@link java.time.DateTimeException}.
* </p>
* @since JDK1.8
*/
-package java.time.calendar;
+package java.time.chrono;