Download - Adopt JSR 354

Go for the Money

Adopt JSR 354

Slideshare 2014

March 2014

Go for the money – Adopt JSR 354 -

http://java.net/projects/javamoney

Go for the money - JSR 354 - http://java.net/projects/javamoney March 2014

Bio

Anatole Tresch

Consultant, Coach

Credit Suisse

Technical Coordinator & Architect

Specification Lead JSR 354

Regular Conference Speaker

Driving Java EE Config

Twitter/Google+: @atsticks

[email protected]

[email protected]

Java Config Discussion https://groups.google.com/forum/#!forum/java-config

Java Config Blog: http://javaeeconfig.blogspot.ch

Zurich Java Community (Google Community)

Zurich Hackergarten

2

mailto:[email protected]




https://groups.google.com/forum/#!forum/java-config





http://javaeeconfig.blogspot.ch/


Agenda

3

Overview

Setup

Adoption Areas

API Challenge: Moneymachine

Helping out with the TCK

Adding functonalities to the RI,

e.g. Cash Roundings

Stabilizing JavaMoney Library

Other ?


Overview

4


Money Machine

5


Overview of JSR 354 and Javamoney

API (javax.money):

CurrencyUnit, MonetaryAmount, MonetaryOperator,

MonetaryQuery, CurrencyConversion, ExchangeRate,

MonetaryAmountFormat, MonetaryException;

MonetaryCurrencies, MonetaryAmounts, MonetaryRoundings,

MonetaryConversions, MonetaryFormats

RI (org.javamoney.moneta): BuildableCurrencyUnit, Money, FastMoney, MonetaryFunctions

TCK (org.javamoney.tck):

Javamoney (GitHub OSS project): org.javamoney…

format (extended API)

currencies (mapping)

Regions

Validity

calc

6


Currencies and Monetary Amounts

javax.money

7


Currencies (continued)

API

8

Allow currencies with arbitrary other currency codes

Register additional Currency Units using an flexible SPI Fluent API using a Builder (RI only)

Historic Validity of currencies related to regions/countries and vice

versa (not part of JSR, but javamoney OSS project)

public interface CurrencyUnit{

public String getCurrencyCode();

public int getNumericCode();

public int getDefaultFractionDigits();

}

public final class MonetaryCurrencies{

public CurrencyUnit getCurrency(String currencyCode);

public CurrencyUnit getCurrency(Locale locale);

public boolean isCurrencyAvailable(String currencyCode);

public boolean isCurrencyAvailable(String locale);

}


Currencies (continued)

API Samples

CurrencyUnit currency1 = MonetaryCurrencies.getCurrency("USD");

CurrencyUnit currency2 = MonetaryCurrencies.getCurrency(

Locale.GERMANY);

CurrencyUnit bitcoin = new BuildableCurrencyUnit.Builder("BTC")

.setNumericCode(123456)

.setDefaultFractionDigits(8)

.create();

9

Access a CurrencyUnit

Build a CurrencyUnit (RI only)

Register a CurrencyUnit

CurrencyUnit bitcoin = ….create(true);


Monetary Amounts

General Aspects

10

Amount = Currency + Numeric Value

+ Capabilities

Arithmetic Functions, Comparison

Fluent API


Monetary Amounts (continued)

Key Decisions

11

Support Several Numeric Representations (instead of one

single fixed value type)

Use functional design for extendible functionality (MonetaryOperator, MonetaryQuery)

Define Implementation Recommendations

• Rounding should to be modelled as separate concern (a MonetaryOperator)

• Ensure Interoperability by the MonetaryAmount

interface

• Precision/scale capabilities should be inherited to its

operational results.


Monetary Amounts (continued)

The API public interface MonetaryAmount{

public CurrencyUnit getCurrency();

public NumberValue getNumber();

public MonetaryContext getMonetaryContext();

public MonetaryAmount with(MonetaryOperator operator);

public <R> R query(MonetaryQuery<R> query);

public MonetaryAmountFactory<? extends MonetaryAmount> getFactory();

…

public boolean isLessThanOrEqualTo(MonetaryAmount amt);

public boolean isLessThan(MonetaryAmount amt);

public boolean isEqualTo(MonetaryAmount amt);

public int signum();

…

public MonetaryAmount add(MonetaryAmount amount);

public MonetaryAmount subtract(MonetaryAmount amount);

public MonetaryAmount divide(long number);

public MonetaryAmount multiply(Number number);

public MonetaryAmount remainder(double number);

…

public MonetaryAmount stripTrailingZeros();

}

