jdk/src/share/classes/java/time/temporal/Temporal.java
changeset 19030 32f129cb6351
parent 17474 8c100beabcc0
child 20519 eee7a92074fd
--- a/jdk/src/share/classes/java/time/temporal/Temporal.java	Thu Jul 18 10:49:08 2013 -0700
+++ b/jdk/src/share/classes/java/time/temporal/Temporal.java	Thu Jul 18 11:02:02 2013 -0700
@@ -62,7 +62,6 @@
 package java.time.temporal;
 
 import java.time.DateTimeException;
-import java.time.ZoneId;
 
 /**
  * Framework-level interface defining read-write access to a temporal object,
@@ -81,7 +80,8 @@
  * See {@link ChronoField} for the standard set of fields.
  * <p>
  * Two pieces of date/time information cannot be represented by numbers,
- * the {@linkplain java.time.chrono.Chronology chronology} and the {@linkplain ZoneId time-zone}.
+ * the {@linkplain java.time.chrono.Chronology chronology} and the
+ * {@linkplain java.time.ZoneId time-zone}.
  * These can be accessed via {@link #query(TemporalQuery) queries} using
  * the static methods defined on {@link TemporalQuery}.
  * <p>
@@ -129,6 +129,29 @@
 public interface Temporal extends TemporalAccessor {
 
     /**
+     * Checks if the specified unit is supported.
+     * <p>
+     * This checks if the specified unit can be added to, or subtracted from, this date-time.
+     * If false, then calling the {@link #plus(long, TemporalUnit)} and
+     * {@link #minus(long, TemporalUnit) minus} methods will throw an exception.
+     *
+     * @implSpec
+     * Implementations must check and handle all units defined in {@link ChronoUnit}.
+     * If the unit is supported, then true must be returned, otherwise false must be returned.
+     * <p>
+     * If the field is not a {@code ChronoUnit}, then the result of this method
+     * is obtained by invoking {@code TemporalUnit.isSupportedBy(Temporal)}
+     * passing {@code this} as the argument.
+     * <p>
+     * Implementations must ensure that no observable state is altered when this
+     * read-only method is invoked.
+     *
+     * @param unit  the unit to check, null returns false
+     * @return true if the unit can be added/subtracted, false if not
+     */
+    boolean isSupported(TemporalUnit unit);
+
+    /**
      * Returns an adjusted object of the same type as this object with the adjustment made.
      * <p>
      * This adjusts this date-time according to the rules of the specified adjuster.
@@ -352,7 +375,7 @@
      * The start and end points are {@code this} and the specified temporal.
      * The result will be negative if the end is before the start.
      * For example, the period in hours between two temporal objects can be
-     * calculated using {@code startTime.periodUntil(endTime, HOURS)}.
+     * calculated using {@code startTime.until(endTime, HOURS)}.
      * <p>
      * The calculation returns a whole number, representing the number of
      * complete units between the two temporals.
@@ -364,7 +387,7 @@
      * The second is to use {@link TemporalUnit#between(Temporal, Temporal)}:
      * <pre>
      *   // these two lines are equivalent
-     *   temporal = start.periodUntil(end, unit);
+     *   temporal = start.until(end, unit);
      *   temporal = unit.between(start, end);
      * </pre>
      * The choice should be made based on which makes the code more readable.
@@ -372,7 +395,7 @@
      * For example, this method allows the number of days between two dates to
      * be calculated:
      * <pre>
-     *  long daysBetween = start.periodUntil(end, DAYS);
+     *  long daysBetween = start.until(end, DAYS);
      *  // or alternatively
      *  long daysBetween = DAYS.between(start, end);
      * </pre>
@@ -399,7 +422,8 @@
      *  return unit.between(this, endTemporal);
      * </pre>
      * <p>
-     * Neither this object, nor the specified temporal, may be altered.
+     * Implementations must ensure that no observable state is altered when this
+     * read-only method is invoked.
      *
      * @param endTemporal  the end temporal, of the same type as this object, not null
      * @param unit  the unit to measure the amount in, not null
@@ -410,6 +434,6 @@
      * @throws UnsupportedTemporalTypeException if the unit is not supported
      * @throws ArithmeticException if numeric overflow occurs
      */
-    long periodUntil(Temporal endTemporal, TemporalUnit unit);
+    long until(Temporal endTemporal, TemporalUnit unit);
 
 }