1 /*
   2  * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /*
  27  * This file is available under and governed by the GNU General Public
  28  * License version 2 only, as published by the Free Software Foundation.
  29  * However, the following notice accompanied the original version of this
  30  * file:
  31  *
  32  * Copyright (c) 2012, Stephen Colebourne & Michael Nascimento Santos
  33  *
  34  * All rights reserved.
  35  *
  36  * Redistribution and use in source and binary forms, with or without
  37  * modification, are permitted provided that the following conditions are met:
  38  *
  39  *  * Redistributions of source code must retain the above copyright notice,
  40  *    this list of conditions and the following disclaimer.
  41  *
  42  *  * Redistributions in binary form must reproduce the above copyright notice,
  43  *    this list of conditions and the following disclaimer in the documentation
  44  *    and/or other materials provided with the distribution.
  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.
 108      * For example, in the field 'MonthOfYear', the unit is 'Months'.
 109      * See also {@link #getRangeUnit()}.
 110      *
 111      * @return the period unit defining the base unit of the field, not null
 112      */
 113     TemporalUnit getBaseUnit();
 114 
 115     /**
 116      * Gets the range that the field is bound by.
 117      * <p>
 118      * The range of the field is the period that the field varies within.
 119      * For example, in the field 'MonthOfYear', the range is 'Years'.
 120      * See also {@link #getBaseUnit()}.
 121      * <p>
 122      * The range is never null. For example, the 'Year' field is shorthand for
 123      * 'YearOfForever'. It therefore has a unit of 'Years' and a range of 'Forever'.
 124      *
 125      * @return the period unit defining the range of the field, not null
 126      */
 127     TemporalUnit getRangeUnit();
 128 
 129     //-----------------------------------------------------------------------
 130     /**
 131      * Compares the value of this field in two temporal objects.
 132      * <p>
 133      * All fields implement {@link Comparator} on {@link TemporalAccessor}.
 134      * This allows a list of date-times to be compared using the value of a field.
 135      * For example, you could sort a list of arbitrary temporal objects by the value of
 136      * the month-of-year field - {@code Collections.sort(list, MONTH_OF_YEAR)}
 137      * <p>
 138      * The default implementation must behave equivalent to this code:
 139      * <pre>
 140      *  return Long.compare(temporal1.getLong(this), temporal2.getLong(this));
 141      * </pre>
 142      *
 143      * @param temporal1  the first temporal object to compare, not null
 144      * @param temporal2  the second temporal object to compare, not null
 145      * @throws DateTimeException if unable to obtain the value for this field
 146      */
 147     public default int compare(TemporalAccessor temporal1, TemporalAccessor temporal2) {
 148          return Long.compare(temporal1.getLong(this), temporal2.getLong(this));
 149     }
 150 
 151     /**
 152      * Gets the range of valid values for the field.
 153      * <p>
 154      * All fields can be expressed as a {@code long} integer.
 155      * This method returns an object that describes the valid range for that value.
 156      * This method is generally only applicable to the ISO-8601 calendar system.
 157      * <p>
 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 }