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

Print this page




  76  * The first is to invoke the method on this interface directly.
  77  * The second is to use {@link Temporal#with(TemporalAdjuster)}:
  78  * <pre>
  79  *   // these two lines are equivalent, but the second approach is recommended
  80  *   temporal = thisAdjuster.adjustInto(temporal);
  81  *   temporal = temporal.with(thisAdjuster);
  82  * </pre>
  83  * It is recommended to use the second approach, {@code with(TemporalAdjuster)},
  84  * as it is a lot clearer to read in code.
  85  * <p>
  86  * See {@link Adjusters} for a standard set of adjusters, including finding the
  87  * last day of the month.
  88  * Adjusters may also be defined by applications.
  89  *
  90  * <h3>Specification for implementors</h3>
  91  * This interface places no restrictions on the mutability of implementations,
  92  * however immutability is strongly recommended.
  93  *
  94  * @since 1.8
  95  */

  96 public interface TemporalAdjuster {
  97 
  98     /**
  99      * Adjusts the specified temporal object.
 100      * <p>
 101      * This adjusts the specified temporal object using the logic
 102      * encapsulated in the implementing class.
 103      * Examples might be an adjuster that sets the date avoiding weekends, or one that
 104      * sets the date to the last day of the month.
 105      * <p>
 106      * There are two equivalent ways of using this method.
 107      * The first is to invoke this method directly.
 108      * The second is to use {@link Temporal#with(TemporalAdjuster)}:
 109      * <pre>
 110      *   // these two lines are equivalent, but the second approach is recommended
 111      *   temporal = thisAdjuster.adjustInto(temporal);
 112      *   temporal = temporal.with(thisAdjuster);
 113      * </pre>
 114      * It is recommended to use the second approach, {@code with(TemporalAdjuster)},
 115      * as it is a lot clearer to read in code.
 116      *
 117      * <h3>Specification for implementors</h3>
 118      * The implementation must take the input object and adjust it.
 119      * The implementation defines the logic of the adjustment and is responsible for
 120      * documenting that logic. It may use any method on {@code Temporal} to
 121      * query the temporal object and perform the adjustment.
 122      * The returned object must have the same observable type as the input object
 123      * <p>
 124      * The input object must not be altered.
 125      * Instead, an adjusted copy of the original must be returned.
 126      * This provides equivalent, safe behavior for immutable and mutable temporal objects.
 127      * <p>
 128      * The input temporal object may be in a calendar system other than ISO.
 129      * Implementations may choose to document compatibility with other calendar systems,
 130      * or reject non-ISO temporal objects by {@link Queries#chrono() querying the chronology}.
 131      * <p>
 132      * This method may be called from multiple threads in parallel.
 133      * It must be thread-safe when invoked.
 134      *
 135      * @param temporal  the temporal object to adjust, not null
 136      * @return an object of the same observable type with the adjustment made, not null
 137      * @throws DateTimeException if unable to make the adjustment
 138      * @throws ArithmeticException if numeric overflow occurs
 139      */
 140     Temporal adjustInto(Temporal temporal);
 141 
 142 }


  76  * The first is to invoke the method on this interface directly.
  77  * The second is to use {@link Temporal#with(TemporalAdjuster)}:
  78  * <pre>
  79  *   // these two lines are equivalent, but the second approach is recommended
  80  *   temporal = thisAdjuster.adjustInto(temporal);
  81  *   temporal = temporal.with(thisAdjuster);
  82  * </pre>
  83  * It is recommended to use the second approach, {@code with(TemporalAdjuster)},
  84  * as it is a lot clearer to read in code.
  85  * <p>
  86  * See {@link Adjusters} for a standard set of adjusters, including finding the
  87  * last day of the month.
  88  * Adjusters may also be defined by applications.
  89  *
  90  * <h3>Specification for implementors</h3>
  91  * This interface places no restrictions on the mutability of implementations,
  92  * however immutability is strongly recommended.
  93  *
  94  * @since 1.8
  95  */
  96 @FunctionalInterface
  97 public interface TemporalAdjuster {
  98 
  99     /**
 100      * Adjusts the specified temporal object.
 101      * <p>
 102      * This adjusts the specified temporal object using the logic
 103      * encapsulated in the implementing class.
 104      * Examples might be an adjuster that sets the date avoiding weekends, or one that
 105      * sets the date to the last day of the month.
 106      * <p>
 107      * There are two equivalent ways of using this method.
 108      * The first is to invoke this method directly.
 109      * The second is to use {@link Temporal#with(TemporalAdjuster)}:
 110      * <pre>
 111      *   // these two lines are equivalent, but the second approach is recommended
 112      *   temporal = thisAdjuster.adjustInto(temporal);
 113      *   temporal = temporal.with(thisAdjuster);
 114      * </pre>
 115      * It is recommended to use the second approach, {@code with(TemporalAdjuster)},
 116      * as it is a lot clearer to read in code.
 117      *
 118      * <h3>Specification for implementors</h3>
 119      * The implementation must take the input object and adjust it.
 120      * The implementation defines the logic of the adjustment and is responsible for
 121      * documenting that logic. It may use any method on {@code Temporal} to
 122      * query the temporal object and perform the adjustment.
 123      * The returned object must have the same observable type as the input object
 124      * <p>
 125      * The input object must not be altered.
 126      * Instead, an adjusted copy of the original must be returned.
 127      * This provides equivalent, safe behavior for immutable and mutable temporal objects.
 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#chronology() 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 adjust, not null
 137      * @return an object of the same observable type with the adjustment made, not null
 138      * @throws DateTimeException if unable to make the adjustment
 139      * @throws ArithmeticException if numeric overflow occurs
 140      */
 141     Temporal adjustInto(Temporal temporal);
 142 
 143 }