--- old/src/share/classes/java/time/temporal/Queries.java 2013-02-08 10:48:27.000000000 -0800 +++ new/src/share/classes/java/time/temporal/Queries.java 2013-02-08 10:48:26.000000000 -0800 @@ -61,10 +61,17 @@ */ package java.time.temporal; +import static java.time.temporal.ChronoField.EPOCH_DAY; +import static java.time.temporal.ChronoField.NANO_OF_DAY; import static java.time.temporal.ChronoField.OFFSET_SECONDS; +import java.time.LocalDate; +import java.time.LocalTime; +import java.time.OffsetDateTime; import java.time.ZoneId; import java.time.ZoneOffset; +import java.time.ZonedDateTime; +import java.time.chrono.Chronology; /** * Common implementations of {@code TemporalQuery}. @@ -116,9 +123,8 @@ * This queries a {@code TemporalAccessor} for the zone. * The zone is only returned if the date-time conceptually contains a {@code ZoneId}. * It will not be returned if the date-time only conceptually has an {@code ZoneOffset}. - * Thus a {@link java.time.ZonedDateTime ZonedDateTime} will return the result of - * {@code getZone()}, but an {@link java.time.temporal.OffsetDateTime OffsetDateTime} will - * return null. + * Thus a {@link ZonedDateTime} will return the result of {@code getZone()}, + * but an {@link OffsetDateTime} will return null. *
* In most cases, applications should use {@link #ZONE} as this query is too strict. *
@@ -127,7 +133,6 @@
* {@code LocalTime} returns null
* This queries a {@code TemporalAccessor} for the chronology.
* If the target {@code TemporalAccessor} represents a date, or part of a date,
@@ -163,39 +166,36 @@
* {@code LocalTime}, will return null.
*
* The result from JDK classes implementing {@code TemporalAccessor} is as follows:
- * The method {@link Chrono#from(TemporalAccessor)} can be used as a
- * {@code TemporalQuery} via a method reference, {@code Chrono::from}.
+ * The method {@link Chronology#from(TemporalAccessor)} can be used as a
+ * {@code TemporalQuery} via a method reference, {@code Chronology::from}.
* That method is equivalent to this query, except that it throws an
* exception if a chronology cannot be obtained.
- * @return a Chrono, may be null
+ *
+ * @return a query that can obtain the chronology of a temporal, not null
*/
- public static final TemporalQuery
* In most cases, applications should use this query rather than {@code #zoneId()}.
*
- * This query examines the {@link java.time.temporal.ChronoField#OFFSET_SECONDS offset-seconds}
- * field and uses it to create a {@code ZoneOffset}.
- *
* The method {@link ZoneId#from(TemporalAccessor)} can be used as a
* {@code TemporalQuery} via a method reference, {@code ZoneId::from}.
* That method is equivalent to this query, except that it throws an
* exception if a zone cannot be obtained.
- * @return a ZoneId, may be null
+ *
+ * @return a query that can obtain the zone ID or offset of a temporal, not null
*/
public static final TemporalQuery
- * This queries a {@code TemporalAccessor} for the offset.
+ * This returns a {@code TemporalQuery} that can be used to query a temporal
+ * object for the offset. The query will return null if the temporal
+ * object cannot supply an offset.
*
- * This query examines the {@link java.time.temporal.ChronoField#OFFSET_SECONDS offset-seconds}
+ * The query implementation examines the {@link ChronoField#OFFSET_SECONDS OFFSET_SECONDS}
* field and uses it to create a {@code ZoneOffset}.
*
* The method {@link ZoneOffset#from(TemporalAccessor)} can be used as a
* {@code TemporalQuery} via a method reference, {@code ZoneOffset::from}.
- * That method is equivalent to this query, except that it throws an
- * exception if an offset cannot be obtained.
- * @return a ZoneOffset, may be null
+ * This query and {@code ZoneOffset::from} will return the same result if the
+ * temporal object contains an offset. If the temporal object does not contain
+ * an offset, then the method reference will throw an exception, whereas this
+ * query will return null.
+ *
+ * @return a query that can obtain the offset of a temporal, not null
*/
public static final TemporalQuery
+ * This returns a {@code TemporalQuery} that can be used to query a temporal
+ * object for the local date. The query will return null if the temporal
+ * object cannot supply a local date.
+ *
+ * The query implementation examines the {@link ChronoField#EPOCH_DAY EPOCH_DAY}
+ * field and uses it to create a {@code LocalDate}.
+ *
+ * The method {@link ZoneOffset#from(TemporalAccessor)} can be used as a
+ * {@code TemporalQuery} via a method reference, {@code LocalDate::from}.
+ * This query and {@code LocalDate::from} will return the same result if the
+ * temporal object contains a date. If the temporal object does not contain
+ * a date, then the method reference will throw an exception, whereas this
+ * query will return null.
+ *
+ * @return a query that can obtain the date of a temporal, not null
+ */
+ public static final TemporalQuery
+ * This returns a {@code TemporalQuery} that can be used to query a temporal
+ * object for the local time. The query will return null if the temporal
+ * object cannot supply a local time.
+ *
+ * The query implementation examines the {@link ChronoField#NANO_OF_DAY NANO_OF_DAY}
+ * field and uses it to create a {@code LocalTime}.
+ *
+ * The method {@link ZoneOffset#from(TemporalAccessor)} can be used as a
+ * {@code TemporalQuery} via a method reference, {@code LocalTime::from}.
+ * This query and {@code LocalTime::from} will return the same result if the
+ * temporal object contains a time. If the temporal object does not contain
+ * a time, then the method reference will throw an exception, whereas this
+ * query will return null.
+ *
+ * @return a query that can obtain the time of a temporal, not null
+ */
+ public static final TemporalQuery
* {@code LocalDateTime} returns null
* {@code ZonedDateTime} returns the associated zone
- * {@code OffsetDate} returns null
* {@code OffsetTime} returns null
* {@code OffsetDateTime} returns null
* {@code ChronoLocalDate} returns null
@@ -141,20 +146,18 @@
* {@code MonthDay} returns null
* {@code ZoneOffset} returns null
* {@code Instant} returns null
- * @return a ZoneId, may be null
+ *
+ * @return a query that can obtain the zone ID of a temporal, not null
*/
public static final TemporalQuery
- * {@code LocalDate} returns {@code ISOChrono.INSTANCE}
+ * {@code LocalDate} returns {@code IsoChronology.INSTANCE}
* {@code LocalTime} returns null (does not represent a date)
- * {@code LocalDateTime} returns {@code ISOChrono.INSTANCE}
- * {@code ZonedDateTime} returns {@code ISOChrono.INSTANCE}
- * {@code OffsetDate} returns {@code ISOChrono.INSTANCE}
+ * {@code LocalDateTime} returns {@code IsoChronology.INSTANCE}
+ * {@code ZonedDateTime} returns {@code IsoChronology.INSTANCE}
* {@code OffsetTime} returns null (does not represent a date)
- * {@code OffsetDateTime} returns {@code ISOChrono.INSTANCE}
+ * {@code OffsetDateTime} returns {@code IsoChronology.INSTANCE}
* {@code ChronoLocalDate} returns the associated chronology
* {@code ChronoLocalDateTime} returns the associated chronology
* {@code ChronoZonedDateTime} returns the associated chronology
* {@code Era} returns the associated chronology
* {@code DayOfWeek} returns null (shared across chronologies)
- * {@code Month} returns {@code ISOChrono.INSTANCE}
- * {@code Year} returns {@code ISOChrono.INSTANCE}
- * {@code YearMonth} returns {@code ISOChrono.INSTANCE}
- * {@code MonthDay} returns null {@code ISOChrono.INSTANCE}
+ * {@code Month} returns {@code IsoChronology.INSTANCE}
+ * {@code Year} returns {@code IsoChronology.INSTANCE}
+ * {@code YearMonth} returns {@code IsoChronology.INSTANCE}
+ * {@code MonthDay} returns null {@code IsoChronology.INSTANCE}
* {@code ZoneOffset} returns null (does not represent a date)
* {@code Instant} returns null (does not represent a date)
*
* {@code LocalDateTime} returns {@code NANOS}
* {@code ZonedDateTime} returns {@code NANOS}
- * {@code OffsetDate} returns {@code DAYS}
* {@code OffsetTime} returns {@code NANOS}
* {@code OffsetDateTime} returns {@code NANOS}
* {@code ChronoLocalDate} returns {@code DAYS}
@@ -229,16 +228,14 @@
* {@code MonthDay} returns null (does not represent a complete date or time)
* {@code ZoneOffset} returns null (does not represent a date or time)
* {@code Instant} returns {@code NANOS}
- * @return a ChronoUnit, may be null
+ *
+ * @return a query that can obtain the precision of a temporal, not null
*/
- public static final TemporalQuery