[JAVAMONEY-13] Abstraction for Currencies Created: 31/Jan/13  Updated: 08/Aug/13  Resolved: 26/Apr/13

Status: Closed
Project: javamoney
Component/s: API
Affects Version/s: 0.3
Fix Version/s: 0.4-EDR1

Type: New Feature Priority: Critical
Reporter: atsticks Assignee: atsticks
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: 0 minutes
Time Spent: Not Specified
Original Estimate: 0 minutes

Tags: Currency, CurrencyUnit, api, multi-curency, time_handling


Provide an interface and a value type for a CurrencyUnit, which provides the following functionality:

  • the CurrencyUnit interface modelled does not define any methods for changing the internal state.
  • the value type must be final and immutable, and implement the CurrencyUnit interface.
  • CurrencyUnit may have different namespaces, e.g. 'ISO-4217' (default), but also arbitrary others are supported.
  • the namespace of a CurrencyUnit can be accessed by a corresponding method String getNamespace().
  • a CurrencyUnit must have a unique literal currency code unique within the namespace, accessible by a method String getCurrencyCode().
  • a CurrencyUnit provides the basic non localized methods similar to java.util.Currency for maximal backwards compatibility:
    • int getNumericCode() Gets a numeric currency code. Hereby -1 is returned if no numeric code is available for an instance.
    • int getDefaultFractionDigits(), Gets the number of fractional digits typically used by a currency. -1 is returned if no such value is available for an instance
  • a CurrencyUnit has a time period defined, when it is valid. This is modelled by Long getValidFrom(); and Long getValidUntil();.
    • If no feasible values can be returned, or the currency unit is still valid in the current context, null is returned for the time period methods.
    • the implementation of CurrencyUnit by java.util.Currency should always return null for both methods as a default.
    • SPI implementation may create additional instances of CurrencyUnit also for the ISO-4217 namespace, that reflect the currency duration as defined also by ISO.
  • A CurrencyUnit has a boolean flag if it has a legal tender.
  • Finally a CurrencyUnit can be a real or a virtual currency, modelled by the boolean isVirtual() method.
  • a Currencynit extends AttributeProvider, which allows to provide additional arbitrary attributes. This is required since complex use cases, such as not clearly defined ISO codes and legal tenders may require passing additional information, that can not be fully covered by this JSR.
  • The implementations of CurrencyUnit must implement Comparable<CurrencyUnit>, whereas the interface does not define this requirements due to decoupling aspects.

Instances of CurrencyUnit can be obtained

  • by using the CurrencyProvider available on the Monetary singleton. This allows to support more complex use cases, e.g. classification based access, historic currencies and alternate namespaces.
  • by using the static factory method on java.util.Currency instance (the JDK class must, of course, implement CurrencyUnit.

Generated at Tue Feb 28 03:40:12 UTC 2017 using JIRA 6.2.3#6260-sha1:63ef1d6dac3f4f4d7db4c1effd405ba38ccdc558.