1 /* 2 * Copyright (c) 2007-present, Stephen Colebourne & Michael Nascimento Santos 3 * 4 * All rights reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions are met: 8 * 9 * * Redistributions of source code must retain the above copyright notice, 10 * this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright notice, 13 * this list of conditions and the following disclaimer in the documentation 14 * and/or other materials provided with the distribution. 15 * 16 * * Neither the name of JSR-310 nor the names of its contributors 17 * may be used to endorse or promote products derived from this software 18 * without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 23 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 27 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 28 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 29 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 package org.threeten.bp.temporal; 33 34 import java.util.List; 35 36 import org.threeten.bp.DateTimeException; 37 import org.threeten.bp.Duration; 38 import org.threeten.bp.Period; 39 40 /** 41 * Framework-level interface defining an amount of time, 42 * such as "6 hours", "8 days" or "2 years and 3 months". 43 * <p> 44 * This is the base interface type for amounts of time. 45 * An amount is distinct from a date or time-of-day in that it is not tied 46 * to any specific point on the time-line. 47 * <p> 48 * The amount can be thought of as a Map of {@code TemporalUnit} to long, 49 * exposed via {@link #getUnits()} and {@link #get(TemporalUnit)}. 50 * A simple case might have a single unit-value pair, such as "6 hours". 51 * A more complex case may have multiple unit-value pairs, such as "7 years, 3 months and 5 days". 52 * <p> 53 * There are two common implementations. 54 * {@link Period} is a date-based implementation, storing years, months and days. 55 * {@link Duration} is a time-based implementation, storing seconds and 56 * nanoseconds, but providing some access using other duration based units 57 * such as minutes, hours and fixed 24-hour days. 58 * <p> 59 * This interface is a framework-level interface that should not be widely used 60 * in application code. Instead, applications should create and pass around 61 * instances of concrete types, such as {@code Period} and {@code Duration}. 62 * 63 * <h3>Specification for implementors</h3> 64 * This interface places no restrictions on the mutability of implementations, 65 * however immutability is strongly recommended. 66 */ 67 public interface TemporalAmount { 68 69 /** 70 * Gets the list of units, from largest to smallest, that fully define this amount. 71 * 72 * @return the list of units. 73 */ getUnits()74 List<TemporalUnit> getUnits(); 75 76 /** 77 * Gets the amount associated with the specified unit. 78 * 79 * @param unit the unit to get, not null 80 * @return the amount of the unit 81 * @throws DateTimeException if the amount cannot be obtained 82 */ get(TemporalUnit unit)83 long get(TemporalUnit unit); 84 85 /** 86 * Adds to the specified temporal object. 87 * <p> 88 * This adds to the specified temporal object using the logic 89 * encapsulated in the implementing class. 90 * <p> 91 * There are two equivalent ways of using this method. 92 * The first is to invoke this method directly. 93 * The second is to use {@link Temporal#plus(TemporalAmount)}: 94 * <pre> 95 * // these two lines are equivalent, but the second approach is recommended 96 * dateTime = amount.addTo(dateTime); 97 * dateTime = dateTime.plus(amount); 98 * </pre> 99 * It is recommended to use the second approach, {@code plus(TemporalAmount)}, 100 * as it is a lot clearer to read in code. 101 * 102 * <h3>Specification for implementors</h3> 103 * The implementation must take the input object and add to it. 104 * The implementation defines the logic of the addition and is responsible for 105 * documenting that logic. It may use any method on {@code Temporal} to 106 * query the temporal object and perform the addition. 107 * The returned object must have the same observable type as the input object 108 * <p> 109 * The input object must not be altered. 110 * Instead, an adjusted copy of the original must be returned. 111 * This provides equivalent, safe behavior for immutable and mutable temporal objects. 112 * <p> 113 * The input temporal object may be in a calendar system other than ISO. 114 * Implementations may choose to document compatibility with other calendar systems, 115 * or reject non-ISO temporal objects by {@link TemporalQueries#chronology() querying the chronology}. 116 * <p> 117 * This method may be called from multiple threads in parallel. 118 * It must be thread-safe when invoked. 119 * 120 * @param temporal the temporal object to adjust, not null 121 * @return an object of the same observable type with the addition made, not null 122 * @throws DateTimeException if unable to add 123 * @throws ArithmeticException if numeric overflow occurs 124 */ addTo(Temporal temporal)125 Temporal addTo(Temporal temporal); 126 127 /** 128 * Subtracts this object from the specified temporal object. 129 * <p> 130 * This adds to the specified temporal object using the logic 131 * encapsulated in the implementing class. 132 * <p> 133 * There are two equivalent ways of using this method. 134 * The first is to invoke this method directly. 135 * The second is to use {@link Temporal#minus(TemporalAmount)}: 136 * <pre> 137 * // these two lines are equivalent, but the second approach is recommended 138 * dateTime = amount.subtractFrom(dateTime); 139 * dateTime = dateTime.minus(amount); 140 * </pre> 141 * It is recommended to use the second approach, {@code minus(TemporalAmount)}, 142 * as it is a lot clearer to read in code. 143 * 144 * <h3>Specification for implementors</h3> 145 * The implementation must take the input object and subtract from it. 146 * The implementation defines the logic of the subtraction and is responsible for 147 * documenting that logic. It may use any method on {@code Temporal} to 148 * query the temporal object and perform the subtraction. 149 * The returned object must have the same observable type as the input object 150 * <p> 151 * The input object must not be altered. 152 * Instead, an adjusted copy of the original must be returned. 153 * This provides equivalent, safe behavior for immutable and mutable temporal objects. 154 * <p> 155 * The input temporal object may be in a calendar system other than ISO. 156 * Implementations may choose to document compatibility with other calendar systems, 157 * or reject non-ISO temporal objects by {@link TemporalQueries#chronology() querying the chronology}. 158 * <p> 159 * This method may be called from multiple threads in parallel. 160 * It must be thread-safe when invoked. 161 * 162 * @param temporal the temporal object to adjust, not null 163 * @return an object of the same observable type with the subtraction made, not null 164 * @throws DateTimeException if unable to subtract 165 * @throws ArithmeticException if numeric overflow occurs 166 */ subtractFrom(Temporal temporal)167 Temporal subtractFrom(Temporal temporal); 168 169 } 170