This revision made February 06, 2013 12:15, by Anatole
JSR 354 - Requirements
- Currencies are modelled by an interface called
CurrencyUnit does not provide methods for localization (functionality is separated into dedicated
CurrencyUnit always must provide the following properties:
- The owning namespace
- The literal code, unique within this namespace.
- The default fraction digits
CurrencyUnit can optionally provide the following properties:
- A numeric code, unique within this namespace.
validFrom timestamp, defining from when the currency is valid (used for historic currencies).
validUntil timestamp, defining until when the currency is valid (used for historic currencies).
Access of CurrencyUnit
CurrencyUnits can be accessed from 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
- for a
Region, which defines a grouping that may be different to the grouping defined by
- Monetary amounts are modelled by an interface called
MonetaryAmount never rounds the internal numeric representation to avoid loosing information.
MonetaryAmount can be created using a
- and a numeric value:
- an instance of
- an instance of numeric Java primitive.
- PROPOSAL: Optionally, the required representation type can be passed as a parameter on construction.
MonetaryAmount directly provides arithmetic operations retuning the result as new immutable instance of
- other methods as defined by
- Generally when calling an arithmetic method with another instance of
MonetaryAmount, that has a different
CurrencyMismatchException (runtime exception) must be thrown. Implicit conversion is not allowed.
MonetaryAmount supports converting the numeric value using
short toShort(); double toDouble(); etc.
MonetaryAmount supports conversion into the corresoinding numeric wrapper classes by a method
- In SE conversion into
BigInteger is also supported.
MonetaryAmount can be queried for its internal number representation by calling
- 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.
Difference compared to previous revision
===Access of CurrencyUnit
* <code>CurrencyUnit</code>s can be accessed from the <code>CurrencySupport</code> component.
* The <code>Currency<span style="text-decoration:line-through;color:red">Supp</span><span style="text-decoration:underline;color:green">UnitPr</span>o<span style="text-decoration:underline;color:green">vide</span>or<span style="text-decoration:line-through;color:red">t</span></code> is provided b<span style="text-decoration:line-through;color:red"><</span>r</code> is provided b<span style="text-decoration:underline;color:green">y</span> the <code><span style="text-decoration:line-through;color:red">Curre</span><span style="text-decoration:underline;color:green">Mo</span>n<span style="text-decoration:line-through;color:red">ci</span>e<span style="text-decoration:line-through;color:red">s</span>ne<span style="text-decoration:underline;color:green">tary</span></code> accessor ''singleton''.
* A single <code>CurrencyUnit</code> can be accessed using
** the target namespace
** the currency's code.<span>