src/share/classes/java/time/temporal/TemporalAccessor.java
Print this page
*** 77,87 ****
* a {@code long} to handle large values. Year, month and day-of-month are
* simple examples of fields, but they also include instant and offsets.
* See {@link ChronoField} for the standard set of fields.
* <p>
* Two pieces of date/time information cannot be represented by numbers,
! * the {@linkplain Chrono chronology} and the {@linkplain ZoneId time-zone}.
* These can be accessed via {@link #query(TemporalQuery) queries} using
* the static methods defined on {@link Queries}.
* <p>
* A sub-interface, {@link Temporal}, extends this definition to one that also
* supports adjustment and manipulation on more complete temporal objects.
--- 77,87 ----
* a {@code long} to handle large values. Year, month and day-of-month are
* simple examples of fields, but they also include instant and offsets.
* 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}.
* <p>
* A sub-interface, {@link Temporal}, extends this definition to one that also
* supports adjustment and manipulation on more complete temporal objects.
*** 89,99 ****
* 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
* of this interface may be in calendar systems other than ISO.
! * See {@link ChronoLocalDate} for a fuller discussion of the issues.
*
* <h3>Specification for implementors</h3>
* This interface places no restrictions on the mutability of implementations,
* however immutability is strongly recommended.
*
--- 89,99 ----
* 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
* of this interface may be in calendar systems other than ISO.
! * See {@link java.time.chrono.ChronoLocalDate} for a fuller discussion of the issues.
*
* <h3>Specification for implementors</h3>
* This interface places no restrictions on the mutability of implementations,
* however immutability is strongly recommended.
*
*** 111,121 ****
* <h3>Specification for implementors</h3>
* Implementations must check and handle all fields defined in {@link ChronoField}.
* If the field is supported, then true is returned, otherwise false
* <p>
* If the field is not a {@code ChronoField}, then the result of this method
! * is obtained by invoking {@code TemporalField.doIsSupported(TemporalAccessor)}
* passing {@code this} as the argument.
* <p>
* Implementations must not alter either this object.
*
* @param field the field to check, null returns false
--- 111,121 ----
* <h3>Specification for implementors</h3>
* Implementations must check and handle all fields defined in {@link ChronoField}.
* If the field is supported, then true is returned, otherwise false
* <p>
* If the field is not a {@code ChronoField}, then the result of this method
! * is obtained by invoking {@code TemporalField.isSupportedBy(TemporalAccessor)}
* passing {@code this} as the argument.
* <p>
* Implementations must not alter either this object.
*
* @param field the field to check, null returns false
*** 140,150 ****
* Implementations must check and handle all fields defined in {@link ChronoField}.
* If the field is supported, then the range of the field must be returned.
* If unsupported, then a {@code DateTimeException} must be thrown.
* <p>
* If the field is not a {@code ChronoField}, then the result of this method
! * is obtained by invoking {@code TemporalField.doRange(TemporalAccessorl)}
* passing {@code this} as the argument.
* <p>
* Implementations must not alter either this object.
* <p>
* The default implementation must behave equivalent to this code:
--- 140,150 ----
* Implementations must check and handle all fields defined in {@link ChronoField}.
* If the field is supported, then the range of the field must be returned.
* If unsupported, then a {@code DateTimeException} must be thrown.
* <p>
* If the field is not a {@code ChronoField}, then the result of this method
! * is obtained by invoking {@code TemporalField.rangeRefinedBy(TemporalAccessorl)}
* passing {@code this} as the argument.
* <p>
* Implementations must not alter either this object.
* <p>
* The default implementation must behave equivalent to this code:
*** 153,163 ****
* if (isSupported(field)) {
* return field.range();
* }
* throw new DateTimeException("Unsupported field: " + field.getName());
* }
! * return field.doRange(this);
* </pre>
*
* @param field the field to query the range for, not null
* @return the range of valid values for the field, not null
* @throws DateTimeException if the range for the field cannot be obtained
--- 153,163 ----
* if (isSupported(field)) {
* return field.range();
* }
* throw new DateTimeException("Unsupported field: " + field.getName());
* }
! * return field.rangeRefinedBy(this);
* </pre>
*
* @param field the field to query the range for, not null
* @return the range of valid values for the field, not null
* @throws DateTimeException if the range for the field cannot be obtained
*** 167,177 ****
if (isSupported(field)) {
return field.range();
}
throw new DateTimeException("Unsupported field: " + field.getName());
}
! return field.doRange(this);
}
/**
* Gets the value of the specified field as an {@code int}.
* <p>
--- 167,177 ----
if (isSupported(field)) {
return field.range();
}
throw new DateTimeException("Unsupported field: " + field.getName());
}
! return field.rangeRefinedBy(this);
}
/**
* Gets the value of the specified field as an {@code int}.
* <p>
*** 185,195 ****
* If the field is supported and has an {@code int} range, then the value of
* the field must be returned.
* If unsupported, then a {@code DateTimeException} must be thrown.
* <p>
* If the field is not a {@code ChronoField}, then the result of this method
! * is obtained by invoking {@code TemporalField.doGet(TemporalAccessor)}
* passing {@code this} as the argument.
* <p>
* Implementations must not alter either this object.
* <p>
* The default implementation must behave equivalent to this code:
--- 185,195 ----
* If the field is supported and has an {@code int} range, then the value of
* the field must be returned.
* If unsupported, then a {@code DateTimeException} must be thrown.
* <p>
* If the field is not a {@code ChronoField}, then the result of this method
! * is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)}
* passing {@code this} as the argument.
* <p>
* Implementations must not alter either this object.
* <p>
* The default implementation must behave equivalent to this code:
*** 220,230 ****
* Implementations must check and handle all fields defined in {@link ChronoField}.
* If the field is supported, then the value of the field must be returned.
* If unsupported, then a {@code DateTimeException} must be thrown.
* <p>
* If the field is not a {@code ChronoField}, then the result of this method
! * is obtained by invoking {@code TemporalField.doGet(TemporalAccessor)}
* passing {@code this} as the argument.
* <p>
* Implementations must not alter either this object.
*
* @param field the field to get, not null
--- 220,230 ----
* Implementations must check and handle all fields defined in {@link ChronoField}.
* If the field is supported, then the value of the field must be returned.
* If unsupported, then a {@code DateTimeException} must be thrown.
* <p>
* If the field is not a {@code ChronoField}, then the result of this method
! * is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)}
* passing {@code this} as the argument.
* <p>
* Implementations must not alter either this object.
*
* @param field the field to get, not null
*** 251,261 ****
* Queries may also be defined by applications.
*
* <h3>Specification for implementors</h3>
* The default implementation must behave equivalent to this code:
* <pre>
! * if (query == Queries.zoneId() || query == Queries.chrono() || query == Queries.precision()) {
* return null;
* }
* return query.queryFrom(this);
* </pre>
* Future versions are permitted to add further queries to the if statement.
--- 251,261 ----
* Queries may also be defined by applications.
*
* <h3>Specification for implementors</h3>
* The default implementation must behave equivalent to this code:
* <pre>
! * if (query == Queries.zoneId() || query == Queries.chronology() || query == Queries.precision()) {
* return null;
* }
* return query.queryFrom(this);
* </pre>
* Future versions are permitted to add further queries to the if statement.
*** 281,291 ****
* @return the query result, null may be returned (defined by the query)
* @throws DateTimeException if unable to query
* @throws ArithmeticException if numeric overflow occurs
*/
public default <R> R query(TemporalQuery<R> query) {
! if (query == Queries.zoneId() || query == Queries.chrono() || query == Queries.precision()) {
return null;
}
return query.queryFrom(this);
}
--- 281,291 ----
* @return the query result, null may be returned (defined by the query)
* @throws DateTimeException if unable to query
* @throws ArithmeticException if numeric overflow occurs
*/
public default <R> R query(TemporalQuery<R> query) {
! if (query == Queries.zoneId() || query == Queries.chronology() || query == Queries.precision()) {
return null;
}
return query.queryFrom(this);
}