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.time.Duration;
  66 import java.time.Period;
  67 
  68 /**
  69  * A unit of date-time, such as Days or Hours.
  70  * <p>
  71  * Measurement of time is built on units, such as years, months, days, hours, minutes and seconds.
  72  * Implementations of this interface represent those units.
  73  * <p>
  74  * An instance of this interface represents the unit itself, rather than an amount of the unit.
  75  * See {@link Period} for a class that represents an amount in terms of the common units.
  76  * <p>
  77  * The most commonly used units are defined in {@link ChronoUnit}.
  78  * Further units are supplied in {@link ISOFields}.
  79  * Units can also be written by application code by implementing this interface.
  80  * <p>
  81  * The unit works using double dispatch. Client code calls methods on a date-time like
  82  * {@code LocalDateTime} which check if the unit is a {@code ChronoUnit}.
  83  * If it is, then the date-time must handle it.
  84  * Otherwise, the method call is re-dispatched to the matching method in this interface.
  85  *
  86  * <h3>Specification for implementors</h3>
  87  * This interface must be implemented with care to ensure other classes operate correctly.
  88  * All implementations that can be instantiated must be final, immutable and thread-safe.
  89  * It is recommended to use an enum where possible.
  90  *
  91  * @since 1.8
  92  */
  93 public interface TemporalUnit {
  94 
  95     /**
  96      * Gets a descriptive name for the unit.
  97      * <p>
  98      * This should be in the plural and upper-first camel case, such as 'Days' or 'Minutes'.
  99      *
 100      * @return the name, not null
 101      */
 102     String getName();
 103 
 104     /**
 105      * Gets the duration of this unit, which may be an estimate.
 106      * <p>
 107      * All units return a duration measured in standard nanoseconds from this method.
 108      * For example, an hour has a duration of {@code 60 * 60 * 1,000,000,000ns}.
 109      * <p>
 110      * Some units may return an accurate duration while others return an estimate.
 111      * For example, days have an estimated duration due to the possibility of
 112      * daylight saving time changes.
 113      * To determine if the duration is an estimate, use {@link #isDurationEstimated()}.
 114      *
 115      * @return the duration of this unit, which may be an estimate, not null
 116      */
 117     Duration getDuration();
 118 
 119     /**
 120      * Checks if the duration of the unit is an estimate.
 121      * <p>
 122      * All units have a duration, however the duration is not always accurate.
 123      * For example, days have an estimated duration due to the possibility of
 124      * daylight saving time changes.
 125      * This method returns true if the duration is an estimate and false if it is
 126      * accurate. Note that accurate/estimated ignores leap seconds.
 127      *
 128      * @return true if the duration is estimated, false if accurate
 129      */
 130     boolean isDurationEstimated();
 131 
 132     //-----------------------------------------------------------------------
 133     /**
 134      * Checks if this unit is supported by the specified temporal object.
 135      * <p>
 136      * This checks that the implementing date-time can add/subtract this unit.
 137      * This can be used to avoid throwing an exception.
 138      * <p>
 139      * This default implementation derives the value using
 140      * {@link Temporal#plus(long, TemporalUnit)}.
 141      *
 142      * @param temporal  the temporal object to check, not null
 143      * @return true if the unit is supported
 144      */
 145     public default boolean isSupported(Temporal temporal) {
 146         try {
 147             temporal.plus(1, this);
 148             return true;
 149         } catch (RuntimeException ex) {
 150             try {
 151                 temporal.plus(-1, this);
 152                 return true;
 153             } catch (RuntimeException ex2) {
 154                 return false;
 155             }
 156         }
 157     }
 158 
 159     /**
 160      * Returns a copy of the specified temporal object with the specified period added.
 161      * <p>
 162      * The period added is a multiple of this unit. For example, this method
 163      * could be used to add "3 days" to a date by calling this method on the
 164      * instance representing "days", passing the date and the period "3".
 165      * The period to be added may be negative, which is equivalent to subtraction.
 166      * <p>
 167      * There are two equivalent ways of using this method.
 168      * The first is to invoke this method directly.
 169      * The second is to use {@link Temporal#plus(long, TemporalUnit)}:
 170      * <pre>
 171      *   // these two lines are equivalent, but the second approach is recommended
 172      *   temporal = thisUnit.doPlus(temporal);
 173      *   temporal = temporal.plus(thisUnit);
 174      * </pre>
 175      * It is recommended to use the second approach, {@code plus(TemporalUnit)},
 176      * as it is a lot clearer to read in code.
 177      * <p>
 178      * Implementations should perform any queries or calculations using the units
 179      * available in {@link ChronoUnit} or the fields available in {@link ChronoField}.
 180      * If the field is not supported a {@code DateTimeException} must be thrown.
 181      * <p>
 182      * Implementations must not alter the specified temporal object.
 183      * Instead, an adjusted copy of the original must be returned.
 184      * This provides equivalent, safe behavior for immutable and mutable implementations.
 185      *
 186      * @param <R>  the type of the Temporal object
 187      * @param dateTime  the temporal object to adjust, not null
 188      * @param periodToAdd  the period of this unit to add, positive or negative
 189      * @return the adjusted temporal object, not null
 190      * @throws DateTimeException if the period cannot be added
 191      */
 192     <R extends Temporal> R doPlus(R dateTime, long periodToAdd);
 193 
 194     //-----------------------------------------------------------------------
 195     /**
 196      * Calculates the period in terms of this unit between two temporal objects of the same type.
 197      * <p>
 198      * The period will be positive if the second date-time is after the first, and
 199      * negative if the second date-time is before the first.
 200      * Call {@link SimplePeriod#abs() abs()} on the result to ensure that the result
 201      * is always positive.
 202      * <p>
 203      * The result can be queried for the {@link SimplePeriod#getAmount() amount}, the
 204      * {@link SimplePeriod#getUnit() unit} and used directly in addition/subtraction:
 205      * <pre>
 206      *  date = date.minus(MONTHS.between(start, end));
 207      * </pre>
 208      *
 209      * @param <R>  the type of the Temporal object; the two date-times must be of the same type
 210      * @param dateTime1  the base temporal object, not null
 211      * @param dateTime2  the other temporal object, not null
 212      * @return the period between datetime1 and datetime2 in terms of this unit;
 213      *      positive if datetime2 is later than datetime1, not null
 214      */
 215     <R extends Temporal> SimplePeriod between(R dateTime1, R dateTime2);
 216 
 217     //-----------------------------------------------------------------------
 218     /**
 219      * Outputs this unit as a {@code String} using the name.
 220      *
 221      * @return the name of this unit, not null
 222      */
 223     @Override
 224     String toString();
 225 
 226 }