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;
035
036/**
037 * Strategy for querying a temporal object.
038 * <p>
039 * Queries are a key tool for extracting information from temporal objects.
040 * They exist to externalize the process of querying, permitting different
041 * approaches, as per the strategy design pattern.
042 * Examples might be a query that checks if the date is the day before February 29th
043 * in a leap year, or calculates the number of days to your next birthday.
044 * <p>
045 * The {@link TemporalField} interface provides another mechanism for querying
046 * temporal objects. That interface is limited to returning a {@code long}.
047 * By contrast, queries can return any type.
048 * <p>
049 * There are two equivalent ways of using a {@code TemporalQuery}.
050 * The first is to invoke the method on this interface directly.
051 * The second is to use {@link TemporalAccessor#query(TemporalQuery)}:
052 * <pre>
053 *   // these two lines are equivalent, but the second approach is recommended
054 *   temporal = thisQuery.queryFrom(temporal);
055 *   temporal = temporal.query(thisQuery);
056 * </pre>
057 * It is recommended to use the second approach, {@code query(TemporalQuery)},
058 * as it is a lot clearer to read in code.
059 * <p>
060 * The most common implementations are method references, such as
061 * {@code LocalDate::from} and {@code ZoneId::from}.
062 * Further implementations are on {@link TemporalQueries}.
063 * Queries may also be defined by applications.
064 *
065 * <h3>Specification for implementors</h3>
066 * This interface places no restrictions on the mutability of implementations,
067 * however immutability is strongly recommended.
068 */
069public interface TemporalQuery<R> {
070
071    /**
072     * Queries the specified temporal object.
073     * <p>
074     * This queries the specified temporal object to return an object using the logic
075     * encapsulated in the implementing class.
076     * Examples might be a query that checks if the date is the day before February 29th
077     * in a leap year, or calculates the number of days to your next birthday.
078     * <p>
079     * There are two equivalent ways of using this method.
080     * The first is to invoke this method directly.
081     * The second is to use {@link TemporalAccessor#query(TemporalQuery)}:
082     * <pre>
083     *   // these two lines are equivalent, but the second approach is recommended
084     *   temporal = thisQuery.queryFrom(temporal);
085     *   temporal = temporal.query(thisQuery);
086     * </pre>
087     * It is recommended to use the second approach, {@code query(TemporalQuery)},
088     * as it is a lot clearer to read in code.
089     *
090     * <h3>Specification for implementors</h3>
091     * The implementation must take the input object and query it.
092     * The implementation defines the logic of the query and is responsible for
093     * documenting that logic.
094     * It may use any method on {@code TemporalAccessor} to determine the result.
095     * The input object must not be altered.
096     * <p>
097     * The input temporal object may be in a calendar system other than ISO.
098     * Implementations may choose to document compatibility with other calendar systems,
099     * or reject non-ISO temporal objects by {@link TemporalQueries#chrono() 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     */
109    R queryFrom(TemporalAccessor temporal);
110
111}