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 36 /** 37 * Strategy for querying a temporal object. 38 * <p> 39 * Queries are a key tool for extracting information from temporal objects. 40 * They exist to externalize the process of querying, permitting different 41 * approaches, as per the strategy design pattern. 42 * Examples might be a query that checks if the date is the day before February 29th 43 * in a leap year, or calculates the number of days to your next birthday. 44 * <p> 45 * The {@link TemporalField} interface provides another mechanism for querying 46 * temporal objects. That interface is limited to returning a {@code long}. 47 * By contrast, queries can return any type. 48 * <p> 49 * There are two equivalent ways of using a {@code TemporalQuery}. 50 * The first is to invoke the method on this interface directly. 51 * The second is to use {@link TemporalAccessor#query(TemporalQuery)}: 52 * <pre> 53 * // these two lines are equivalent, but the second approach is recommended 54 * temporal = thisQuery.queryFrom(temporal); 55 * temporal = temporal.query(thisQuery); 56 * </pre> 57 * It is recommended to use the second approach, {@code query(TemporalQuery)}, 58 * as it is a lot clearer to read in code. 59 * <p> 60 * The most common implementations are method references, such as 61 * {@code LocalDate::from} and {@code ZoneId::from}. 62 * Further implementations are on {@link TemporalQueries}. 63 * Queries may also be defined by applications. 64 * 65 * <h3>Specification for implementors</h3> 66 * This interface places no restrictions on the mutability of implementations, 67 * however immutability is strongly recommended. 68 */ 69 public interface TemporalQuery<R> { 70 71 /** 72 * Queries the specified temporal object. 73 * <p> 74 * This queries the specified temporal object to return an object using the logic 75 * encapsulated in the implementing class. 76 * Examples might be a query that checks if the date is the day before February 29th 77 * in a leap year, or calculates the number of days to your next birthday. 78 * <p> 79 * There are two equivalent ways of using this method. 80 * The first is to invoke this method directly. 81 * The second is to use {@link TemporalAccessor#query(TemporalQuery)}: 82 * <pre> 83 * // these two lines are equivalent, but the second approach is recommended 84 * temporal = thisQuery.queryFrom(temporal); 85 * temporal = temporal.query(thisQuery); 86 * </pre> 87 * It is recommended to use the second approach, {@code query(TemporalQuery)}, 88 * as it is a lot clearer to read in code. 89 * 90 * <h3>Specification for implementors</h3> 91 * The implementation must take the input object and query it. 92 * The implementation defines the logic of the query and is responsible for 93 * documenting that logic. 94 * It may use any method on {@code TemporalAccessor} to determine the result. 95 * The input object must not be altered. 96 * <p> 97 * The input temporal object may be in a calendar system other than ISO. 98 * Implementations may choose to document compatibility with other calendar systems, 99 * or reject non-ISO temporal objects by {@link TemporalQueries#chronology() querying the chronology}. 100 * <p> 101 * This method may be called from multiple threads in parallel. 102 * It must be thread-safe when invoked. 103 * 104 * @param temporal the temporal object to query, not null 105 * @return the queried value, may return null to indicate not found 106 * @throws DateTimeException if unable to query 107 * @throws ArithmeticException if numeric overflow occurs 108 */ queryFrom(TemporalAccessor temporal)109 R queryFrom(TemporalAccessor temporal); 110 111 } 112