Module java.money

Package javax.money.spi

Interface MonetaryConversionsSingletonSpi

public interface MonetaryConversionsSingletonSpi

SPI (conversion) that implements the functionality provided by the MonetaryConversions singleton accessor. It should be registered as a service using the JDK ServiceLoader. Hereby only one instance can be registered at a time.

This interface is designed to support also contextual behaviour, e.g. in Java EE containers each application may provide its own ExchangeRateProvider instances, e.g. by registering them as CDI beans. An EE container can register an according MonetaryConversionsSingletonSpi that manages the different application contexts transparently. In a SE environment this class is expected to behave like an ordinary singleton, loading its SPIs from the ServiceLoader.

Instances of this class must be thread safe. It is not a requirement that they are serializable.

Only one instance can be registered using the ServiceLoader. When registering multiple instances the MonetaryConversions accessor will not work.

Author:

Anatole Tresch, Werner Keil

Method Summary

Modifier and Type	Method	Description
default CurrencyConversion	getConversion(ConversionQuery conversionQuery)	Access an instance of CurrencyConversion.
default CurrencyConversion	getConversion(CurrencyUnit termCurrency, java.lang.String... providers)	Access an instance of CurrencyConversion.
java.util.List<java.lang.String>	getDefaultProviderChain()	Get the default provider chain used.
default ExchangeRateProvider	getExchangeRateProvider(java.lang.String... providers)	Access a compound instance of an ExchangeRateProvider based on the given provider chain.
ExchangeRateProvider	getExchangeRateProvider(ConversionQuery conversionQuery)	Access an instance of ExchangeRateProvider.
default java.util.List<ExchangeRateProvider>	getExchangeRateProviders(java.lang.String... providers)	Access the current registered ExchangeRateProvider instances.
java.util.Collection<java.lang.String>	getProviderNames()	Get all currently registered provider names.
default boolean	isConversionAvailable(ConversionQuery conversionQuery)	Allows to quickly check, if a CurrencyConversion is accessible for the given ConversionQuery.
default boolean	isConversionAvailable(CurrencyUnit termCurrency, java.lang.String... providers)	Allows to quickly check, if a CurrencyConversion is accessible for the given ConversionQuery.
default boolean	isExchangeRateProviderAvailable(ConversionQuery conversionQuery)	Allows to quickly check, if a ExchangeRateProvider is accessible for the given ConversionQuery.

Method Detail

getProviderNames

java.util.Collection<java.lang.String> getProviderNames()

Get all currently registered provider names.

Returns:

all currently registered provider names

See Also:

AbstractContext.getProviderName()

getDefaultProviderChain

java.util.List<java.lang.String> getDefaultProviderChain()

Get the default provider chain used. The ordering of the items is the access order/precedence of the providers.

Returns:

the default provider chain, not null and not empty.

getExchangeRateProvider

ExchangeRateProvider getExchangeRateProvider(ConversionQuery conversionQuery)

Access an instance of ExchangeRateProvider. By setting .ConversionQuery#getCurrencyProviderNames() multiple providers can be selected, that will be included into a compound instance, with the same order as returned by the .money.convert.ConversionQuery.

Parameters:

conversionQuery - the ConversionQuery determining the type of conversion required, not null.

Returns:

an ExchangeRateProvider built up with the given sub providers, never null

Throws:

MonetaryException - if a provider could not be found.

See Also:

isExchangeRateProviderAvailable(javax.money.convert.ConversionQuery)

isExchangeRateProviderAvailable

default boolean isExchangeRateProviderAvailable(ConversionQuery conversionQuery)

Allows to quickly check, if a ExchangeRateProvider is accessible for the given ConversionQuery.

Parameters:

conversionQuery - the ConversionQuery determining the type of conversion required, not null.

Returns:

true, if such a conversion is supported, meaning an according ExchangeRateProvider can be accessed.

See Also:

getExchangeRateProvider(ConversionQuery), getExchangeRateProvider(String...)

isConversionAvailable

default boolean isConversionAvailable(ConversionQuery conversionQuery)

Allows to quickly check, if a CurrencyConversion is accessible for the given ConversionQuery.

Parameters:

conversionQuery - the ConversionQuery determining the type of conversion required, not null.

Returns:

true, if such a conversion is supported, meaning an according CurrencyConversion can be accessed.

See Also:

getConversion(javax.money.convert.ConversionQuery), getConversion(CurrencyUnit, String...)

isConversionAvailable

default boolean isConversionAvailable(CurrencyUnit termCurrency,
                                      java.lang.String... providers)

Allows to quickly check, if a CurrencyConversion is accessible for the given ConversionQuery.

Parameters:

termCurrency - the terminating/target currency unit, not null.

providers - the provider names defines a corresponding provider chain that must be encapsulated by the resulting .money.convert.CurrencyConversion. By default the provider chain as defined by #getDefaultCurrencyProviderChain will be used.

Returns:

true, if such a conversion is supported, meaning an according CurrencyConversion can be accessed.

See Also:

getConversion(javax.money.convert.ConversionQuery), getConversion(CurrencyUnit, String...)

getExchangeRateProviders

default java.util.List<ExchangeRateProvider> getExchangeRateProviders(java.lang.String... providers)

Access the current registered ExchangeRateProvider instances. If no provider names are passed ALL current registered providers are returned in undefined order.

Parameters:

providers - the provider names of the providers to be accessed

Returns:

the list of providers, in the same order as requested.

Throws:

MonetaryException - if a provider could not be resolved.

getExchangeRateProvider

default ExchangeRateProvider getExchangeRateProvider(java.lang.String... providers)

Access a compound instance of an ExchangeRateProvider based on the given provider chain.

Parameters:

providers - the ConversionQuery provider names defines a corresponding provider chain that must be encapsulated by the resulting ExchangeRateProvider. By default the default provider changes as defined in #getDefaultCurrencyProviderChain will be used.

Returns:

an ExchangeRateProvider built up with the given sub providers, never null.

Throws:

MonetaryException - if a provider listed could not be found.

See Also:

getProviderNames(), isExchangeRateProviderAvailable(javax.money.convert.ConversionQuery)

getConversion

default CurrencyConversion getConversion(ConversionQuery conversionQuery)

Access an instance of CurrencyConversion.

Parameters:

conversionQuery - the ConversionQuery determining the type of conversion required, not null.

Returns:

the corresponding conversion, not null.

Throws:

MonetaryException - if no matching conversion could be found.

See Also:

isConversionAvailable(javax.money.convert.ConversionQuery)

getConversion

default CurrencyConversion getConversion(CurrencyUnit termCurrency,
                                         java.lang.String... providers)

Access an instance of CurrencyConversion.

Parameters:

termCurrency - the terminating/target currency unit, not null.

providers - the ConversionQuery provider names defines a corresponding provider chain that must be encapsulated by the resulting .money.convert.CurrencyConversion. By default the default provider chain as defined by #getDefaultCurrencyProviderChain will be used.

Returns:

the corresponding conversion, not null.

Throws:

MonetaryException - if no matching conversion could be found.

See Also:

isConversionAvailable(javax.money.convert.ConversionQuery)