src/share/classes/java/time/temporal/TemporalQuery.java

Print this page




  81  * The second is to use {@link TemporalAccessor#query(TemporalQuery)}:
  82  * <pre>
  83  *   // these two lines are equivalent, but the second approach is recommended
  84  *   temporal = thisQuery.queryFrom(temporal);
  85  *   temporal = temporal.query(thisQuery);
  86  * </pre>
  87  * It is recommended to use the second approach, {@code query(TemporalQuery)},
  88  * as it is a lot clearer to read in code.
  89  * <p>
  90  * The most common implementations are method references, such as
  91  * {@code LocalDate::from} and {@code ZoneId::from}.
  92  * Further implementations are on {@link Queries}.
  93  * Queries may also be defined by applications.
  94  *
  95  * <h3>Specification for implementors</h3>
  96  * This interface places no restrictions on the mutability of implementations,
  97  * however immutability is strongly recommended.
  98  *
  99  * @since 1.8
 100  */

 101 public interface TemporalQuery<R> {
 102 
 103     /**
 104      * Queries the specified temporal object.
 105      * <p>
 106      * This queries the specified temporal object to return an object using the logic
 107      * encapsulated in the implementing class.
 108      * Examples might be a query that checks if the date is the day before February 29th
 109      * in a leap year, or calculates the number of days to your next birthday.
 110      * <p>
 111      * There are two equivalent ways of using this method.
 112      * The first is to invoke this method directly.
 113      * The second is to use {@link TemporalAccessor#query(TemporalQuery)}:
 114      * <pre>
 115      *   // these two lines are equivalent, but the second approach is recommended
 116      *   temporal = thisQuery.queryFrom(temporal);
 117      *   temporal = temporal.query(thisQuery);
 118      * </pre>
 119      * It is recommended to use the second approach, {@code query(TemporalQuery)},
 120      * as it is a lot clearer to read in code.
 121      *
 122      * <h3>Specification for implementors</h3>
 123      * The implementation must take the input object and query it.
 124      * The implementation defines the logic of the query and is responsible for
 125      * documenting that logic.
 126      * It may use any method on {@code TemporalAccessor} to determine the result.
 127      * The input object must not be altered.
 128      * <p>
 129      * The input temporal object may be in a calendar system other than ISO.
 130      * Implementations may choose to document compatibility with other calendar systems,
 131      * or reject non-ISO temporal objects by {@link Queries#chrono() querying the chronology}.
 132      * <p>
 133      * This method may be called from multiple threads in parallel.
 134      * It must be thread-safe when invoked.
 135      *
 136      * @param temporal  the temporal object to query, not null
 137      * @return the queried value, may return null to indicate not found
 138      * @throws DateTimeException if unable to query
 139      * @throws ArithmeticException if numeric overflow occurs
 140      */
 141     R queryFrom(TemporalAccessor temporal);
 142 
 143 }


  81  * The second is to use {@link TemporalAccessor#query(TemporalQuery)}:
  82  * <pre>
  83  *   // these two lines are equivalent, but the second approach is recommended
  84  *   temporal = thisQuery.queryFrom(temporal);
  85  *   temporal = temporal.query(thisQuery);
  86  * </pre>
  87  * It is recommended to use the second approach, {@code query(TemporalQuery)},
  88  * as it is a lot clearer to read in code.
  89  * <p>
  90  * The most common implementations are method references, such as
  91  * {@code LocalDate::from} and {@code ZoneId::from}.
  92  * Further implementations are on {@link Queries}.
  93  * Queries may also be defined by applications.
  94  *
  95  * <h3>Specification for implementors</h3>
  96  * This interface places no restrictions on the mutability of implementations,
  97  * however immutability is strongly recommended.
  98  *
  99  * @since 1.8
 100  */
 101 @FunctionalInterface
 102 public interface TemporalQuery<R> {
 103 
 104     /**
 105      * Queries the specified temporal object.
 106      * <p>
 107      * This queries the specified temporal object to return an object using the logic
 108      * encapsulated in the implementing class.
 109      * Examples might be a query that checks if the date is the day before February 29th
 110      * in a leap year, or calculates the number of days to your next birthday.
 111      * <p>
 112      * There are two equivalent ways of using this method.
 113      * The first is to invoke this method directly.
 114      * The second is to use {@link TemporalAccessor#query(TemporalQuery)}:
 115      * <pre>
 116      *   // these two lines are equivalent, but the second approach is recommended
 117      *   temporal = thisQuery.queryFrom(temporal);
 118      *   temporal = temporal.query(thisQuery);
 119      * </pre>
 120      * It is recommended to use the second approach, {@code query(TemporalQuery)},
 121      * as it is a lot clearer to read in code.
 122      *
 123      * <h3>Specification for implementors</h3>
 124      * The implementation must take the input object and query it.
 125      * The implementation defines the logic of the query and is responsible for
 126      * documenting that logic.
 127      * It may use any method on {@code TemporalAccessor} to determine the result.
 128      * The input object must not be altered.
 129      * <p>
 130      * The input temporal object may be in a calendar system other than ISO.
 131      * Implementations may choose to document compatibility with other calendar systems,
 132      * or reject non-ISO temporal objects by {@link Queries#chronology() querying the chronology}.
 133      * <p>
 134      * This method may be called from multiple threads in parallel.
 135      * It must be thread-safe when invoked.
 136      *
 137      * @param temporal  the temporal object to query, not null
 138      * @return the queried value, may return null to indicate not found
 139      * @throws DateTimeException if unable to query
 140      * @throws ArithmeticException if numeric overflow occurs
 141      */
 142     R queryFrom(TemporalAccessor temporal);
 143 
 144 }