1 /*

     2  * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 /*

    27  * This file is available under and governed by the GNU General Public

    28  * License version 2 only, as published by the Free Software Foundation.

    29  * However, the following notice accompanied the original version of this

    30  * file:

    31  *

    32  * Copyright (c) 2012, Stephen Colebourne & Michael Nascimento Santos

    33  *

    34  * All rights reserved.

    35  *

    36  * Redistribution and use in source and binary forms, with or without

    37  * modification, are permitted provided that the following conditions are met:

    38  *

    39  *  * Redistributions of source code must retain the above copyright notice,

    40  *    this list of conditions and the following disclaimer.

    41  *

    42  *  * Redistributions in binary form must reproduce the above copyright notice,

    43  *    this list of conditions and the following disclaimer in the documentation

    44  *    and/or other materials provided with the distribution.

    45  *

    46  *  * Neither the name of JSR-310 nor the names of its contributors

    47  *    may be used to endorse or promote products derived from this software

    48  *    without specific prior written permission.

    49  *

    50  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

    51  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

    52  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

    53  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR

    54  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,

    55  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

    56  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

    57  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

    58  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

    59  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

    60  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    61  */

    62 package java.time.temporal;

    63 

    64 import java.io.Serializable;

    65 import java.time.Clock;

    66 import java.time.DateTimeException;

    67 import java.time.Instant;

    68 import java.time.LocalDate;

    69 import java.time.LocalDateTime;

    70 import java.time.ZoneId;

    71 import java.time.ZonedDateTime;

    72 import java.util.Arrays;

    73 import java.util.List;

    74 import java.util.Locale;

    75 import java.util.Objects;

    76 

    77 /**

    78  * The ISO calendar system.

    79  * <p>

    80  * This chronology defines the rules of the ISO calendar system.

    81  * This calendar system is based on the ISO-8601 standard, which is the

    82  * <i>de facto</i> world calendar.

    83  * <p>

    84  * The fields are defined as follows:

    85  * <p><ul>

    86  * <li>era - There are two eras, 'Current Era' (CE) and 'Before Current Era' (BCE).

    87  * <li>year-of-era - The year-of-era is the same as the proleptic-year for the current CE era.

    88  *  For the BCE era before the ISO epoch the year increases from 1 upwards as time goes backwards.

    89  * <li>proleptic-year - The proleptic year is the same as the year-of-era for the

    90  *  current era. For the previous era, years have zero, then negative values.

    91  * <li>month-of-year - There are 12 months in an ISO year, numbered from 1 to 12.

    92  * <li>day-of-month - There are between 28 and 31 days in each of the ISO month, numbered from 1 to 31.

    93  *  Months 4, 6, 9 and 11 have 30 days, Months 1, 3, 5, 7, 8, 10 and 12 have 31 days.

    94  *  Month 2 has 28 days, or 29 in a leap year.

    95  * <li>day-of-year - There are 365 days in a standard ISO year and 366 in a leap year.

    96  *  The days are numbered from 1 to 365 or 1 to 366.

    97  * <li>leap-year - Leap years occur every 4 years, except where the year is divisble by 100 and not divisble by 400.

    98  * </ul><p>

    99  *

   100  * <h3>Specification for implementors</h3>

   101  * This class is immutable and thread-safe.

   102  *

   103  * @since 1.8

   104  */

   105 public final class ISOChrono extends Chrono<ISOChrono> implements Serializable {

   106 

   107     /**

   108      * Singleton instance of the ISO chronology.

   109      */

   110     public static final ISOChrono INSTANCE = new ISOChrono();

   111     /**

   112      * The singleton instance for the era BCE - 'Before Current Era'.

   113      * The 'ISO' part of the name emphasizes that this differs from the BCE

   114      * era in the Gregorian calendar system.

   115      * This has the numeric value of {@code 0}.

   116      */

   117     public static final Era<ISOChrono> ERA_BCE = ISOEra.BCE;

   118     /**

   119      * The singleton instance for the era CE - 'Current Era'.

   120      * The 'ISO' part of the name emphasizes that this differs from the CE

   121      * era in the Gregorian calendar system.

   122      * This has the numeric value of {@code 1}.

   123      */

   124     public static final Era<ISOChrono> ERA_CE = ISOEra.CE;

   125 

   126     /**

   127      * Serialization version.

   128      */

   129     private static final long serialVersionUID = -1440403870442975015L;

   130 

   131     /**

   132      * Restricted constructor.

   133      */

   134     private ISOChrono() {

   135     }

   136 

   137     /**

   138      * Resolve singleton.

   139      *

   140      * @return the singleton instance, not null

   141      */

   142     private Object readResolve() {

   143         return INSTANCE;

   144     }

   145 

   146     //-----------------------------------------------------------------------

   147     /**

   148      * Gets the ID of the chronology - 'ISO'.

   149      * <p>

   150      * The ID uniquely identifies the {@code Chrono}.

   151      * It can be used to lookup the {@code Chrono} using {@link #of(String)}.

   152      *

   153      * @return the chronology ID - 'ISO'

   154      * @see #getCalendarType()

   155      */

   156     @Override

   157     public String getId() {

   158         return "ISO";

   159     }

   160 

   161     /**

   162      * Gets the calendar type of the underlying calendar system - 'iso8601'.

   163      * <p>

   164      * The calendar type is an identifier defined by the

   165      * <em>Unicode Locale Data Markup Language (LDML)</em> specification.

   166      * It can be used to lookup the {@code Chrono} using {@link #of(String)}.

   167      * It can also be used as part of a locale, accessible via

   168      * {@link Locale#getUnicodeLocaleType(String)} with the key 'ca'.

   169      *

   170      * @return the calendar system type - 'iso8601'

   171      * @see #getId()

   172      */

   173     @Override

   174     public String getCalendarType() {

   175         return "iso8601";

   176     }

   177 

   178     //-----------------------------------------------------------------------

   179     /**

   180      * Obtains an ISO local date from the era, year-of-era, month-of-year

   181      * and day-of-month fields.

   182      *

   183      * @param era  the ISO era, not null

   184      * @param yearOfEra  the ISO year-of-era

   185      * @param month  the ISO month-of-year

   186      * @param dayOfMonth  the ISO day-of-month

   187      * @return the ISO local date, not null

   188      * @throws DateTimeException if unable to create the date

   189      */

   190     @Override  // override with covariant return type

   191     public LocalDate date(Era<ISOChrono> era, int yearOfEra, int month, int dayOfMonth) {

   192         return date(prolepticYear(era, yearOfEra), month, dayOfMonth);

   193     }

   194 

   195     /**

   196      * Obtains an ISO local date from the proleptic-year, month-of-year

   197      * and day-of-month fields.

   198      * <p>

   199      * This is equivalent to {@link LocalDate#of(int, int, int)}.

   200      *

   201      * @param prolepticYear  the ISO proleptic-year

   202      * @param month  the ISO month-of-year

   203      * @param dayOfMonth  the ISO day-of-month

   204      * @return the ISO local date, not null

   205      * @throws DateTimeException if unable to create the date

   206      */

   207     @Override  // override with covariant return type

   208     public LocalDate date(int prolepticYear, int month, int dayOfMonth) {

   209         return LocalDate.of(prolepticYear, month, dayOfMonth);

   210     }

   211 

   212     /**

   213      * Obtains an ISO local date from the era, year-of-era and day-of-year fields.

   214      *

   215      * @param era  the ISO era, not null

   216      * @param yearOfEra  the ISO year-of-era

   217      * @param dayOfYear  the ISO day-of-year

   218      * @return the ISO local date, not null

   219      * @throws DateTimeException if unable to create the date

   220      */

   221     @Override  // override with covariant return type

   222     public LocalDate dateYearDay(Era<ISOChrono> era, int yearOfEra, int dayOfYear) {

   223         return dateYearDay(prolepticYear(era, yearOfEra), dayOfYear);

   224     }

   225 

   226     /**

   227      * Obtains an ISO local date from the proleptic-year and day-of-year fields.

   228      * <p>

   229      * This is equivalent to {@link LocalDate#ofYearDay(int, int)}.

   230      *

   231      * @param prolepticYear  the ISO proleptic-year

   232      * @param dayOfYear  the ISO day-of-year

   233      * @return the ISO local date, not null

   234      * @throws DateTimeException if unable to create the date

   235      */

   236     @Override  // override with covariant return type

   237     public LocalDate dateYearDay(int prolepticYear, int dayOfYear) {

   238         return LocalDate.ofYearDay(prolepticYear, dayOfYear);

   239     }

   240 

   241     //-----------------------------------------------------------------------

   242     /**

   243      * Obtains an ISO local date from another date-time object.

   244      * <p>

   245      * This is equivalent to {@link LocalDate#from(TemporalAccessor)}.

   246      *

   247      * @param temporal  the date-time object to convert, not null

   248      * @return the ISO local date, not null

   249      * @throws DateTimeException if unable to create the date

   250      */

   251     @Override  // override with covariant return type

   252     public LocalDate date(TemporalAccessor temporal) {

   253         return LocalDate.from(temporal);

   254     }

   255 

   256     /**

   257      * Obtains an ISO local date-time from another date-time object.

   258      * <p>

   259      * This is equivalent to {@link LocalDateTime#from(TemporalAccessor)}.

   260      *

   261      * @param temporal  the date-time object to convert, not null

   262      * @return the ISO local date-time, not null

   263      * @throws DateTimeException if unable to create the date-time

   264      */

   265     @Override  // override with covariant return type

   266     public LocalDateTime localDateTime(TemporalAccessor temporal) {

   267         return LocalDateTime.from(temporal);

   268     }

   269 

   270     /**

   271      * Obtains an ISO zoned date-time from another date-time object.

   272      * <p>

   273      * This is equivalent to {@link ZonedDateTime#from(TemporalAccessor)}.

   274      *

   275      * @param temporal  the date-time object to convert, not null

   276      * @return the ISO zoned date-time, not null

   277      * @throws DateTimeException if unable to create the date-time

   278      */

   279     @Override  // override with covariant return type

   280     public ZonedDateTime zonedDateTime(TemporalAccessor temporal) {

   281         return ZonedDateTime.from(temporal);

   282     }

   283 

   284     /**

   285      * Obtains an ISO zoned date-time in this chronology from an {@code Instant}.

   286      * <p>

   287      * This is equivalent to {@link ZonedDateTime#ofInstant(Instant, ZoneId)}.

   288      *

   289      * @param instant  the instant to create the date-time from, not null

   290      * @param zone  the time-zone, not null

   291      * @return the zoned date-time, not null

   292      * @throws DateTimeException if the result exceeds the supported range

   293      */

   294     public ZonedDateTime zonedDateTime(Instant instant, ZoneId zone) {

   295         return ZonedDateTime.ofInstant(instant, zone);

   296     }

   297 

   298     //-----------------------------------------------------------------------

   299     /**

   300      * Obtains the current ISO local date from the system clock in the default time-zone.

   301      * <p>

   302      * This will query the {@link Clock#systemDefaultZone() system clock} in the default

   303      * time-zone to obtain the current date.

   304      * <p>

   305      * Using this method will prevent the ability to use an alternate clock for testing

   306      * because the clock is hard-coded.

   307      *

   308      * @return the current ISO local date using the system clock and default time-zone, not null

   309      * @throws DateTimeException if unable to create the date

   310      */

   311     @Override  // override with covariant return type

   312     public LocalDate dateNow() {

   313         return dateNow(Clock.systemDefaultZone());

   314     }

   315 

   316     /**

   317      * Obtains the current ISO local date from the system clock in the specified time-zone.

   318      * <p>

   319      * This will query the {@link Clock#system(ZoneId) system clock} to obtain the current date.

   320      * Specifying the time-zone avoids dependence on the default time-zone.

   321      * <p>

   322      * Using this method will prevent the ability to use an alternate clock for testing

   323      * because the clock is hard-coded.

   324      *

   325      * @return the current ISO local date using the system clock, not null

   326      * @throws DateTimeException if unable to create the date

   327      */

   328     @Override  // override with covariant return type

   329     public LocalDate dateNow(ZoneId zone) {

   330         return dateNow(Clock.system(zone));

   331     }

   332 

   333     /**

   334      * Obtains the current ISO local date from the specified clock.

   335      * <p>

   336      * This will query the specified clock to obtain the current date - today.

   337      * Using this method allows the use of an alternate clock for testing.

   338      * The alternate clock may be introduced using {@link Clock dependency injection}.

   339      *

   340      * @param clock  the clock to use, not null

   341      * @return the current ISO local date, not null

   342      * @throws DateTimeException if unable to create the date

   343      */

   344     @Override  // override with covariant return type

   345     public LocalDate dateNow(Clock clock) {

   346         Objects.requireNonNull(clock, "clock");

   347         return date(LocalDate.now(clock));

   348     }

   349 

   350     //-----------------------------------------------------------------------

   351     /**

   352      * Checks if the year is a leap year, according to the ISO proleptic

   353      * calendar system rules.

   354      * <p>

   355      * This method applies the current rules for leap years across the whole time-line.

   356      * In general, a year is a leap year if it is divisible by four without

   357      * remainder. However, years divisible by 100, are not leap years, with

   358      * the exception of years divisible by 400 which are.

   359      * <p>

   360      * For example, 1904 is a leap year it is divisible by 4.

   361      * 1900 was not a leap year as it is divisible by 100, however 2000 was a

   362      * leap year as it is divisible by 400.

   363      * <p>

   364      * The calculation is proleptic - applying the same rules into the far future and far past.

   365      * This is historically inaccurate, but is correct for the ISO-8601 standard.

   366      *

   367      * @param prolepticYear  the ISO proleptic year to check

   368      * @return true if the year is leap, false otherwise

   369      */

   370     @Override

   371     public boolean isLeapYear(long prolepticYear) {

   372         return ((prolepticYear & 3) == 0) && ((prolepticYear % 100) != 0 || (prolepticYear % 400) == 0);

   373     }

   374 

   375     @Override

   376     public int prolepticYear(Era<ISOChrono> era, int yearOfEra) {

   377         if (era instanceof ISOEra == false) {

   378             throw new DateTimeException("Era must be ISOEra");

   379         }

   380         return (era == ISOEra.CE ? yearOfEra : 1 - yearOfEra);

   381     }

   382 

   383     @Override

   384     public Era<ISOChrono> eraOf(int eraValue) {

   385         return ISOEra.of(eraValue);

   386     }

   387 

   388     @Override

   389     public List<Era<ISOChrono>> eras() {

   390         return Arrays.<Era<ISOChrono>>asList(ISOEra.values());

   391     }

   392 

   393     //-----------------------------------------------------------------------

   394     @Override

   395     public ValueRange range(ChronoField field) {

   396         return field.range();

   397     }

   398 

   399 }