Skip to main content
Last updated October 06, 2013 22:23, by keilw

JSR 354 - Requirements

Functional Requirements


  • Currencies are modelled by an interface called CurrencyUnit
  • CurrencyUnit does not provide methods for localization (functionality is separated into dedicated package.
  • A CurrencyUnit always must provide the following properties:
    • The owning namespace
    • The literal code, unique within this namespace.
    • The default fraction digits
  • A CurrencyUnit can optionally provide the following properties:
    • A numeric code, unique within this namespace.
    • A validFrom timestamp, defining from when the currency is valid (used for historic currencies).
    • A validUntil timestamp, defining until when the currency is valid (used for historic currencies).

Access of CurrencyUnit

  • CurrencyUnits can be accessed from the CurrencySupport component.
  • The CurrencyUnitProvider is provided by the Monetary accessor singleton.
  • A single CurrencyUnit can be accessed using
    • the target namespace
    • the currency's code.
  • Optionally the following can be passed on access:
    • A target timestamp which defines the target date/time for the currency returned.
  • If a CurrencyUnit accessed is not available, a IllegalArgumentException should be thrown.
  • The method boolean isCurrencyAvailable allows to check if a CurrencyUnit is available given the requested parameters.
  • It must be possible to query all CurrencyUnit instances available for a given namespace, either
    • for the current instant
    • for a target timestamp
    • for a corresponding java.util.Locale
    • for a Region, which defines a grouping that may be different to the grouping defined by java.util.Locale.


  • Monetary amounts are modelled by an interface called MonetaryAmount
  • A MonetaryAmount never rounds the internal numeric representation to avoid loosing information.
  • A MonetaryAmount can be created using a
    • CurrencyUnit
    • and a numeric value:
      • an instance of java.lang.Number
      • an instance of numeric Java primitive.
  • PROPOSAL: Optionally, the required representation type can be passed as a parameter on construction.
  • A MonetaryAmount directly provides arithmetic operations retuning the result as new immutable instance of MonetaryAmount for
    • add
    • subtract
    • multiply
    • divide
    • other methods as defined by BigDecimal
    • Generally when calling an arithmetic method with another instance of MonetaryAmount, that has a different CurrencyUnit a CurrencyMismatchException (runtime exception) must be thrown. Implicit conversion is not allowed.
  • A MonetaryAmount supports converting the numeric value using toXXX, e.g. short toShort(); double toDouble(); etc.
  • A MonetaryAmount supports conversion into the corresponding numeric wrapper classes by a method asType.
  • In SE conversion into BigDecimal and BigInteger is also supported.
  • A MonetaryAmount can be queried for its internal number representation by calling Class getNumberType()
  • It can be possible to perform arithmetics between instances of MonetaryAmount with different numeric representations. By default the representation of the result equals to the target MonetaryAmount, on which the operation was performed.

Not yet in Detailed Form

  • Ability to format currencies as per the local market convention. For those unfamiliar with this take a look at something like Region and Language -> Customize Format in Windows 7 for the complete list of number grouping conventions that can be used for monetary values. The new Money type should have the ability to format itself to the standard convention for the Currency or a user specified format.
  • Ability to convert Money value to a String representation (i.e. Five hundred dollars and fifty three cents – useful when producing statements and printing cheques in financial applications. SJC - this is a hard requirement in I18N terms, and something that could be added on top of the main API and separate to the JSR.
  • Currencies shall store their symbols and symbol placement convention. For example: GBP 541.53 should be able to format itself as Five hundred and forty one pounds fifty three pence, but also as £ 541.53p. Put another way currency should also hold its currency symbols, placement rules (many currencies use suffix notation) and probably the natural names for the currency components, so “pounds” and “pence” in the example above.
  • Ability to apply currency rounding and precision conventions (not all currencies and markets use the round up on >=5 and round down <5 convention that we’re used to in the UK and US). These are typically defined as a market convention for a given currency.
  • I’d like us to at least discuss some simplistic support for non-decimal currencies – many financial products are still quoted using fractional prices (as well as decimal) so it would at least make sense for us to be able to represent such prices as naturally as possible.
Please Confirm