1 /*
   2  * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * Copyright (c) 2012, Stephen Colebourne & Michael Nascimento Santos
   4  *
   5  * All rights reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions are met:
   9  *
  10  *  * Redistributions of source code must retain the above copyright notice,
  11  *    this list of conditions and the following disclaimer.
  12  *
  13  *  * Redistributions in binary form must reproduce the above copyright notice,
  14  *    this list of conditions and the following disclaimer in the documentation
  15  *    and/or other materials provided with the distribution.
  16  *
  17  *  * Neither the name of JSR-310 nor the names of its contributors
  18  *    may be used to endorse or promote products derived from this software
  19  *    without specific prior written permission.
  20  *
  21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  25  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  26  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  27  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  28  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  29  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  30  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  31  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33 
  34 /**
  35  * <p>
  36  * Support for calendar systems other than the default ISO.
  37  * </p>
  38  * <p>
  39  * The main API is based around the calendar system defined in ISO-8601.
  40  * This package provides support for alternate systems.
  41  * </p>
  42  * <p>
  43  * The supported calendar systems includes:
  44  * </p>
  45  * <ul>
  46  * <li>{@link java.time.calendar.HijrahChrono Hijrah calendar}</li>
  47  * <li>{@link java.time.calendar.JapaneseChrono Japanese calendar}</li>
  48  * <li>{@link java.time.calendar.MinguoChrono Minguo calendar}</li>
  49  * <li>{@link java.time.calendar.ThaiBuddhistChrono Thai Buddhist calendar}</li>
  50  * </ul>
  51  * <p>
  52  * It is intended that applications use the main API whenever possible,
  53  * including code to read and write from a persistent data store,
  54  * such as a database, and to send dates and times across a network.
  55  * This package is then used at the user interface level to deal with
  56  * localized input/output.
  57  * See {@link java.time.temporal.ChronoLocalDate ChronoLocalDate}
  58  * for a full discussion of the issues.
  59  * </p>
  60  *
  61  * <h3>Example</h3>
  62  * <p>
  63  * This example creates and uses a date in a non-ISO calendar system.
  64  * </p>
  65  * <pre>
  66  *   // Print the Thai Buddhist date
  67  *       ChronoLocalDate&lt;ThaiBuddhistChrono&gt; now1 = ThaiBuddhistChrono.INSTANCE.dateNow();
  68  *       int day = now1.get(ChronoField.DAY_OF_MONTH);
  69  *       int dow = now1.get(ChronoField.DAY_OF_WEEK);
  70  *       int month = now1.get(ChronoField.MONTH_OF_YEAR);
  71  *       int year = now1.get(ChronoField.YEAR);
  72  *       System.out.printf("  Today is %s %s %d-%s-%d%n", now1.getChrono().getId(),
  73  *                 dow, day, month, year);
  74  *
  75  *   // Enumerate the list of available calendars and print today for each
  76  *       Set&lt;Chrono&lt;?&gt;&gt; chronos = Chrono.getAvailableChronologies();
  77  *       for (Chrono&lt;?&gt; chrono : chronos) {
  78  *         ChronoLocalDate&lt;?&gt; date = chrono.dateNow();
  79  *         System.out.printf("   %20s: %s%n", chrono.getId(), date.toString());
  80  *       }
  81  *
  82  *   // Print today's date and the last day of the year for the Thai Buddhist Calendar.
  83  *       ChronoLocalDate&lt;ThaiBuddhistChrono&gt; first = now1
  84  *                 .with(ChronoField.DAY_OF_MONTH, 1)
  85  *                 .with(ChronoField.MONTH_OF_YEAR, 1);
  86  *       ChronoLocalDate&lt;ThaiBuddhistChrono&gt; last = first
  87  *                 .plus(1, ChronoUnit.YEARS)
  88  *                 .minus(1, ChronoUnit.DAYS);
  89  *       System.out.printf("  %s: 1st of year: %s; end of year: %s%n", last.getChrono().getId(),
  90  *                 first, last);
  91  *  </pre>
  92  *
  93  * <h3>Package specification</h3>
  94  * <p>
  95  * Unless otherwise noted, passing a null argument to a constructor or method in any class or interface
  96  * in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.
  97  * The Javadoc "@param" definition is used to summarise the null-behavior.
  98  * The "@throws {@link java.lang.NullPointerException}" is not explicitly documented in each method.
  99  * </p>
 100  * <p>
 101  * All calculations should check for numeric overflow and throw either an {@link java.lang.ArithmeticException}
 102  * or a {@link java.time.DateTimeException}.
 103  * </p>
 104  * @since JDK1.8
 105  */
 106 package java.time.calendar;