* The most common implementations are method references, such as * {@code LocalDate::from} and {@code ZoneId::from}. - * Further implementations are on {@link Queries}. - * Queries may also be defined by applications. + * Additional common implementations are provided on this interface as static methods. * *
* The input temporal object may be in a calendar system other than ISO. * Implementations may choose to document compatibility with other calendar systems, - * or reject non-ISO temporal objects by {@link Queries#chronology() querying the chronology}. + * or reject non-ISO temporal objects by {@link TemporalQuery#chronology() querying the chronology}. *
* This method may be called from multiple threads in parallel. * It must be thread-safe when invoked. @@ -141,4 +145,214 @@ */ R queryFrom(TemporalAccessor temporal); + //----------------------------------------------------------------------- + // special constants should be used to extract information from a TemporalAccessor + // that cannot be derived in other ways + // Javadoc added here, so as to pretend they are more normal than they really are + + /** + * A strict query for the {@code ZoneId}. + *
+ * 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} will return the result of {@code getZone()}, + * but an {@link java.time.OffsetDateTime} will return null. + *
+ * In most cases, applications should use {@link #zone()} as this query is too strict. + *
+ * The result from JDK classes implementing {@code TemporalAccessor} is as follows:
+ * This queries a {@code TemporalAccessor} for the chronology.
+ * If the target {@code TemporalAccessor} represents a date, or part of a date,
+ * then it should return the chronology that the date is expressed in.
+ * As a result of this definition, objects only representing time, such as
+ * {@code LocalTime}, will return null.
+ *
+ * The result from JDK classes implementing {@code TemporalAccessor} is as follows:
+ * The method {@link java.time.chrono.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 query that can obtain the chronology of a temporal, not null
+ */
+ static TemporalQuery
+ * This queries a {@code TemporalAccessor} for the time precision.
+ * If the target {@code TemporalAccessor} represents a consistent or complete date-time,
+ * date or time then this must return the smallest precision actually supported.
+ * Note that fields such as {@code NANO_OF_DAY} and {@code NANO_OF_SECOND}
+ * are defined to always return ignoring the precision, thus this is the only
+ * way to find the actual smallest supported unit.
+ * For example, were {@code GregorianCalendar} to implement {@code TemporalAccessor}
+ * it would return a precision of {@code MILLIS}.
+ *
+ * The result from JDK classes implementing {@code TemporalAccessor} is as follows:
+ * This queries a {@code TemporalAccessor} for the zone.
+ * It first tries to obtain the zone, using {@link #zoneId()}.
+ * If that is not found it tries to obtain the {@link #offset()}.
+ * Thus a {@link java.time.ZonedDateTime} will return the result of {@code getZone()},
+ * while an {@link java.time.OffsetDateTime} will return the result of {@code getOffset()}.
+ *
+ * In most cases, applications should use this query rather than {@code #zoneId()}.
+ *
+ * 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 query that can obtain the zone ID or offset of a temporal, not null
+ */
+ static TemporalQuery
+ * 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.
+ *
+ * The query implementation examines the {@link ChronoField#OFFSET_SECONDS OFFSET_SECONDS}
+ * field and uses it to create a {@code ZoneOffset}.
+ *
+ * The method {@link java.time.ZoneOffset#from(TemporalAccessor)} can be used as a
+ * {@code TemporalQuery} via a method reference, {@code ZoneOffset::from}.
+ * 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
+ */
+ static 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
+ */
+ static 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
+ */
+ static TemporalQuery
+ * {@code LocalDate} returns null
+ * {@code LocalTime} returns null
+ * {@code LocalDateTime} returns null
+ * {@code ZonedDateTime} returns the associated zone
+ * {@code OffsetTime} returns null
+ * {@code OffsetDateTime} returns null
+ * {@code ChronoLocalDate} returns null
+ * {@code ChronoLocalDateTime} returns null
+ * {@code ChronoZonedDateTime} returns the associated zone
+ * {@code Era} returns null
+ * {@code DayOfWeek} returns null
+ * {@code Month} returns null
+ * {@code Year} returns null
+ * {@code YearMonth} returns null
+ * {@code MonthDay} returns null
+ * {@code ZoneOffset} returns null
+ * {@code Instant} returns null
+ *
+ * @return a query that can obtain the zone ID of a temporal, not null
+ */
+ static TemporalQuery
+ * {@code LocalDate} returns {@code IsoChronology.INSTANCE}
+ * {@code LocalTime} returns null (does not represent a date)
+ * {@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 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 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 LocalDate} returns {@code DAYS}
+ * {@code LocalTime} returns {@code NANOS}
+ * {@code LocalDateTime} returns {@code NANOS}
+ * {@code ZonedDateTime} returns {@code NANOS}
+ * {@code OffsetTime} returns {@code NANOS}
+ * {@code OffsetDateTime} returns {@code NANOS}
+ * {@code ChronoLocalDate} returns {@code DAYS}
+ * {@code ChronoLocalDateTime} returns {@code NANOS}
+ * {@code ChronoZonedDateTime} returns {@code NANOS}
+ * {@code Era} returns {@code ERAS}
+ * {@code DayOfWeek} returns {@code DAYS}
+ * {@code Month} returns {@code MONTHS}
+ * {@code Year} returns {@code YEARS}
+ * {@code YearMonth} returns {@code MONTHS}
+ * {@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 query that can obtain the precision of a temporal, not null
+ */
+ static TemporalQuery