001/*
002 * CREDIT SUISSE IS WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE
003 * CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN THIS AGREEMENT.
004 * PLEASE READ THE TERMS AND CONDITIONS OF THIS AGREEMENT CAREFULLY. BY
005 * DOWNLOADING THIS SPECIFICATION, YOU ACCEPT THE TERMS AND CONDITIONS OF THE
006 * AGREEMENT. IF YOU ARE NOT WILLING TO BE BOUND BY IT, SELECT THE "DECLINE"
007 * BUTTON AT THE BOTTOM OF THIS PAGE.
008 * 
009 * Specification: JSR-354 Money and Currency API ("Specification")
010 * 
011 * Copyright (c) 2012-2013, Credit Suisse All rights reserved.
012 */
013package javax.money;
014
015/**
016 * Strategy for querying a monetary amount.
017 * <p>
018 * Queries are a key tool for extracting information from monetary amounts.
019 * They match the strategy design pattern, allowing different types of
020 * query to be easily captured.
021 * Examples might be a query that checks if the amount is positive, or
022 * one that extracts the currency as a symbol.
023 * <p>
024 * There are two equivalent ways of using a {@code MonetaryQuery}.
025 * The first is to invoke the method on this interface.
026 * The second is to use {@link MonetaryAmount#query(MonetaryQuery)}:
027 * <pre>
028 *   // these two lines are equivalent, but the second approach is recommended
029 *   monetary = thisQuery.queryFrom(monetary);
030 *   // recommened approach
031 *   monetary = monetary.query(thisQuery);
032 * </pre>
033 * It is recommended to use the second approach, {@code query(MonetaryQuery)},
034 * as it is a lot clearer to read in code.
035 * <h4>Implementation specification</h4>
036 * This interface places no restrictions on the mutability of implementations,
037 * however immutability is strongly recommended.
038 */
039// @FunctionalInterface for Java 9
040public interface MonetaryQuery<R> {
041
042        /**
043     * Queries the specified monetary amount.
044     * <p>
045     * This queries the specified monetary amount to return an object using the logic
046     * encapsulated in the implementing class.
047     * Examples might be a query that checks if the amount is positive, or
048     * one that extracts the currency as a symbol.
049     * <p>
050     * There are two equivalent ways of using a {@code MonetaryQuery}.
051     * The first is to invoke the method on this interface.
052     * The second is to use {@link MonetaryAmount#query(MonetaryQuery)}:
053     * <pre>
054     *   // these two lines are equivalent, but the second approach is recommended
055     *   monetary = thisQuery.queryFrom(monetary);
056     *   monetary = monetary.query(thisQuery);
057     * </pre>
058     * It is recommended to use the second approach, {@code query(MonetaryQuery)},
059     * as it is a lot clearer to read in code.
060     * 
061     * <h4>Implementation specification</h4>
062     * The implementation must take the input object and query it.
063     * The implementation defines the logic of the query and is responsible for
064     * documenting that logic.
065     * It may use any method on {@code MonetaryAmount} to determine the result.
066     * The input object must not be altered.
067     * <p>
068     * This method may be called from multiple threads in parallel.
069     * It must be thread-safe when invoked.
070     *
071     * @param amount  the monetary amount to query, not null
072     * @return the queried value, may return null to indicate not found
073     * @throws MonetaryException if unable to query
074     * @throws ArithmeticException if numeric overflow occurs
075     */
076        public R queryFrom(MonetaryAmount amount);
077
078}