CurrencyManagement

Business Purpose

Manages the global registry of ISO 4217 currency units, including lookup by code, numeric code, country, and locale, as well as support for custom or pseudo-currencies. [AI Inference] This allows the library to validate currency consistency across monetary operations.

Current Behaviors

• CurrencyUnit.of(String) returns the registered currency for a given three-letter code CurrencyUnit.java:354.
• CurrencyUnit.ofNumericCode(int) looks up by numeric code CurrencyUnit.java:374.
• CurrencyUnit.of(Locale) returns the currency for a locale CurrencyUnit.java:415.
• CurrencyUnit.ofCountry(String) returns the currency for a country code CurrencyUnit.java:434.
• CurrencyUnit.registerCurrency(String, int, int, String...) allows adding custom currencies CurrencyUnit.java:162.
• CurrencyUnit.registeredCurrencies() returns an unmodifiable set of all known currencies CurrencyUnit.java:313.
• CurrencyUnit.getCode() returns the three-letter code CurrencyUnit.java:485.
• CurrencyUnit.getNumericCode() returns the numeric code CurrencyUnit.java:496.
• CurrencyUnit.getDecimalPlaces() returns the default decimal places CurrencyUnit.java:551.
• CurrencyUnit.isPseudoCurrency() indicates if it's a pseudo (non-traded) currency CurrencyUnit.java:560.
• CurrencyUnit.getSymbol() returns the symbol, possibly localized (CurrencyUnit.java:575, 598).
• DefaultCurrencyUnitDataProvider reads currency data from property files DefaultCurrencyUnitDataProvider.java:59.
• IllegalCurrencyException is thrown for unknown codes (IllegalCurrencyException.java).
• CurrencyMismatchException is thrown when operations mix different currencies (CurrencyMismatchException.java).

Technical Implementation

• CurrencyUnit CurrencyUnit.java:162 is designed as IMMUTABLE_VALUE_OBJECT (design pattern detected).
• Registration methods are synchronized and update a global map CurrencyUnit.java:162.
• The @FromString annotation on of(String) enables automatic string conversion CurrencyUnit.java:354.
• CurrencyUnitDataProvider CurrencyUnitDataProvider.java:28 provides an abstract base for registering currencies.
• DefaultCurrencyUnitDataProvider DefaultCurrencyUnitDataProvider.java:50 overrides registerCurrencies to load from files.
• Both exception classes are IMMUTABLE_VALUE_OBJECT (design patterns detected).

Definition of Done

• Calling CurrencyUnit.of("USD") returns the pre-registered USD currency.
• Attempting to get an unregistered currency code throws IllegalCurrencyException.
• Registering a new currency with registerCurrency("XYZ", 999, 2, "XY") adds it to the registry.
• CurrencyUnit.ofNumericCode(840) returns USD.
• CurrencyUnit.registeredCurrencies() contains at least all ISO 4217 currencies and any custom ones added.
• A CurrencyMismatchException is thrown when trying to add two amounts with different currencies.