javax.money.convert

Interface ExchangeRateProvider

public interface ExchangeRateProvider

This interface defines access to the exchange rates provided by a provider. The provider and its capabilities can be defined in arbitrary detail by the corresponding ProviderContext. Instances of this class must only provide conversion data for exact one provider, identified by AbstractContext.getProviderName(). When accessing ExchangeRateProvider instances or CurrencyConversion instances from the MonetaryConversions in many cases a chain of providers will be returned. It is the reponsibility of the implementation code assembling the chain to establish a well defined coordination mechanism for evaluating the correct result. By default the first provider in the chain that returns a non null result determines the final result of a call. Nevertheless adapting the MonetaryConversionsSingletonSpi allows to implement also alternate strategies, e.g. honoring different priorities of providers as well.

Implementations of this interface are required to be thread save.

Implementations of this class must neither be immutable nor serializable.

Author:

Anatole Tresch, Werner Keil

Method Summary

Modifier and Type	Method and Description
ProviderContext	getContext() Access the ConversionContext for this ExchangeRateProvider.
CurrencyConversion	getCurrencyConversion(ConversionQuery conversionQuery) Access a CurrencyConversion that can be applied as a MonetaryOperator to an amount.
default CurrencyConversion	getCurrencyConversion(CurrencyUnit term) Access a CurrencyConversion that can be applied as a MonetaryOperator to an amount.
default CurrencyConversion	getCurrencyConversion(String termCode) Access a CurrencyConversion that can be applied as a MonetaryOperator to an amount.
ExchangeRate	getExchangeRate(ConversionQuery conversionQuery) Access a ExchangeRate using the given currencies.
default ExchangeRate	getExchangeRate(CurrencyUnit base, CurrencyUnit term) Access a ExchangeRate using the given currencies.
default ExchangeRate	getExchangeRate(String baseCode, String termCode) Access a ExchangeRate using the given currencies.
default ExchangeRate	getReversed(ExchangeRate rate) The method reverses the ExchangeRate to a rate mapping from term to base CurrencyUnit.
default boolean	isAvailable(ConversionQuery conversionQuery) Checks if an ExchangeRate between two CurrencyUnit is available from this provider.
default boolean	isAvailable(CurrencyUnit base, CurrencyUnit term) Checks if an ExchangeRate between two CurrencyUnit is available from this provider.
default boolean	isAvailable(String baseCode, String termCode) Checks if an ExchangeRate between two CurrencyUnit is available from this provider.

Method Detail

getContext

ProviderContext getContext()

Access the ConversionContext for this ExchangeRateProvider. Each instance of ExchangeRateProvider provides conversion data for exact one ConversionContext .

Returns:

the exchange rate type, never null.

getExchangeRate

ExchangeRate getExchangeRate(ConversionQuery conversionQuery)

Access a ExchangeRate using the given currencies. The ExchangeRate may be, depending on the data provider, eal-time or deferred. This method should return the rate that is currently valid.

Parameters:

conversionQuery - the required ConversionQuery, not null

Returns:

the matching ExchangeRate.

Throws:

CurrencyConversionException - If no such rate is available.

MonetaryException - if one of the currency codes passed is not valid.

See Also:

ConversionQueryBuilder

getCurrencyConversion

CurrencyConversion getCurrencyConversion(ConversionQuery conversionQuery)

Access a CurrencyConversion that can be applied as a MonetaryOperator to an amount.

Parameters:

conversionQuery - the required ConversionQuery, not null

Returns:

a new instance of a corresponding CurrencyConversion, never null.

Throws:

MonetaryException - if one of the currency codes passed is not valid.

See Also:

ConversionQueryBuilder

isAvailable

default boolean isAvailable(ConversionQuery conversionQuery)

Checks if an ExchangeRate between two CurrencyUnit is available from this provider. This method should check, if a given rate is currently defined.

Parameters:

conversionQuery - the required ConversionQuery, not null

Returns:

true, if such an ExchangeRate is currently defined.

getExchangeRate

default ExchangeRate getExchangeRate(CurrencyUnit base,
                                     CurrencyUnit term)

Access a ExchangeRate using the given currencies. The ExchangeRate may be, depending on the data provider, eal-time or deferred. This method should return the rate that is currently valid.

Parameters:

base - base CurrencyUnit, not null

term - term CurrencyUnit, not null

Throws:

CurrencyConversionException - If no such rate is available.

getCurrencyConversion

default CurrencyConversion getCurrencyConversion(CurrencyUnit term)

Access a CurrencyConversion that can be applied as a MonetaryOperator to an amount.

Parameters:

term - term CurrencyUnit, not null

Returns:

a new instance of a corresponding CurrencyConversion, never null.

isAvailable

default boolean isAvailable(CurrencyUnit base,
                            CurrencyUnit term)

Checks if an ExchangeRate between two CurrencyUnit is available from this provider. This method should check, if a given rate is currently defined.

Parameters:

base - the base CurrencyUnit

term - the term CurrencyUnit

Returns:

true, if such an ExchangeRate is currently defined.

isAvailable

default boolean isAvailable(String baseCode,
                            String termCode)

Checks if an ExchangeRate between two CurrencyUnit is available from this provider. This method should check, if a given rate is currently defined.

Parameters:

baseCode - the base currency code

termCode - the terminal/target currency code

Returns:

true, if such an ExchangeRate is currently defined.

Throws:

MonetaryException - if one of the currency codes passed is not valid.

getExchangeRate

default ExchangeRate getExchangeRate(String baseCode,
                                     String termCode)

Access a ExchangeRate using the given currencies. The ExchangeRate may be, depending on the data provider, eal-time or deferred. This method should return the rate that is currently valid.

Parameters:

baseCode - base currency code, not null

termCode - term/target currency code, not null

Returns:

the matching ExchangeRate.

Throws:

CurrencyConversionException - If no such rate is available.

MonetaryException - if one of the currency codes passed is not valid.

getReversed

default ExchangeRate getReversed(ExchangeRate rate)

The method reverses the ExchangeRate to a rate mapping from term to base CurrencyUnit. Hereby the factor must not be recalculated as 1/oldFactor, since typically reverse rates are not symmetric in most cases.

Returns:

the matching reversed ExchangeRate, or null, if the rate cannot be reversed.

getCurrencyConversion

default CurrencyConversion getCurrencyConversion(String termCode)

Access a CurrencyConversion that can be applied as a MonetaryOperator to an amount.

Parameters:

termCode - terminal/target currency code, not null

Returns:

a new instance of a corresponding CurrencyConversion, never null.

Throws:

MonetaryException - if one of the currency codes passed is not valid.