Last updated January 06, 2013 09:58, by Anatole

==General Considerations
Basically we target the most common use cases, which can be well covered by a general and flexible design, such as:
* Deposit or withdraw an amount of money, debitting or crediting associated accounts.
* Make a payment of some amount of money and make change Interbank transfers
* Settlement of financial transactions
* Credit card payment
* All of the above, using foreign currency
* Access currencies both current as well as historic ones
* In general, provide a simple, but effective representation for currencies and monetary amounts that creates real benefit to the Java platform.
==Data Modelling (''core'')
===Currencies
* Support multiple currency schemes
** ISO4217 currency using its numeric or literal code.
** virtual currencies that are not covered by ISO, e.g. [http://www.bitcoin.org BitCoin] or similar examples of Virtual/Social currencies).
** Additionally big financial organizations typically also have additional currency schemes that also must be supported, e.g. for historic reasons. For example ''Deutsche Reichsmark'' is not mapped to the current ISO scheme.
* Access all currencies available (for presentation, validation or usage on calculations)
** at the current instant
** historic, at any time in the past (timestamp)
** for a given namespace, e.g. ISO4217.
* access all currencies available to different classifications
** a <code>java.util.Locale</code> (simple localization)
** a Region (world, continent, sub-continent, territory, or arbitrary grouping, e.g. legal unit).
===Monetary Amounts
* Model a monetary amount, consisting an amount (number) and a currency
* Provide arithmetic operations on monetary amounts, such as
** Perform addition and substraction of ''amounts'', and scalar multiplication and division, using full precision
** Support ''currency safe'' arithmetics by encapsulating the number and currency value into a common ''amount''.
* Support different number representations by hiding the effective implementation. This allows to use it one both SE and ME environments and also enables to use the numeric representation that bests suites the concrete use case.
* Support arbitrary rounding schemes.
==Currency Conversion (''conversion'')
=== Access Exchage Rates and Perform Currency Conversion
* Access exchange rates between two currencies:
** direct exchange rates only
** derived rates only, including also the chained exchange rates
** or both of the above
** select between real-time or deferred exchange rates.
** Allow to access historic exchange rates
** Allow to query exchange rates only from a defined source (e.g. the New York Stock Exchange).
* Support traceability or exchange data source
==Data Formatting and Representation (''format'')
=== Support Complex Localization
Complex localization requires much more than a simple <code>java.util.Locale</code>:
* multiple locales may be required for formatting and parsing, e.g. for
** number localization
** translations
** date localization
* within big application landscape different formatting/parsing areas must be supported:
** screen rendering
** technical data conversion
** differnt conversion for different use cases
As a consequence the following must be supported:
** Different currency formats (symbols, names etc.)
** Different number formats (groupings, scales, precision, rounding, signs, sign and currency placement, decimal points)
** Different roundings
** Combination of all (currency placement, additional literal data, the ladder also requiring a translation, date locales, e.g. when formatting payments)
==Interoperability and Extendability
* Ensure implementation interoperability (e.g. serialization, JPA mapping)
* Design and extendable system supporting arbitrary data providers.
* Provide a flexible and stable infrastructure for higher functionality, e.g. financial libraries.
* Ensure backwards compatibility with <code>java.util.Currency</code> where possible.
==Additional Use cases
===Divide and Separate
Image the following use case:
* A balance of 1000 should be separated into 3 sub values.
* When just using standard rounding, e.g. with a precisoin of 2, one penny will be short because <code>1000/3 = 333.33; 333.33*3 = 999.99; // invalid!</code>.
* Since this would not work in an accounting application, need to consider an api where the penny is accounted for e.g.:
** return an array where the first element is the quotient, and the second element is the excpetion: [333.33, 333.34]
** Or represent the result and remainder [333.33, .01]
==== Further Notes
Both of these approaches would require a third number to represent the remainder or exception. In both approaches, the remainder or exception needs to be included in further calculations.
So 100/3 = [33, 34]. Now let's say we want to divide that by 4, so the 33 term produces [8,9] and the 34 term produces [8,10], so how do you capture all of those remainders?
Another issue. To show it clearly, assume 0 decimal precision, so - 34/4 = [8, 10] using exception approach, or [8, 2] using remainder approach.
In either case, "multiplying" back yields the correct result: 8+8+8+10 = 34. But shouldn't that be better represented as 8+8+9+9? so how do you represent that.
Another approach - retain the fractional representation and work with the formatter to iterate through the results, adding the missing penny to the last one. Then all arithmetic would be fractional arithmetic.

Please Confirm