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

Print this page




  45  *
  46  *  * Neither the name of JSR-310 nor the names of its contributors
  47  *    may be used to endorse or promote products derived from this software
  48  *    without specific prior written permission.
  49  *
  50  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  51  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  52  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  53  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  54  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  55  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  56  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  57  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  58  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  59  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  60  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  61  */
  62 package java.time.temporal;
  63 
  64 import java.time.DateTimeException;
  65 import java.time.format.DateTimeBuilder;
  66 import java.util.Comparator;

  67 
  68 /**
  69  * A field of date-time, such as month-of-year or hour-of-minute.
  70  * <p>
  71  * Date and time is expressed using fields which partition the time-line into something
  72  * meaningful for humans. Implementations of this interface represent those fields.
  73  * <p>
  74  * The most commonly used units are defined in {@link ChronoField}.
  75  * Further fields are supplied in {@link ISOFields}, {@link WeekFields} and {@link JulianFields}.
  76  * Fields can also be written by application code by implementing this interface.
  77  * <p>
  78  * The field works using double dispatch. Client code calls methods on a date-time like
  79  * {@code LocalDateTime} which check if the field is a {@code ChronoField}.
  80  * If it is, then the date-time must handle it.
  81  * Otherwise, the method call is re-dispatched to the matching method in this interface.
  82  *
  83  * <h3>Specification for implementors</h3>
  84  * This interface must be implemented with care to ensure other classes operate correctly.
  85  * All implementations that can be instantiated must be final, immutable and thread-safe.
  86  * It is recommended to use an enum where possible.

  87  *
  88  * @since 1.8
  89  */
  90 public interface TemporalField extends Comparator<TemporalAccessor> {
  91 
  92     /**
  93      * Gets a descriptive name for the field.
  94      * <p>
  95      * The should be of the format 'BaseOfRange', such as 'MonthOfYear',
  96      * unless the field has a range of {@code FOREVER}, when only
  97      * the base unit is mentioned, such as 'Year' or 'Era'.
  98      *
  99      * @return the name, not null
 100      */
 101     String getName();
 102 
 103     /**
 104      * Gets the unit that the field is measured in.
 105      * <p>
 106      * The unit of the field is the period that varies within the range.


 157      * Note that the result only describes the minimum and maximum valid values
 158      * and it is important not to read too much into them. For example, there
 159      * could be values within the range that are invalid for the field.
 160      *
 161      * @return the range of valid values for the field, not null
 162      */
 163     ValueRange range();
 164 
 165     //-----------------------------------------------------------------------
 166     /**
 167      * Checks if this field is supported by the temporal object.
 168      * <p>
 169      * This determines whether the temporal accessor supports this field.
 170      * If this returns false, the the temporal cannot be queried for this field.
 171      * <p>
 172      * There are two equivalent ways of using this method.
 173      * The first is to invoke this method directly.
 174      * The second is to use {@link TemporalAccessor#isSupported(TemporalField)}:
 175      * <pre>
 176      *   // these two lines are equivalent, but the second approach is recommended
 177      *   temporal = thisField.doIsSupported(temporal);
 178      *   temporal = temporal.isSupported(thisField);
 179      * </pre>
 180      * It is recommended to use the second approach, {@code isSupported(TemporalField)},
 181      * as it is a lot clearer to read in code.
 182      * <p>
 183      * Implementations should determine whether they are supported using the fields
 184      * available in {@link ChronoField}.
 185      *
 186      * @param temporal  the temporal object to query, not null
 187      * @return true if the date-time can be queried for this field, false if not
 188      */
 189     boolean doIsSupported(TemporalAccessor temporal);
 190 
 191     /**
 192      * Get the range of valid values for this field using the temporal object to
 193      * refine the result.
 194      * <p>
 195      * This uses the temporal object to find the range of valid values for the field.
 196      * This is similar to {@link #range()}, however this method refines the result
 197      * using the temporal. For example, if the field is {@code DAY_OF_MONTH} the
 198      * {@code range} method is not accurate as there are four possible month lengths,
 199      * 28, 29, 30 and 31 days. Using this method with a date allows the range to be
 200      * accurate, returning just one of those four options.
 201      * <p>
 202      * There are two equivalent ways of using this method.
 203      * The first is to invoke this method directly.
 204      * The second is to use {@link TemporalAccessor#range(TemporalField)}:
 205      * <pre>
 206      *   // these two lines are equivalent, but the second approach is recommended
 207      *   temporal = thisField.doRange(temporal);
 208      *   temporal = temporal.range(thisField);
 209      * </pre>
 210      * It is recommended to use the second approach, {@code range(TemporalField)},
 211      * as it is a lot clearer to read in code.
 212      * <p>
 213      * Implementations should perform any queries or calculations using the fields
 214      * available in {@link ChronoField}.
 215      * If the field is not supported a {@code DateTimeException} must be thrown.
 216      *
 217      * @param temporal  the temporal object used to refine the result, not null
 218      * @return the range of valid values for this field, not null
 219      * @throws DateTimeException if the range for the field cannot be obtained
 220      */
 221     ValueRange doRange(TemporalAccessor temporal);
 222 
 223     /**
 224      * Gets the value of this field from the specified temporal object.
 225      * <p>
 226      * This queries the temporal object for the value of this field.
 227      * <p>
 228      * There are two equivalent ways of using this method.
 229      * The first is to invoke this method directly.
 230      * The second is to use {@link TemporalAccessor#getLong(TemporalField)}
 231      * (or {@link TemporalAccessor#get(TemporalField)}):
 232      * <pre>
 233      *   // these two lines are equivalent, but the second approach is recommended
 234      *   temporal = thisField.doGet(temporal);
 235      *   temporal = temporal.getLong(thisField);
 236      * </pre>
 237      * It is recommended to use the second approach, {@code getLong(TemporalField)},
 238      * as it is a lot clearer to read in code.
 239      * <p>
 240      * Implementations should perform any queries or calculations using the fields
 241      * available in {@link ChronoField}.
 242      * If the field is not supported a {@code DateTimeException} must be thrown.
 243      *
 244      * @param temporal  the temporal object to query, not null
 245      * @return the value of this field, not null
 246      * @throws DateTimeException if a value for the field cannot be obtained

 247      */
 248     long doGet(TemporalAccessor temporal);
 249 
 250     /**
 251      * Returns a copy of the specified temporal object with the value of this field set.
 252      * <p>
 253      * This returns a new temporal object based on the specified one with the value for
 254      * this field changed. For example, on a {@code LocalDate}, this could be used to
 255      * set the year, month or day-of-month.
 256      * The returned object has the same observable type as the specified object.
 257      * <p>
 258      * In some cases, changing a field is not fully defined. For example, if the target object is
 259      * a date representing the 31st January, then changing the month to February would be unclear.
 260      * In cases like this, the implementation is responsible for resolving the result.
 261      * Typically it will choose the previous valid date, which would be the last valid
 262      * day of February in this example.
 263      * <p>
 264      * There are two equivalent ways of using this method.
 265      * The first is to invoke this method directly.
 266      * The second is to use {@link Temporal#with(TemporalField, long)}:
 267      * <pre>
 268      *   // these two lines are equivalent, but the second approach is recommended
 269      *   temporal = thisField.doWith(temporal);
 270      *   temporal = temporal.with(thisField);
 271      * </pre>
 272      * It is recommended to use the second approach, {@code with(TemporalField)},
 273      * as it is a lot clearer to read in code.
 274      * <p>
 275      * Implementations should perform any queries or calculations using the fields
 276      * available in {@link ChronoField}.
 277      * If the field is not supported a {@code DateTimeException} must be thrown.
 278      * <p>
 279      * Implementations must not alter the specified temporal object.
 280      * Instead, an adjusted copy of the original must be returned.
 281      * This provides equivalent, safe behavior for immutable and mutable implementations.
 282      *
 283      * @param <R>  the type of the Temporal object
 284      * @param temporal the temporal object to adjust, not null
 285      * @param newValue the new value of the field
 286      * @return the adjusted temporal object, not null
 287      * @throws DateTimeException if the field cannot be set

 288      */
 289     <R extends Temporal> R doWith(R temporal, long newValue);
 290 
 291     /**
 292      * Resolves the date/time information in the builder
 293      * <p>
 294      * This method is invoked during the resolve of the builder.
 295      * Implementations should combine the associated field with others to form
 296      * objects like {@code LocalDate}, {@code LocalTime} and {@code LocalDateTime}
 297      *
 298      * @param builder  the builder to resolve, not null
 299      * @param value  the value of the associated field
 300      * @return true if builder has been changed, false otherwise
 301      * @throws DateTimeException if unable to resolve





















 302      */
 303     boolean resolve(DateTimeBuilder builder, long value);


 304 
 305 }


  45  *
  46  *  * Neither the name of JSR-310 nor the names of its contributors
  47  *    may be used to endorse or promote products derived from this software
  48  *    without specific prior written permission.
  49  *
  50  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  51  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  52  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  53  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  54  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  55  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  56  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  57  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  58  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  59  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  60  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  61  */
  62 package java.time.temporal;
  63 
  64 import java.time.DateTimeException;

  65 import java.util.Comparator;
  66 import java.util.Map;
  67 
  68 /**
  69  * A field of date-time, such as month-of-year or hour-of-minute.
  70  * <p>
  71  * Date and time is expressed using fields which partition the time-line into something
  72  * meaningful for humans. Implementations of this interface represent those fields.
  73  * <p>
  74  * The most commonly used units are defined in {@link ChronoField}.
  75  * Further fields are supplied in {@link IsoFields}, {@link WeekFields} and {@link JulianFields}.
  76  * Fields can also be written by application code by implementing this interface.
  77  * <p>
  78  * The field works using double dispatch. Client code calls methods on a date-time like
  79  * {@code LocalDateTime} which check if the field is a {@code ChronoField}.
  80  * If it is, then the date-time must handle it.
  81  * Otherwise, the method call is re-dispatched to the matching method in this interface.
  82  *
  83  * <h3>Specification for implementors</h3>
  84  * This interface must be implemented with care to ensure other classes operate correctly.
  85  * All implementations that can be instantiated must be final, immutable and thread-safe.
  86  * Implementations should be {@code Serializable} where possible.
  87  * An enum is as effective implementation choice.
  88  *
  89  * @since 1.8
  90  */
  91 public interface TemporalField extends Comparator<TemporalAccessor> {
  92 
  93     /**
  94      * Gets a descriptive name for the field.
  95      * <p>
  96      * The should be of the format 'BaseOfRange', such as 'MonthOfYear',
  97      * unless the field has a range of {@code FOREVER}, when only
  98      * the base unit is mentioned, such as 'Year' or 'Era'.
  99      *
 100      * @return the name, not null
 101      */
 102     String getName();
 103 
 104     /**
 105      * Gets the unit that the field is measured in.
 106      * <p>
 107      * The unit of the field is the period that varies within the range.


 158      * Note that the result only describes the minimum and maximum valid values
 159      * and it is important not to read too much into them. For example, there
 160      * could be values within the range that are invalid for the field.
 161      *
 162      * @return the range of valid values for the field, not null
 163      */
 164     ValueRange range();
 165 
 166     //-----------------------------------------------------------------------
 167     /**
 168      * Checks if this field is supported by the temporal object.
 169      * <p>
 170      * This determines whether the temporal accessor supports this field.
 171      * If this returns false, the the temporal cannot be queried for this field.
 172      * <p>
 173      * There are two equivalent ways of using this method.
 174      * The first is to invoke this method directly.
 175      * The second is to use {@link TemporalAccessor#isSupported(TemporalField)}:
 176      * <pre>
 177      *   // these two lines are equivalent, but the second approach is recommended
 178      *   temporal = thisField.isSupportedBy(temporal);
 179      *   temporal = temporal.isSupported(thisField);
 180      * </pre>
 181      * It is recommended to use the second approach, {@code isSupported(TemporalField)},
 182      * as it is a lot clearer to read in code.
 183      * <p>
 184      * Implementations should determine whether they are supported using the fields
 185      * available in {@link ChronoField}.
 186      *
 187      * @param temporal  the temporal object to query, not null
 188      * @return true if the date-time can be queried for this field, false if not
 189      */
 190     boolean isSupportedBy(TemporalAccessor temporal);
 191 
 192     /**
 193      * Get the range of valid values for this field using the temporal object to
 194      * refine the result.
 195      * <p>
 196      * This uses the temporal object to find the range of valid values for the field.
 197      * This is similar to {@link #range()}, however this method refines the result
 198      * using the temporal. For example, if the field is {@code DAY_OF_MONTH} the
 199      * {@code range} method is not accurate as there are four possible month lengths,
 200      * 28, 29, 30 and 31 days. Using this method with a date allows the range to be
 201      * accurate, returning just one of those four options.
 202      * <p>
 203      * There are two equivalent ways of using this method.
 204      * The first is to invoke this method directly.
 205      * The second is to use {@link TemporalAccessor#range(TemporalField)}:
 206      * <pre>
 207      *   // these two lines are equivalent, but the second approach is recommended
 208      *   temporal = thisField.rangeRefinedBy(temporal);
 209      *   temporal = temporal.range(thisField);
 210      * </pre>
 211      * It is recommended to use the second approach, {@code range(TemporalField)},
 212      * as it is a lot clearer to read in code.
 213      * <p>
 214      * Implementations should perform any queries or calculations using the fields
 215      * available in {@link ChronoField}.
 216      * If the field is not supported a {@code DateTimeException} must be thrown.
 217      *
 218      * @param temporal  the temporal object used to refine the result, not null
 219      * @return the range of valid values for this field, not null
 220      * @throws DateTimeException if the range for the field cannot be obtained
 221      */
 222     ValueRange rangeRefinedBy(TemporalAccessor temporal);
 223 
 224     /**
 225      * Gets the value of this field from the specified temporal object.
 226      * <p>
 227      * This queries the temporal object for the value of this field.
 228      * <p>
 229      * There are two equivalent ways of using this method.
 230      * The first is to invoke this method directly.
 231      * The second is to use {@link TemporalAccessor#getLong(TemporalField)}
 232      * (or {@link TemporalAccessor#get(TemporalField)}):
 233      * <pre>
 234      *   // these two lines are equivalent, but the second approach is recommended
 235      *   temporal = thisField.getFrom(temporal);
 236      *   temporal = temporal.getLong(thisField);
 237      * </pre>
 238      * It is recommended to use the second approach, {@code getLong(TemporalField)},
 239      * as it is a lot clearer to read in code.
 240      * <p>
 241      * Implementations should perform any queries or calculations using the fields
 242      * available in {@link ChronoField}.
 243      * If the field is not supported a {@code DateTimeException} must be thrown.
 244      *
 245      * @param temporal  the temporal object to query, not null
 246      * @return the value of this field, not null
 247      * @throws DateTimeException if a value for the field cannot be obtained
 248      * @throws ArithmeticException if numeric overflow occurs
 249      */
 250     long getFrom(TemporalAccessor temporal);
 251 
 252     /**
 253      * Returns a copy of the specified temporal object with the value of this field set.
 254      * <p>
 255      * This returns a new temporal object based on the specified one with the value for
 256      * this field changed. For example, on a {@code LocalDate}, this could be used to
 257      * set the year, month or day-of-month.
 258      * The returned object has the same observable type as the specified object.
 259      * <p>
 260      * In some cases, changing a field is not fully defined. For example, if the target object is
 261      * a date representing the 31st January, then changing the month to February would be unclear.
 262      * In cases like this, the implementation is responsible for resolving the result.
 263      * Typically it will choose the previous valid date, which would be the last valid
 264      * day of February in this example.
 265      * <p>
 266      * There are two equivalent ways of using this method.
 267      * The first is to invoke this method directly.
 268      * The second is to use {@link Temporal#with(TemporalField, long)}:
 269      * <pre>
 270      *   // these two lines are equivalent, but the second approach is recommended
 271      *   temporal = thisField.adjustInto(temporal);
 272      *   temporal = temporal.with(thisField);
 273      * </pre>
 274      * It is recommended to use the second approach, {@code with(TemporalField)},
 275      * as it is a lot clearer to read in code.
 276      * <p>
 277      * Implementations should perform any queries or calculations using the fields
 278      * available in {@link ChronoField}.
 279      * If the field is not supported a {@code DateTimeException} must be thrown.
 280      * <p>
 281      * Implementations must not alter the specified temporal object.
 282      * Instead, an adjusted copy of the original must be returned.
 283      * This provides equivalent, safe behavior for immutable and mutable implementations.
 284      *
 285      * @param <R>  the type of the Temporal object
 286      * @param temporal the temporal object to adjust, not null
 287      * @param newValue the new value of the field
 288      * @return the adjusted temporal object, not null
 289      * @throws DateTimeException if the field cannot be set
 290      * @throws ArithmeticException if numeric overflow occurs
 291      */
 292     <R extends Temporal> R adjustInto(R temporal, long newValue);
 293 
 294     /**
 295      * Resolves this field to provide a simpler alternative.
 296      * <p>
 297      * This method is invoked during the resolve phase of parsing.
 298      * It is designed to allow application defined fields to be simplified into
 299      * more standard fields, such as those on {@code ChronoField}.
 300      * <p>
 301      * The method will only be invoked if the specified temporal supports this field.
 302      * The value of this field is provided.
 303      * <p>
 304      * The temporal must be queried using the methods of {@code TemporalAccessor},
 305      * not using {@code getFrom}, {@code isSupportedBy} or {@code rangeRefinedBy}.
 306      * Before querying any field, implementations must ensure it is supported, as
 307      * exceptions of this type would negatively affect the calculation of a parsed result.
 308      * <p>
 309      * If this field can resolve, it must return a map, if not it must return null.
 310      * The returned map contains the changes to be made to the temporal, expressed
 311      * as field-value pairs. If the value for a field is null, the field is to be
 312      * removed from the temporal. A null key must not be added to the result map.
 313      * <p>
 314      * If the result is non-null, this field will be removed from the temporal.
 315      * This field should not be added to the result map.
 316      * <p>
 317      * The default implementation must return null.
 318      *
 319      * @param temporal  the temporal to resolve, not null
 320      * @param value  the value of this field
 321      * @return a map of fields to update in the temporal, with a mapping to null
 322      *  indicating a deletion. The whole map must be null if no resolving occurred
 323      * @throws DateTimeException if resolving results in an error. This must not be thrown
 324      *  by querying a field on the temporal without first checking if it is supported
 325      * @throws ArithmeticException if numeric overflow occurs
 326      */
 327     public default Map<TemporalField, Long> resolve(TemporalAccessor temporal, long value) {
 328         return null;
 329     }
 330 
 331 }