1 /*

     1 /*

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

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

     4  *

     4  *

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

     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

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

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

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

    88  * It is recommended that applications use the ISO-8601 date and time classes from

    88  * It is recommended that applications use the ISO-8601 date and time classes from

    89  * this package across system boundaries, such as to the database or across the network.

    89  * this package across system boundaries, such as to the database or across the network.

    90  * The calendar neutral API should be reserved for interactions with users.

    90  * The calendar neutral API should be reserved for interactions with users.

    91  * </p>

    91  * </p>

    92  *

    92  *

    94  * <p>

    94  * <p>

    95  * {@link java.time.Instant} is essentially a numeric timestamp.

    95  * {@link java.time.Instant} is essentially a numeric timestamp.

    96  * The current Instant can be retrieved from a {@link java.time.Clock}.

    96  * The current Instant can be retrieved from a {@link java.time.Clock}.

    97  * This is useful for logging and persistence of a point in time

    97  * This is useful for logging and persistence of a point in time

    98  * and has in the past been associated with storing the result

    98  * and has in the past been associated with storing the result

   116  * dates and times taking into account the {@link java.time.ZoneId}, such as 'Europe/Paris'.

   116  * dates and times taking into account the {@link java.time.ZoneId}, such as 'Europe/Paris'.

   117  * Where possible, it is recommended to use a simpler class without a time-zone.

   117  * Where possible, it is recommended to use a simpler class without a time-zone.

   118  * The widespread use of time-zones tends to add considerable complexity to an application.

   118  * The widespread use of time-zones tends to add considerable complexity to an application.

   119  * </p>

   119  * </p>

   120  *

   120  *

   122  * <p>

   122  * <p>

   123  * Beyond dates and times, the API also allows the storage of periods and durations of time.

   123  * Beyond dates and times, the API also allows the storage of periods and durations of time.

   124  * A {@link java.time.Duration} is a simple measure of time along the time-line in nanoseconds.

   124  * A {@link java.time.Duration} is a simple measure of time along the time-line in nanoseconds.

   125  * A {@link java.time.Period} expresses an amount of time in units meaningful

   125  * A {@link java.time.Period} expresses an amount of time in units meaningful

   126  * to humans, such as years or days.

   126  * to humans, such as years or days.

   127  * </p>

   127  * </p>

   128  *

   128  *

   130  * <p>

   130  * <p>

   131  * {@link java.time.Month} stores a month on its own.

   131  * {@link java.time.Month} stores a month on its own.

   132  * This stores a single month-of-year in isolation, such as 'DECEMBER'.

   132  * This stores a single month-of-year in isolation, such as 'DECEMBER'.

   133  * </p>

   133  * </p>

   134  * <p>

   134  * <p>

   158  * This stores a date-time like '2010-12-03T11:30+01:00'.

   158  * This stores a date-time like '2010-12-03T11:30+01:00'.

   159  * This is sometimes found in XML messages and other forms of persistence,

   159  * This is sometimes found in XML messages and other forms of persistence,

   160  * but contains less information than a full time-zone.

   160  * but contains less information than a full time-zone.

   161  * </p>

   161  * </p>

   162  *

   162  *

   164  * <p>

   164  * <p>

   165  * Unless otherwise noted, passing a null argument to a constructor or method in any class or interface

   165  * Unless otherwise noted, passing a null argument to a constructor or method in any class or interface

   166  * in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.

   166  * in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.

   167  * The Javadoc "@param" definition is used to summarise the null-behavior.

   167  * The Javadoc "@param" definition is used to summarise the null-behavior.

   168  * The "@throws {@link java.lang.NullPointerException}" is not explicitly documented in each method.

   168  * The "@throws {@link java.lang.NullPointerException}" is not explicitly documented in each method.

   170  * <p>

   170  * <p>

   171  * All calculations should check for numeric overflow and throw either an {@link java.lang.ArithmeticException}

   171  * All calculations should check for numeric overflow and throw either an {@link java.lang.ArithmeticException}

   172  * or a {@link java.time.DateTimeException}.

   172  * or a {@link java.time.DateTimeException}.

   173  * </p>

   173  * </p>

   174  *

   174  *

   176  * <p>

   176  * <p>

   177  * The API has been designed to reject null early and to be clear about this behavior.

   177  * The API has been designed to reject null early and to be clear about this behavior.

   178  * A key exception is any method that takes an object and returns a boolean, for the purpose

   178  * A key exception is any method that takes an object and returns a boolean, for the purpose

   179  * of checking or validating, will generally return false for null.

   179  * of checking or validating, will generally return false for null.

   180  * </p>

   180  * </p>