javax.money.MonetaryQuery Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of money-api-bp Show documentation

JSR 354 provides an API for representing, transporting, and performing comprehensive calculations with Money and Currency. This module provides a forward compatible backport of the API.

There is a newer version: 1.0.4

Show newest version

/*
 * CREDIT SUISSE IS WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE
 * CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN THIS AGREEMENT.
 * PLEASE READ THE TERMS AND CONDITIONS OF THIS AGREEMENT CAREFULLY. BY
 * DOWNLOADING THIS SPECIFICATION, YOU ACCEPT THE TERMS AND CONDITIONS OF THE
 * AGREEMENT. IF YOU ARE NOT WILLING TO BE BOUND BY IT, SELECT THE "DECLINE"
 * BUTTON AT THE BOTTOM OF THIS PAGE.
 * 
 * Specification: JSR-354 Money and Currency API ("Specification")
 * 
 * Copyright (c) 2012-2013, Credit Suisse All rights reserved.
 */
package javax.money;

/**
 * Strategy for querying a monetary amount.
 * 
 * Queries are a key tool for extracting information from monetary amounts. They
 * match the strategy design pattern, allowing different types of query to be
 * easily captured. Examples might be a query that checks if the amount is
 * positive, or one that extracts the currency as a symbol.
 * 

 * There are two equivalent ways of using a {@code MonetaryQuery}. The first is
 * to invoke the method on this interface. The second is to use
 * {@link MonetaryAmount#query(MonetaryQuery)}:
 * 

 * 
 * // these two lines are equivalent, but the second approach is recommended
 * monetary = thisQuery.queryFrom(monetary);
 * // Recommended approach
 * monetary = monetary.query(thisQuery);
 * 
 * 
 * It is recommended to use the second approach, {@code query(MonetaryQuery)},
 * as it is a lot clearer to read in code.
 * 
Implementation specification
 * This interface places no restrictions on the mutability of implementations,
 * however immutability is strongly recommended.
 *
 * @param  the return type.
 * @author Anatole Tresch
 * @author Stephen Colebourne
 * @author Werner Keil
 * @version 0.8
 */
public interface MonetaryQuery {

    /**
     * Queries the specified monetary amount.
     * 
     * This queries the specified monetary amount to return an object using the
     * logic encapsulated in the implementing class. Examples might be a query
     * that checks if the amount is positive, or one that extracts the currency
     * as a symbol.
     * 

     * There are two equivalent ways of using a {@code MonetaryQuery}. The first
     * is to invoke the method on this interface. The second is to use
     * {@link MonetaryAmount#query(MonetaryQuery)}:
     * 

     * 
     * // these two lines are equivalent, but the second approach is recommended
     * monetary = thisQuery.queryFrom(monetary);
     * monetary = monetary.query(thisQuery);
     * 
     * 
     * It is recommended to use the second approach,
     * {@code query(MonetaryQuery)}, as it is a lot clearer to read in code.
     * 

     * 
Implementation specification
     * The implementation must take the input object and query it. The
     * implementation defines the logic of the query and is responsible for
     * documenting that logic. It may use any method on {@code MonetaryAmount}
     * to determine the result. The input object must not be altered.
     * 
     * This method may be called from multiple threads in parallel. It must be
     * thread-safe when invoked.
     *
     * @param amount the monetary amount to query, not null
     * @return the queried value, may return null to indicate not found
     * @throws MonetaryException   if unable to query
     * @throws ArithmeticException if numeric overflow occurs
     */
    R queryFrom(MonetaryAmount amount);

}