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 }