< prev index next >
src/java.base/share/classes/java/time/package-info.java
Print this page
*** 1,7 ****
/*
! * Copyright (c) 2012, 2015, 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
--- 1,7 ----
/*
! * Copyright (c) 2012, 2018, 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
*** 88,98 ****
* It is recommended that applications use the ISO-8601 date and time classes from
* this package across system boundaries, such as to the database or across the network.
* The calendar neutral API should be reserved for interactions with users.
* </p>
*
! * <h3>Dates and Times</h3>
* <p>
* {@link java.time.Instant} is essentially a numeric timestamp.
* The current Instant can be retrieved from a {@link java.time.Clock}.
* This is useful for logging and persistence of a point in time
* and has in the past been associated with storing the result
--- 88,98 ----
* It is recommended that applications use the ISO-8601 date and time classes from
* this package across system boundaries, such as to the database or across the network.
* The calendar neutral API should be reserved for interactions with users.
* </p>
*
! * <h2>Dates and Times</h2>
* <p>
* {@link java.time.Instant} is essentially a numeric timestamp.
* The current Instant can be retrieved from a {@link java.time.Clock}.
* This is useful for logging and persistence of a point in time
* and has in the past been associated with storing the result
*** 116,134 ****
* dates and times taking into account the {@link java.time.ZoneId}, such as 'Europe/Paris'.
* Where possible, it is recommended to use a simpler class without a time-zone.
* The widespread use of time-zones tends to add considerable complexity to an application.
* </p>
*
! * <h3>Duration and Period</h3>
* <p>
* Beyond dates and times, the API also allows the storage of periods and durations of time.
* A {@link java.time.Duration} is a simple measure of time along the time-line in nanoseconds.
* A {@link java.time.Period} expresses an amount of time in units meaningful
* to humans, such as years or days.
* </p>
*
! * <h3>Additional value types</h3>
* <p>
* {@link java.time.Month} stores a month on its own.
* This stores a single month-of-year in isolation, such as 'DECEMBER'.
* </p>
* <p>
--- 116,134 ----
* dates and times taking into account the {@link java.time.ZoneId}, such as 'Europe/Paris'.
* Where possible, it is recommended to use a simpler class without a time-zone.
* The widespread use of time-zones tends to add considerable complexity to an application.
* </p>
*
! * <h2>Duration and Period</h2>
* <p>
* Beyond dates and times, the API also allows the storage of periods and durations of time.
* A {@link java.time.Duration} is a simple measure of time along the time-line in nanoseconds.
* A {@link java.time.Period} expresses an amount of time in units meaningful
* to humans, such as years or days.
* </p>
*
! * <h2>Additional value types</h2>
* <p>
* {@link java.time.Month} stores a month on its own.
* This stores a single month-of-year in isolation, such as 'DECEMBER'.
* </p>
* <p>
*** 158,168 ****
* This stores a date-time like '2010-12-03T11:30+01:00'.
* This is sometimes found in XML messages and other forms of persistence,
* but contains less information than a full time-zone.
* </p>
*
! * <h3>Package specification</h3>
* <p>
* Unless otherwise noted, passing a null argument to a constructor or method in any class or interface
* in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.
* The Javadoc "@param" definition is used to summarise the null-behavior.
* The "@throws {@link java.lang.NullPointerException}" is not explicitly documented in each method.
--- 158,168 ----
* This stores a date-time like '2010-12-03T11:30+01:00'.
* This is sometimes found in XML messages and other forms of persistence,
* but contains less information than a full time-zone.
* </p>
*
! * <h2>Package specification</h2>
* <p>
* Unless otherwise noted, passing a null argument to a constructor or method in any class or interface
* in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.
* The Javadoc "@param" definition is used to summarise the null-behavior.
* The "@throws {@link java.lang.NullPointerException}" is not explicitly documented in each method.
*** 170,180 ****
* <p>
* All calculations should check for numeric overflow and throw either an {@link java.lang.ArithmeticException}
* or a {@link java.time.DateTimeException}.
* </p>
*
! * <h3>Design notes (non normative)</h3>
* <p>
* The API has been designed to reject null early and to be clear about this behavior.
* A key exception is any method that takes an object and returns a boolean, for the purpose
* of checking or validating, will generally return false for null.
* </p>
--- 170,180 ----
* <p>
* All calculations should check for numeric overflow and throw either an {@link java.lang.ArithmeticException}
* or a {@link java.time.DateTimeException}.
* </p>
*
! * <h2>Design notes (non normative)</h2>
* <p>
* The API has been designed to reject null early and to be clear about this behavior.
* A key exception is any method that takes an object and returns a boolean, for the purpose
* of checking or validating, will generally return false for null.
* </p>
< prev index next >