jdk-sandbox: comparison jdk/src/share/classes/java/time/Instant.java

equal deleted inserted replaced

-:35cd9b3a98ff
+:8c100beabcc0
 * alterations to the length of the notional second. As of 2012, discussions are underway
 * to change the definition of UTC again, with the potential to remove leap seconds or
 * introduce other changes.
 * <p>
 * Given the complexity of accurate timekeeping described above, this Java API defines
-* its own time-scale with a simplification. The Java time-scale is defined as follows:
+* its own time-scale, the <i>Java Time-Scale</i>.
+* <p>
+* The Java Time-Scale divides each calendar day into exactly 86400
+* subdivisions, known as seconds.  These seconds may differ from the
+* SI second.  It closely matches the de facto international civil time
+* scale, the definition of which changes from time to time.
+* <p>
+* The Java Time-Scale has slightly different definitions for different
+* segments of the time-line, each based on the consensus international
+* time scale that is used as the basis for civil time. Whenever the
+* internationally-agreed time scale is modified or replaced, a new
+* segment of the Java Time-Scale must be defined for it.  Each segment
+* must meet these requirements:
 * <p><ul>
-* <li>midday will always be exactly as defined by the agreed international civil time</li>
+* <li>the Java Time-Scale shall closely match the underlying international
-* <li>other times during the day will be broadly in line with the agreed international civil time</li>
+*  civil time scale;</li>
-* <li>the day will be divided into exactly 86400 subdivisions, referred to as "seconds"</li>
+* <li>the Java Time-Scale shall exactly match the international civil
-* <li>the Java "second" may differ from an SI second</li>
+*  time scale at noon each day;</li>
-* <li>a well-defined algorithm must be specified to map each second in the accurate agreed
+* <li>the Java Time-Scale shall have a precisely-defined relationship to
-*  international civil time to each "second" in this time-scale</li>
+*  the international civil time scale.</li>
 * </ul><p>
-* Agreed international civil time is the base time-scale agreed by international convention,
+* There are currently, as of 2013, two segments in the Java time-scale.
-* which in 2012 is UTC (with leap-seconds).
+* <p>
-* <p>
+* For the segment from 1972-11-03 (exact boundary discussed below) until
-* In 2012, the definition of the Java time-scale is the same as UTC for all days except
+* further notice, the consensus international time scale is UTC (with
-* those where a leap-second occurs. On days where a leap-second does occur, the time-scale
+* leap seconds).  In this segment, the Java Time-Scale is identical to
-* effectively eliminates the leap-second, maintaining the fiction of 86400 seconds in the day.
-* The approved well-defined algorithm to eliminate leap-seconds is specified as
 * <a href="http://www.cl.cam.ac.uk/~mgk25/time/utc-sls/">UTC-SLS</a>.