12


Monetary Context

Model Amount Capabilities

13

Describes the capabilities of a MonetaryAmount.

Accessible from each MonetaryAmount instance.

Allows querying a feasible implementation type from

MonetaryAmounts.

Contains

common aspects

Max precision, max scale, amount flavor

Arbitrary attributes

E.g. RoundingMode, MathContext, …


Monetary Context (continued)

The API

public final class MonetaryContext extends AbstractContext

implements Serializable {

public static enum AmountFlavor{ PRECISION, PERFORMANCE, UNDEFINED }

public int getPrecision();

public int getMaxScale();

public AmountFlavor getAmountFlavor();

public Class<? extends MonetaryAmount> getAmountType();

public static final class Builder{…}

}

public abstract class AbstractContext implements Serializable{

…

public <T> T getNamedAttribute(Class<T> type, Object key,

T defaultValue);

public <T> T getNamedAttribute(Class<T> type, Object key);

public <T> T getAttribute(Class<T> type, T defaultValue);

public <T> T getAttribute(Class<T> type);

public Set<Class<?>> getAttributeTypes();

}

14


Creating Monetary Amounts

Monetary Amount Factory

15

Creates new instances of MonetaryAmount.

Declares

The concrete MonetaryAmount implementation type

returned.

The min/max MonetaryContext supported.

Can be configured with a target

CurrencyUnit

A numeric value

MonetaryContext.


Creating Monetary Amounts (continued)

Monetary Amount Factory

public interface MonetaryAmountFactory<T extends MonetaryAmount> {

Class<? extends MonetaryAmount> getAmountType();

MonetaryAmountFactory<T> setCurrency(String currencyCode);

MonetaryAmountFactory<T> setCurrency(CurrencyUnit currency);

MonetaryAmountFactory<T> setNumber(double number);

MonetaryAmountFactory<T> setNumber(long number);

MonetaryAmountFactory<T> setNumber(Number number);

MonetaryAmountFactory<T> setContext(MonetaryContext monetaryContext);

MonetaryAmountFactory<T> setAmount(MonetaryAmount amount);

T create();

MonetaryContext getDefaultMonetaryContext();

MonetaryContext getMaximalMonetaryContext();

}

16


Creating Monetary Amounts

Usage Samples

// Using the default type

MonetaryAmount amount1 = MonetaryAmounts.getAmountFactory()

