Last updated January 11, 2013 10:10, by Anatole
=<img align="right" src="http://asset-1.java.net/attachments/images/project/javamoney.png?20121214.f926c51"/> <br/>JSR 354 - Design Principles<br/><br/><br/>
The following design principles were identified to be useful for this JSR:
=== Design Principles for the Specification
* use '''Value types''' (simple immutable types, depending on even simpler immutable types or primitives)
* '''Encapsulate implementation details''', especially in monetary amounts encapsulate the number representation.
* Strictly '''separate value types from formatting and parsing'''.
* Strictly '''separate value types from conversion''' logic.
* Use <code>long</code> formatted '''UTC timestamps'''.
* Use '''plain Java interfaces''' were possible.
* For each area (<code>MonetaryAmount, CurrencyUnit</code> etc) an according '''accessor interfaces''' must be defined, which then must be implemented. Accessor interface and interfaces basically fully define the functionality provided and must both be described/represented in the specification.
* Were useful do '''reuse existing JDK artifacts''', instead of reinventing new ones.
* Clearly '''separate''' the application programming interface ('''API''')''' from''' the service provider interface ('''SPI'''). The API must never depend on the SPI, where the other way round may be possible.
* '''Define static accessors''' for the API/SPI artifacts.
* '''Separate different concerns''' into different APIs/SPIs.
* '''Allow multiple SPI implementations''' to be registered at a time by providing according separation rules, where possible (and useful). As an example a <code>CurrencyProvider</code> defines the namepsace it is responsible for, whereas multiple namepsaces can be define by multiple providers registered.
* Where an operation can only fail due to extraordinary reason, avoid using checked '''exceptions'''. In case, were a failure must be expected, use checked exceptions.
* '''Method naming and style''' in '''alignment with <code>java.util.Currency</code>''', where applicable <code>BigDecimal</code>, unless otherwise recommended by (Oracle) Platform Architects
** same method name prefixes - <code>getInstance()</code> for factories, other operations modeled after <code>BigDecimal</code>to the extent it makes sense. See JavaFX or other APIs.
** overall API "feel" shold mirror <code>BigDecimal</code>, unless otherwise recommended by (Oracle) Platform Architects
* Works acceptably with other JVM languages (Groovy, Scala, Clojure...) most do with <code>java.util.Currency</code>, or <code>BigDecimal</code>, thus integration will be similar.
** Possibly have to align with OpenJDK and other parts like JavaFX
===Design Principles for the Reference Implementation
* Use <code>java.util.ServiceLoader</code> for loading of SPI implementations.
* If possible/useful '''model classes''' that implement API interfaces as '''non final''', so they can be freely extended by clients.
* Use <code>net.java.javamoney</code> as root package.
===Factory and Accessor Design (not final)
* For each type (<code>MonetaryAmount, CurrencyUnit</code> etc) an according accessor interface is defined. This allows to completely exchange the implementation and prevents implementation dependencies from TCK to the RI easily, since tests are running against the interfaces. The according interfaces are registered/loaded using the jdk's <code>ServiceLoader</code>.
* The specification requires that the implementation/RI must provide a singleton <code>java.money.Money</code> that provides access to the different components.
Example of factory and type access:
Currencies currencies = javax.money.Money.getCurrencies();
CurrencyUnit currencies = currencies.getAll();