javax.money

Interface MonetaryQuery<R>

Type Parameters:

R - the return type.

All Known Subinterfaces:

MonetaryAmountFormat

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface MonetaryQuery<R>

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 MonetaryQuery. The first is to invoke the method on this interface. The second is to use 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, 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.

Version:

0.8

Author:

Anatole Tresch, Stephen Colebourne, Werner Keil

Method Summary

Modifier and Type	Method and Description
R	queryFrom(MonetaryAmount amount) Queries the specified monetary amount.

Method Detail

queryFrom

R queryFrom(MonetaryAmount amount)

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 MonetaryQuery. The first is to invoke the method on this interface. The second is to use 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, 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 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.

Parameters:

amount - the monetary amount to query, not null

Returns:

the queried value, may return null to indicate not found

Throws:

MonetaryException - if unable to query

ArithmeticException - if numeric overflow occurs