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 org.threeten.bp.DateTimeException; 35 import org.threeten.bp.ZoneId; 36 import org.threeten.bp.chrono.ChronoLocalDate; 37 import org.threeten.bp.chrono.Chronology; 38 39 /** 40 * Framework-level interface defining read-only access to a temporal object, 41 * such as a date, time, offset or some combination of these. 42 * <p> 43 * This is the base interface type for date, time and offset objects. 44 * It is implemented by those classes that can provide information 45 * as {@link TemporalField fields} or {@link TemporalQuery queries}. 46 * <p> 47 * Most date and time information can be represented as a number. 48 * These are modeled using {@code TemporalField} with the number held using 49 * a {@code long} to handle large values. Year, month and day-of-month are 50 * simple examples of fields, but they also include instant and offsets. 51 * See {@link ChronoField} for the standard set of fields. 52 * <p> 53 * Two pieces of date/time information cannot be represented by numbers, 54 * the {@link Chronology chronology} and the {@link ZoneId time-zone}. 55 * These can be accessed via {@link #query(TemporalQuery) queries} using 56 * the static methods defined on {@link TemporalQueries}. 57 * <p> 58 * A sub-interface, {@link Temporal}, extends this definition to one that also 59 * supports adjustment and manipulation on more complete temporal objects. 60 * <p> 61 * This interface is a framework-level interface that should not be widely 62 * used in application code. Instead, applications should create and pass 63 * around instances of concrete types, such as {@code LocalDate}. 64 * There are many reasons for this, part of which is that implementations 65 * of this interface may be in calendar systems other than ISO. 66 * See {@link ChronoLocalDate} for a fuller discussion of the issues. 67 * 68 * <h3>Specification for implementors</h3> 69 * This interface places no restrictions on the mutability of implementations, 70 * however immutability is strongly recommended. 71 */ 72 public interface TemporalAccessor { 73 74 /** 75 * Checks if the specified field is supported. 76 * <p> 77 * This checks if the date-time can be queried for the specified field. 78 * If false, then calling the {@link #range(TemporalField) range} and {@link #get(TemporalField) get} 79 * methods will throw an exception. 80 * 81 * <h3>Specification for implementors</h3> 82 * Implementations must check and handle all fields defined in {@link ChronoField}. 83 * If the field is supported, then true is returned, otherwise false 84 * <p> 85 * If the field is not a {@code ChronoField}, then the result of this method 86 * is obtained by invoking {@code TemporalField.isSupportedBy(TemporalAccessor)} 87 * passing {@code this} as the argument. 88 * <p> 89 * Implementations must not alter this object. 90 * 91 * @param field the field to check, null returns false 92 * @return true if this date-time can be queried for the field, false if not 93 */ isSupported(TemporalField field)94 boolean isSupported(TemporalField field); 95 96 /** 97 * Gets the range of valid values for the specified field. 98 * <p> 99 * All fields can be expressed as a {@code long} integer. 100 * This method returns an object that describes the valid range for that value. 101 * The value of this temporal object is used to enhance the accuracy of the returned range. 102 * If the date-time cannot return the range, because the field is unsupported or for 103 * some other reason, an exception will be thrown. 104 * <p> 105 * Note that the result only describes the minimum and maximum valid values 106 * and it is important not to read too much into them. For example, there 107 * could be values within the range that are invalid for the field. 108 * 109 * <h3>Specification for implementors</h3> 110 * Implementations must check and handle all fields defined in {@link ChronoField}. 111 * If the field is supported, then the range of the field must be returned. 112 * If unsupported, then a {@code DateTimeException} must be thrown. 113 * <p> 114 * If the field is not a {@code ChronoField}, then the result of this method 115 * is obtained by invoking {@code TemporalField.rangeRefinedBy(TemporalAccessorl)} 116 * passing {@code this} as the argument. 117 * <p> 118 * Implementations must not alter either this object. 119 * 120 * @param field the field to query the range for, not null 121 * @return the range of valid values for the field, not null 122 * @throws DateTimeException if the range for the field cannot be obtained 123 */ range(TemporalField field)124 ValueRange range(TemporalField field); 125 126 /** 127 * Gets the value of the specified field as an {@code int}. 128 * <p> 129 * This queries the date-time for the value for the specified field. 130 * The returned value will always be within the valid range of values for the field. 131 * If the date-time cannot return the value, because the field is unsupported or for 132 * some other reason, an exception will be thrown. 133 * 134 * <h3>Specification for implementors</h3> 135 * Implementations must check and handle all fields defined in {@link ChronoField}. 136 * If the field is supported and has an {@code int} range, then the value of 137 * the field must be returned. 138 * If unsupported, then a {@code DateTimeException} must be thrown. 139 * <p> 140 * If the field is not a {@code ChronoField}, then the result of this method 141 * is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)} 142 * passing {@code this} as the argument. 143 * <p> 144 * Implementations must not alter either this object. 145 * 146 * @param field the field to get, not null 147 * @return the value for the field, within the valid range of values 148 * @throws DateTimeException if a value for the field cannot be obtained 149 * @throws DateTimeException if the range of valid values for the field exceeds an {@code int} 150 * @throws DateTimeException if the value is outside the range of valid values for the field 151 * @throws ArithmeticException if numeric overflow occurs 152 */ get(TemporalField field)153 int get(TemporalField field); 154 155 /** 156 * Gets the value of the specified field as a {@code long}. 157 * <p> 158 * This queries the date-time for the value for the specified field. 159 * The returned value may be outside the valid range of values for the field. 160 * If the date-time cannot return the value, because the field is unsupported or for 161 * some other reason, an exception will be thrown. 162 * 163 * <h3>Specification for implementors</h3> 164 * Implementations must check and handle all fields defined in {@link ChronoField}. 165 * If the field is supported, then the value of the field must be returned. 166 * If unsupported, then a {@code DateTimeException} must be thrown. 167 * <p> 168 * If the field is not a {@code ChronoField}, then the result of this method 169 * is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)} 170 * passing {@code this} as the argument. 171 * <p> 172 * Implementations must not alter either this object. 173 * 174 * @param field the field to get, not null 175 * @return the value for the field 176 * @throws DateTimeException if a value for the field cannot be obtained 177 * @throws ArithmeticException if numeric overflow occurs 178 */ getLong(TemporalField field)179 long getLong(TemporalField field); 180 181 /** 182 * Queries this date-time. 183 * <p> 184 * This queries this date-time using the specified query strategy object. 185 * <p> 186 * Queries are a key tool for extracting information from date-times. 187 * They exists to externalize the process of querying, permitting different 188 * approaches, as per the strategy design pattern. 189 * Examples might be a query that checks if the date is the day before February 29th 190 * in a leap year, or calculates the number of days to your next birthday. 191 * <p> 192 * The most common query implementations are method references, such as 193 * {@code LocalDate::from} and {@code ZoneId::from}. 194 * Further implementations are on {@link TemporalQueries}. 195 * Queries may also be defined by applications. 196 * 197 * <h3>Specification for implementors</h3> 198 * Implementations of this method must behave as follows: 199 * <pre> 200 * public <R> R query(TemporalQuery<R> type) { 201 * // only include an if statement if the implementation can return it 202 * if (query == TemporalQueries.zoneId()) return // the ZoneId 203 * if (query == TemporalQueries.chronology()) return // the Chrono 204 * if (query == TemporalQueries.precision()) return // the precision 205 * // call default method 206 * return super.query(query); 207 * } 208 * </pre> 209 * 210 * @param <R> the type of the result 211 * @param query the query to invoke, not null 212 * @return the query result, null may be returned (defined by the query) 213 * @throws DateTimeException if unable to query 214 * @throws ArithmeticException if numeric overflow occurs 215 */ query(TemporalQuery<R> query)216 <R> R query(TemporalQuery<R> query); 217 218 } 219