-* <p>
+* This is identical to UTC on days that do not have a leap second.
-* UTC-SLS is a simple algorithm that smoothes the leap-second over the last 1000 seconds of
+* On days that do have a leap second, the leap second is spread equally
-* the day, making each of the last 1000 seconds 1/1000th longer or shorter than an SI second.
+* over the last 1000 seconds of the day, maintaining the appearance of
-* Implementations built on an accurate leap-second aware time source should use UTC-SLS.
+* exactly 86400 seconds per day.
-* Use of a different algorithm risks confusion and misinterpretation of instants around a
+* <p>
-* leap-second and is discouraged.
+* For the segment prior to 1972-11-03, extending back arbitrarily far,
-* <p>
+* the consensus international time scale is defined to be UT1, applied
-* The main benefit of always dividing the day into 86400 subdivisions is that it matches the
+* proleptically, which is equivalent to the (mean) solar time on the
-* expectations of most users of the API. The alternative is to force every user to understand
+* prime meridian (Greenwich). In this segment, the Java Time-Scale is
-* what a leap second is and to force them to have special logic to handle them.
+* identical to the consensus international time scale. The exact
-* Most applications do not have access to a clock that is accurate enough to record leap-seconds.
+* boundary between the two segments is the instant where UT1 = UTC
-* Most applications also do not have a problem with a second being a very small amount longer or
+* between 1972-11-03T00:00 and 1972-11-04T12:00.
-* shorter than a real SI second during a leap-second.
+* <p>
-* <p>
+* Implementations of the Java time-scale using the JSR-310 API are not
-* One final problem is the definition of the agreed international civil time before the
+* required to provide any clock that is sub-second accurate, or that
-* introduction of modern UTC in 1972. This includes the Java epoch of {@code 1970-01-01}.
+* progresses monotonically or smoothly. Implementations are therefore
-* It is intended that instants before 1972 be interpreted based on the solar day divided
+* not required to actually perform the UTC-SLS slew or to otherwise be
-* into 86400 subdivisions, as per the principles of UT1.
+* aware of leap seconds. JSR-310 does, however, require that
+* implementations must document the approach they use when defining a
+* clock representing the current instant.
+* See {@link Clock} for details on the available clocks.
 * <p>
 * The Java time-scale is used for all date-time classes.
 * This includes {@code Instant}, {@code LocalDate}, {@code LocalTime}, {@code OffsetDateTime},
 * {@code ZonedDateTime} and {@code Duration}.
 *
-* <h3>Specification for implementors</h3>
+* @implSpec
 * This class is immutable and thread-safe.
 *
 * @since 1.8
 */
 public final class Instant
 public Temporal adjustInto(Temporal temporal) {
 return temporal.with(INSTANT_SECONDS, seconds).with(NANO_OF_SECOND, nanos);
 }
 /**
-* Calculates the period between this instant and another instant in
+* Calculates the amount of time until another instant in terms of the specified unit.
-* terms of the specified unit.
+* <p>
-* <p>
+* This calculates the amount of time between two {@code Instant}
-* This calculates the period between two instants in terms of a single unit.
+* objects in terms of a single {@code TemporalUnit}.
 * The start and end points are {@code this} and the specified instant.
 * The result will be negative if the end is before the start.
 * The calculation returns a whole number, representing the number of
 * complete units between the two instants.
 * The {@code Temporal} passed to this method must be an {@code Instant}.
-* For example, the period in days between two dates can be calculated
+* For example, the amount in days between two dates can be calculated
 * using {@code startInstant.periodUntil(endInstant, SECONDS)}.
 * <p>
 * There are two equivalent ways of using this method.
 * The first is to invoke this method.
 * The second is to use {@link TemporalUnit#between(Temporal, Temporal)}:
 * passing {@code this} as the first argument and the input temporal as
 * the second argument.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
-* @param endInstant  the end date, which must be a {@code LocalDate}, not null
+* @param endInstant  the end date, which must be an {@code Instant}, not null
-* @param unit  the unit to measure the period in, not null
+* @param unit  the unit to measure the amount in, not null
-* @return the amount of the period between this date and the end date
+* @return the amount of time between this instant and the end instant
-* @throws DateTimeException if the period cannot be calculated
+* @throws DateTimeException if the amount cannot be calculated
 * @throws UnsupportedTemporalTypeException if the unit is not supported
 * @throws ArithmeticException if numeric overflow occurs
 */
 @Override
 public long periodUntil(Temporal endInstant, TemporalUnit unit) {
 if (endInstant instanceof Instant == false) {
 Objects.requireNonNull(endInstant, "endInstant");
-throw new DateTimeException("Unable to calculate period between objects of two different types");
+throw new DateTimeException("Unable to calculate amount as objects are of two different types");
 }
 Instant end = (Instant) endInstant;
 if (unit instanceof ChronoUnit) {
 ChronoUnit f = (ChronoUnit) unit;
 switch (f) {

changeset 17474	8c100beabcc0
parent 16852	60207b2b4b42
child 19030	32f129cb6351