.setCurrency("USD“)

.setNumber(1234566.15)

.create();

// Using an explicit type

Money amount2 = MonetaryAmounts.getAmountFactory(Money.class)



.create();

// Query a matching implementation type

Class<? extends MonetaryAmount> type = MonetaryAmounts.queryAmontType(

new MonetaryContext.Builder()

.setAmountFlavor(

AmountFlavor.PERFORMANT)

.create());

MonetaryAmount amount3 = MonetaryAmounts.getAmountFactory(type)



.create();

17


Extension Points

javax.money

18

cmp Components

Component1

ProvidedInterface1

RequiredInterface

Component2

RequiredInterface


Extension Points

MonetaryOperator

Takes an amount and procudes some other amount.

• With different value

• With different currency

• Or both // @FunctionalInterface

public interface MonetaryOperator {

public MonetaryAmount apply(MonetaryAmount amount);

}

• Operators then can be applied on every MonetaryAmount:

public interface MonetaryAmount{

…

public MonetaryAmount with (MonetaryOperator operator);

…

}

19


Extension Points (continued)

MonetaryOperator: Use Cases

Extend the algorithmic capabilities

• Percentages

• Permil

• Different Minor Units

• Different Major Units

• Rounding

• Currency Conversion

• Financial Calculations

• …

20



MonetaryOperator Example: Rounding and Percentage

21

// round an amount

MonetaryOperator rounding =

MoneyRoundings.getRounding(

MonetaryCurrencies.getCurrency(“USD”));

Money amount = Money.of(“USD”, 12.345567);

Money rounded = amount.with(rounding); // USD 12.35

// MonetaryFunctions, e.g. calculate 3% of it

Money threePercent = rounded.with(

MonetaryFunctions.getPercent(3));

// USD 0.3705



MonetaryQuery

A MonetaryQuery takes an amount and procuces an arbitrary

result:

// @FunctionalInterface

public interface MonetaryQuery<T> {

public T queryFrom(MonetaryAmount amount);

}

Queries then can be applied on every MonetaryAmount:

public interface MonetaryAmount {

…

public <T> T query (MonetaryQuary<T> query);

…

}

22


Currency Conversion

javax.money.convert.*

23


Currency Conversion

ExchangeRate

A ExchangeRate models a conversion between two currencies:

• Base CurrencyUnit

• Terminating/target CurrencyUnit

• Provider

• Conversion Factor, where M(term) = M(base) * f

• Additional attributes (ConversionContext)

• Rate chain (composite rates)

Rates may be direct or derived (composite rates)

24


Currency Conversion

ExchangeRateProvider

// access default provider (chain)

ExchangeRateProvider prov =

MonetaryConversions.getExchangeRateProvider();

// access a provider explicitly

prov = MonetaryConversions.getExchangeRateProvider("IMF");

// access explicit provider chain

prov = MonetaryConversions.getExchangeRateProvider("ECB", "IMF");

// access Exchange rates

ExchangeRate rate = provider.getExchangeRate("EUR", "CHF");

// Passing additional parameters

ExchangeRate rate = provider.getExchangeRate("EUR", "CHF",

ConversionContext.of(

System.currentTimeMillis() + 2000L) );

25 Go for the money - JSR 354 - http://java.net/projects/javamoney


Currency Conversion (continued)

Performing Conversion

Accessing a CurrencyConversion (always targeted to a terminating CurrencyUnit):

// access from a ExchangeRateProvider

ExchangeRateProvider prov = …;

CurrencyConversion conv = prov.getCurrencyConversion("INR");

// access it directly (using default rate chain)

conv = MonetaryConversions.getConversion("INR");

// access it, using explicit provider chain

conv = MonetaryConversions.getConversion("INR", "ECB", "IMF");

Performing conversion:

MonetaryAmount chfAmount = MonetaryAmounts.of("CHF",10.50);

MonetaryAmount inrAmount = chfAmount.with(conv); // around EUR 8.75

26


Formatting and Parsing

javax.money.format.*

27


Formatting and Parsing

MonetaryAmountFormat

Similar to java.text.DecimalFormat, but also ME

compatible

Configured by AmountStyle, CurrencyStyle,

AmountFormatSymbols

Supports also custom formats

Building AmountStyle using a fluent API

Preconfigured format access is also possible



Formatting and Parsing (continued)

MonetaryAmountFormat: Usage Example

// Access a provided format

MonetaryAmountFormat format = MonetaryFormats.getAmountFormat(

new Locale(“”, “in”));

System.out.println(format.format(

Money.of("INR", 39101112.123456))));

output> INR 3,91,01,112.10



JavaMoney OSS Project

org.javamoney.*

30


JavaMoney OSS Project

Extended Currency Services

Currency namespaces (e.g. ISO, VIRTUAL, …)

Currency namespace mapping

Validity Services (Historization API)

• access of historic currency data related to regions

Region Services

Region Forest

• Unicode CLDR region tree

• ISO 2-, 3-letter countries

• Custom Trees

Extendible token-based Formatting API

Financial Calculations & Formulas

31


Links

Current Spec (work in progress, comments allowed): https://docs.google.com/document/d/1FfihURoCYrbkDcSf1W

XM6fHoU3d3tKooMnZLCpmpyV8/edit GitHub Project (JSR and JavaMoney):

https://github.com/JavaMoney/javamoney Umbrella Page: http://javamoney.org JSR 354: http://jcp.org

Java.net Project: http://java.net/projects/javamoney JUG Chennai Adoption (TrakStok):

https://github.com/jugchennaiadoptjava/TrakStok

Twitter: @jsr354 Cash Rounding: http://en.wikipedia.org/wiki/Swedish_rounding

32

https://docs.google.com/document/d/1FfihURoCYrbkDcSf1WXM6fHoU3d3tKooMnZLCpmpyV8/edit



https://github.com/JavaMoney/javamoney

http://javamoney.org/

http://jcp.org/

