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}