src/share/classes/java/time/temporal/Temporal.java
Print this page
@@ -81,11 +81,11 @@
* 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}.
* These can be accessed via {@link #query(TemporalQuery) queries} using
- * the static methods defined on {@link Queries}.
+ * the static methods defined on {@link TemporalQuery}.
* <p>
* This interface is a framework-level interface that should not be widely
* used in application code. Instead, applications should create and pass
* around instances of concrete types, such as {@code LocalDate}.
* There are many reasons for this, part of which is that implementations
@@ -132,11 +132,11 @@
* 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.
* A simple adjuster might simply set the one of the fields, such as the year field.
* A more complex adjuster might set the date to the last day of the month.
- * A selection of common adjustments is provided in {@link Adjusters}.
+ * A selection of common adjustments is provided in {@link TemporalAdjuster}.
* These include finding the "last day of the month" and "next Wednesday".
* The adjuster is responsible for handling special cases, such as the varying
* lengths of month and leap years.
* <p>
* Some example code indicating how and why this method is used:
@@ -159,11 +159,11 @@
* @param adjuster the adjuster to use, not null
* @return an object of the same type with the specified adjustment made, not null
* @throws DateTimeException if unable to make the adjustment
* @throws ArithmeticException if numeric overflow occurs
*/
- public default Temporal with(TemporalAdjuster adjuster) {
+ default Temporal with(TemporalAdjuster adjuster) {
return adjuster.adjustInto(this);
}
/**
* Returns an object of the same type as this object with the specified field altered.
@@ -178,11 +178,11 @@
* the previous valid date, which would be the last valid day of February in this example.
*
* <h3>Specification for implementors</h3>
* Implementations must check and handle all fields defined in {@link ChronoField}.
* If the field is supported, then the adjustment must be performed.
- * If unsupported, then a {@code DateTimeException} must be thrown.
+ * If unsupported, then an {@code UnsupportedTemporalTypeException} must be thrown.
* <p>
* If the field is not a {@code ChronoField}, then the result of this method
* is obtained by invoking {@code TemporalField.adjustInto(Temporal, long)}
* passing {@code this} as the first argument.
* <p>
@@ -192,10 +192,11 @@
*
* @param field the field to set in the result, not null
* @param newValue the new value of the field in the result
* @return an object of the same type with the specified field set, not null
* @throws DateTimeException if the field cannot be set
+ * @throws UnsupportedTemporalTypeException if the field is not supported
* @throws ArithmeticException if numeric overflow occurs
*/
Temporal with(TemporalField field, long newValue);
//-----------------------------------------------------------------------
@@ -208,11 +209,10 @@
* <p>
* Some example code indicating how and why this method is used:
* <pre>
* date = date.plus(period); // add a Period instance
* date = date.plus(duration); // add a Duration instance
- * date = date.plus(MONTHS.between(start, end)); // static import of MONTHS field
* date = date.plus(workingDays(6)); // example user-written workingDays method
* </pre>
* <p>
* Note that calling {@code plus} followed by {@code minus} is not guaranteed to
* return the same date-time.
@@ -230,11 +230,11 @@
* @param amount the amount to add, not null
* @return an object of the same type with the specified adjustment made, not null
* @throws DateTimeException if the addition cannot be made
* @throws ArithmeticException if numeric overflow occurs
*/
- public default Temporal plus(TemporalAmount amount) {
+ default Temporal plus(TemporalAmount amount) {
return amount.addTo(this);
}
/**
* Returns an object of the same type as this object with the specified period added.
@@ -253,11 +253,11 @@
* For example, {@code LocalTime} must accept {@code DAYS} but not {@code WEEKS} or {@code MONTHS}.
*
* <h3>Specification for implementors</h3>
* Implementations must check and handle all units defined in {@link ChronoUnit}.
* If the unit is supported, then the addition must be performed.
- * If unsupported, then a {@code DateTimeException} must be thrown.
+ * If unsupported, then an {@code UnsupportedTemporalTypeException} must be thrown.
* <p>
* If the unit is not a {@code ChronoUnit}, then the result of this method
* is obtained by invoking {@code TemporalUnit.addTo(Temporal, long)}
* passing {@code this} as the first argument.
* <p>
@@ -267,10 +267,11 @@
*
* @param amountToAdd the amount of the specified unit to add, may be negative
* @param unit the unit of the period to add, not null
* @return an object of the same type with the specified period added, not null
* @throws DateTimeException if the unit cannot be added
+ * @throws UnsupportedTemporalTypeException if the unit is not supported
* @throws ArithmeticException if numeric overflow occurs
*/
Temporal plus(long amountToAdd, TemporalUnit unit);
//-----------------------------------------------------------------------
@@ -283,11 +284,10 @@
* <p>
* Some example code indicating how and why this method is used:
* <pre>
* date = date.minus(period); // subtract a Period instance
* date = date.minus(duration); // subtract a Duration instance
- * date = date.minus(MONTHS.between(start, end)); // static import of MONTHS field
* date = date.minus(workingDays(6)); // example user-written workingDays method
* </pre>
* <p>
* Note that calling {@code plus} followed by {@code minus} is not guaranteed to
* return the same date-time.
@@ -305,11 +305,11 @@
* @param amount the amount to subtract, not null
* @return an object of the same type with the specified adjustment made, not null
* @throws DateTimeException if the subtraction cannot be made
* @throws ArithmeticException if numeric overflow occurs
*/
- public default Temporal minus(TemporalAmount amount) {
+ default Temporal minus(TemporalAmount amount) {
return amount.subtractFrom(this);
}
/**
* Returns an object of the same type as this object with the specified period subtracted.
@@ -342,13 +342,14 @@
*
* @param amountToSubtract the amount of the specified unit to subtract, may be negative
* @param unit the unit of the period to subtract, not null
* @return an object of the same type with the specified period subtracted, not null
* @throws DateTimeException if the unit cannot be subtracted
+ * @throws UnsupportedTemporalTypeException if the unit is not supported
* @throws ArithmeticException if numeric overflow occurs
*/
- public default Temporal minus(long amountToSubtract, TemporalUnit unit) {
+ default Temporal minus(long amountToSubtract, TemporalUnit unit) {
return (amountToSubtract == Long.MIN_VALUE ? plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit));
}
//-----------------------------------------------------------------------
/**
@@ -386,11 +387,11 @@
*
* <h3>Specification for implementors</h3>
* Implementations must begin by checking to ensure that the input temporal
* object is of the same observable type as the implementation.
* They must then perform the calculation for all instances of {@link ChronoUnit}.
- * A {@code DateTimeException} must be thrown for {@code ChronoUnit}
+ * An {@code UnsupportedTemporalTypeException} must be thrown for {@code ChronoUnit}
* instances that are unsupported.
* <p>
* If the unit is not a {@code ChronoUnit}, then the result of this method
* is obtained by invoking {@code TemporalUnit.between(Temporal, Temporal)}
* passing {@code this} as the first argument and the input temporal as
@@ -399,11 +400,11 @@
* In summary, implementations must behave in a manner equivalent to this code:
* <pre>
* // check input temporal is the same type as this class
* if (unit instanceof ChronoUnit) {
* // if unit is supported, then calculate and return result
- * // else throw DateTimeException for unsupported units
+ * // else throw UnsupportedTemporalTypeException for unsupported units
* }
* return unit.between(this, endTemporal);
* </pre>
* <p>
* Neither this object, nor the specified temporal, may be altered.
@@ -412,10 +413,11 @@
* @param unit the unit to measure the period in, not null
* @return the period between this temporal object and the specified one in terms of
* the unit; positive if the specified object is later than this one, negative if
* it is earlier than this one
* @throws DateTimeException if the period cannot be calculated
+ * @throws UnsupportedTemporalTypeException if the unit is not supported
* @throws ArithmeticException if numeric overflow occurs
*/
long periodUntil(Temporal endTemporal, TemporalUnit unit);
}