http://java.net/projects/javamoney

https://github.com/jugchennaiadoptjava/TrakStok

http://en.wikipedia.org/wiki/Swedish_rounding

http://en.wikipedia.org/wiki/Swedish_rounding


Setup

33


Setup

34

• Install VirtualBox, if not yet done, download from https://www.virtualbox.org

• Download the prepared image and start it • Login with debian/debian • Open the IDE of your choice (Eclipse, IntelliJ and

Netbeans are preinstalled and setup) • Update the projects/repositories

• For Contributors:

• Ensure you have a GitHub user account • Create your own Branch of the corresponding repositories

• Switch your local repositories on your VM, on which you want to commit, to your branched repos

https://www.virtualbox.org/





Adoption Areas JSR 354

API Challenge: MoneyMachine

35

Objective: Test the API for usability, make proposals to improve

How:

Checkout/update the MoneyMachine project from https://github.com/atsticks/moneymachine.git

Implement the classes in the src/main/java to make the tests

green (skeletons are already there) The challenge will guide you throughout the whole JSR Overall 34 test cases of different complexity, you may also selct

only a subset ;-) Tell me about improvements

Email [email protected] (please add [moneymachine] in your subject header)

Issues on java.net or gitub Blog your (hopefully positive) experience, twitter, …

https://github.com/atsticks/moneymachine.git

https://github.com/atsticks/moneymachine.git




API Challenge: MoneyMachine Example

36

/**

* This class has to be implemented and helps us giving feedback on the JSR's API. This

* part of the

* project deals with basic aspects such as getting currencies and amounts.

* Created by Anatole on 07.03.14.

*/

public class Basics{

/**

* Get a CurrencyUnit using a currency code.

*

* @param currencyCode the currency code

* @return the corresponding CurrencyUnit instance.

*/

public CurrencyUnit getProvidedCurrency(String currencyCode){

throw new UnsupportedOperationException();

}

/**

* Get a CurrencyUnit using a Locale, modeling a country.

*

* @param locale The country locale.

* @return the corresponding CurrencyUnit instance.

*/

public CurrencyUnit getProvidedCurrency(Locale locale){

throw new UnsupportedOperationException();

}

...

}

Describes

the task to

be done

(incl. Some

hints)

Replace this

with the

code



API Challenge: MoneyMachine Testing

37

To check your

implementation is correct,

simply execute the test suite

Correct ;-)



Helping on the TCK

38

Objective: Help writing the JSRs TCK

How:

If the JSR is completely new: Checkout the slides, read the spec, so you have a basic idea

Branch TCK and RI (sometimes you may also find an issue in the RI)

Update/checkout the JSR’s API, RI, JavaMoney parent and TCK Look for the test classes present in the TCK Select tests you want to contribute and coordinate with me Write the tests, if not sure how, you may ask me ;-) If it is the first time working on a TCK, you may do pair

programming with a more experienced person Commit your code to your branch Create a Git Pull Request



Helping on the TCK (continued)

39

/**

* Test successful conversion for possible currency pairs.<br/>

* Hint: you may only check for rate factory, when using a hardcoded

* ExchangeRateProvider, such a provider

* must be also implemented and registered as an SPI.

*/

@Test @SpecAssertion(id = "432-A1", section="4.3.2")

public void testConversion(){

Assert.fail();

}

Describes the test

very briefly

References the according

section in the spec

Add your test code here.

Hint 1: if you are unsure first write a story line

Hint 2: some aspects may require to implement multiple

tests, just ensure the annotations are on all tests



Extending the Reference Implementation

40

Objective: Adding functonalities to the RI

How:

If the JSR is completely new: Talk with me first

Discuss your ideas with me to see where your idea fits best

Branch RI (and/or JavaMoney Library)

Adding functonalities/tests to the RI (and/or JavaMoney Lib)

Write/enhance documentation Commit your changes Create a Pull Request



Stabilizing JavaMoney Library

41

Objective: Help stabilizing the functionality of JavaMoney

How:

If the JSR is completely new: Talk with me first

Branch JavaMoney Library Write tests, e.g. for financial calculations

Write/enhance documentation

New functionalities: discuss with me first Commit your changes

Create a Pull Request


Q & A

42


The End

43

Download - Adopt JSR 354

Top Related