001/* 002 * Copyright (c) 2007-2013, Stephen Colebourne & Michael Nascimento Santos 003 * 004 * All rights reserved. 005 * 006 * Redistribution and use in source and binary forms, with or without 007 * modification, are permitted provided that the following conditions are met: 008 * 009 * * Redistributions of source code must retain the above copyright notice, 010 * this list of conditions and the following disclaimer. 011 * 012 * * Redistributions in binary form must reproduce the above copyright notice, 013 * this list of conditions and the following disclaimer in the documentation 014 * and/or other materials provided with the distribution. 015 * 016 * * Neither the name of JSR-310 nor the names of its contributors 017 * may be used to endorse or promote products derived from this software 018 * without specific prior written permission. 019 * 020 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 021 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 022 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 023 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 024 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 025 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 026 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 027 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 028 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 029 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 030 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 031 */ 032package org.threeten.bp.temporal; 033 034import org.threeten.bp.DateTimeException; 035import org.threeten.bp.ZoneId; 036 037/** 038 * Framework-level interface defining read-only access to a temporal object, 039 * such as a date, time, offset or some combination of these. 040 * <p> 041 * This is the base interface type for date, time and offset objects. 042 * It is implemented by those classes that can provide information 043 * as {@link TemporalField fields} or {@link TemporalQuery queries}. 044 * <p> 045 * Most date and time information can be represented as a number. 046 * These are modeled using {@code TemporalField} with the number held using 047 * a {@code long} to handle large values. Year, month and day-of-month are 048 * simple examples of fields, but they also include instant and offsets. 049 * See {@link ChronoField} for the standard set of fields. 050 * <p> 051 * Two pieces of date/time information cannot be represented by numbers, 052 * the {@link Chrono chronology} and the {@link ZoneId time-zone}. 053 * These can be accessed via {@link #query(TemporalQuery) queries} using 054 * the static methods defined on {@link TemporalQueries}. 055 * <p> 056 * A sub-interface, {@link Temporal}, extends this definition to one that also 057 * supports adjustment and manipulation on more complete temporal objects. 058 * <p> 059 * This interface is a framework-level interface that should not be widely 060 * used in application code. Instead, applications should create and pass 061 * around instances of concrete types, such as {@code LocalDate}. 062 * There are many reasons for this, part of which is that implementations 063 * of this interface may be in calendar systems other than ISO. 064 * See {@link ChronoLocalDate} for a fuller discussion of the issues. 065 * 066 * <h3>Specification for implementors</h3> 067 * This interface places no restrictions on the mutability of implementations, 068 * however immutability is strongly recommended. 069 */ 070public interface TemporalAccessor { 071 072 /** 073 * Checks if the specified field is supported. 074 * <p> 075 * This checks if the date-time can be queried for the specified field. 076 * If false, then calling the {@link #range(TemporalField) range} and {@link #get(TemporalField) get} 077 * methods will throw an exception. 078 * 079 * <h3>Specification for implementors</h3> 080 * Implementations must check and handle all fields defined in {@link ChronoField}. 081 * If the field is supported, then true is returned, otherwise false 082 * <p> 083 * If the field is not a {@code ChronoField}, then the result of this method 084 * is obtained by invoking {@code TemporalField.doIsSupported(TemporalAccessor)} 085 * passing {@code this} as the argument. 086 * <p> 087 * Implementations must not alter either this object. 088 * 089 * @param field the field to check, null returns false 090 * @return true if this date-time can be queried for the field, false if not 091 */ 092 boolean isSupported(TemporalField field); 093 094 /** 095 * Gets the range of valid values for the specified field. 096 * <p> 097 * All fields can be expressed as a {@code long} integer. 098 * This method returns an object that describes the valid range for that value. 099 * The value of this temporal object is used to enhance the accuracy of the returned range. 100 * If the date-time cannot return the range, because the field is unsupported or for 101 * some other reason, an exception will be thrown. 102 * <p> 103 * Note that the result only describes the minimum and maximum valid values 104 * and it is important not to read too much into them. For example, there 105 * could be values within the range that are invalid for the field. 106 * 107 * <h3>Specification for implementors</h3> 108 * Implementations must check and handle all fields defined in {@link ChronoField}. 109 * If the field is supported, then the range of the field must be returned. 110 * If unsupported, then a {@code DateTimeException} must be thrown. 111 * <p> 112 * If the field is not a {@code ChronoField}, then the result of this method 113 * is obtained by invoking {@code TemporalField.doRange(TemporalAccessorl)} 114 * passing {@code this} as the argument. 115 * <p> 116 * Implementations must not alter either this object. 117 * 118 * @param field the field to query the range for, not null 119 * @return the range of valid values for the field, not null 120 * @throws DateTimeException if the range for the field cannot be obtained 121 */ 122 ValueRange range(TemporalField field); 123 124 /** 125 * Gets the value of the specified field as an {@code int}. 126 * <p> 127 * This queries the date-time for the value for the specified field. 128 * The returned value will always be within the valid range of values for the field. 129 * If the date-time cannot return the value, because the field is unsupported or for 130 * some other reason, an exception will be thrown. 131 * 132 * <h3>Specification for implementors</h3> 133 * Implementations must check and handle all fields defined in {@link ChronoField}. 134 * If the field is supported and has an {@code int} range, then the value of 135 * the field must be returned. 136 * If unsupported, then a {@code DateTimeException} must be thrown. 137 * <p> 138 * If the field is not a {@code ChronoField}, then the result of this method 139 * is obtained by invoking {@code TemporalField.doGet(TemporalAccessor)} 140 * passing {@code this} as the argument. 141 * <p> 142 * Implementations must not alter either this object. 143 * 144 * @param field the field to get, not null 145 * @return the value for the field, within the valid range of values 146 * @throws DateTimeException if a value for the field cannot be obtained 147 * @throws DateTimeException if the range of valid values for the field exceeds an {@code int} 148 * @throws DateTimeException if the value is outside the range of valid values for the field 149 * @throws ArithmeticException if numeric overflow occurs 150 */ 151 int get(TemporalField field); 152 153 /** 154 * Gets the value of the specified field as a {@code long}. 155 * <p> 156 * This queries the date-time for the value for the specified field. 157 * The returned value may be outside the valid range of values for the field. 158 * If the date-time cannot return the value, because the field is unsupported or for 159 * some other reason, an exception will be thrown. 160 * 161 * <h3>Specification for implementors</h3> 162 * Implementations must check and handle all fields defined in {@link ChronoField}. 163 * If the field is supported, then the value of the field must be returned. 164 * If unsupported, then a {@code DateTimeException} must be thrown. 165 * <p> 166 * If the field is not a {@code ChronoField}, then the result of this method 167 * is obtained by invoking {@code TemporalField.doGet(TemporalAccessor)} 168 * passing {@code this} as the argument. 169 * <p> 170 * Implementations must not alter either this object. 171 * 172 * @param field the field to get, not null 173 * @return the value for the field 174 * @throws DateTimeException if a value for the field cannot be obtained 175 * @throws ArithmeticException if numeric overflow occurs 176 */ 177 long getLong(TemporalField field); 178 179 /** 180 * Queries this date-time. 181 * <p> 182 * This queries this date-time using the specified query strategy object. 183 * <p> 184 * Queries are a key tool for extracting information from date-times. 185 * They exists to externalize the process of querying, permitting different 186 * approaches, as per the strategy design pattern. 187 * Examples might be a query that checks if the date is the day before February 29th 188 * in a leap year, or calculates the number of days to your next birthday. 189 * <p> 190 * The most common query implementations are method references, such as 191 * {@code LocalDate::from} and {@code ZoneId::from}. 192 * Further implementations are on {@link TemporalQueries}. 193 * Queries may also be defined by applications. 194 * 195 * <h3>Specification for implementors</h3> 196 * Implementations of this method must behave as follows: 197 * <pre> 198 * public <R> R query(TemporalQuery<R> type) { 199 * // only include an if statement if the implementation can return it 200 * if (query == TemporalQueries.zoneId()) return // the ZoneId 201 * if (query == TemporalQueries.chrono()) return // the Chrono 202 * if (query == TemporalQueries.precision()) return // the precision 203 * // call default method 204 * return super.query(query); 205 * } 206 * </pre> 207 * 208 * @param <R> the type of the result 209 * @param query the query to invoke, not null 210 * @return the query result, null may be returned (defined by the query) 211 * @throws DateTimeException if unable to query 212 * @throws ArithmeticException if numeric overflow occurs 213 */ 214 <R> R query(TemporalQuery<R> query); 215 216}