From 57f45fd9163acaaf1e2f2313c5892009066c3cc9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Willi=20Sch=C3=B6nborn?= Date: Fri, 25 Mar 2016 10:58:32 +0100 Subject: [PATCH 1/8] Updated readme --- CONTRIBUTING.md | 13 ++++++ README.md | 122 +++++++++++++++++++++++++++--------------------- 2 files changed, 82 insertions(+), 53 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..00b242b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,13 @@ +# Contributing + +## Pull requests only + +**DON'T** push to the master branch directly. Always use pull requests and let people discuss changes in pull request. +Pull requests should only be merged after all discussions have been concluded and at least 1 reviewer gave his +**approval**. + +## Guidelines + +- **every change** needs a test +- required 100% code coverage +- keep the current code style \ No newline at end of file diff --git a/README.md b/README.md index ea08217..3edd575 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,14 @@ [![Release](https://img.shields.io/github/release/zalando/jackson-datatype-money.svg)](https://github.com/zalando/jackson-datatype-money/releases) [![Maven Central](https://img.shields.io/maven-central/v/org.zalando/jackson-datatype-money.svg)](https://maven-badges.herokuapp.com/maven-central/org.zalando/jackson-datatype-money) -*Jackson Datatype Money* is a [Jackson](https://github.com/codehaus/jackson) module to support JSON serialization and deserialization of [Java Money](https://github.com/JavaMoney/jsr354-api) data types. It fills a niche, in that it connects the Java Money and Jackson libraries so that they work seamlessly together, without requiring additional developer effort. In doing so, it aims to perform a small but repetitive task — once and for all. +*Jackson Datatype Money* is a [Jackson](https://github.com/codehaus/jackson) module to support JSON serialization and +deserialization of [Java Money](https://github.com/JavaMoney/jsr354-api) data types. It fills a niche, in that it +connects the Java Money and Jackson libraries so that they work seamlessly together, without requiring additional +developer effort. In doing so, it aims to perform a small but repetitive task — once and for all. -The maintainers of Jackson Datatype Money build APIs, so you might notice that this project reflects an API design point of view. In developing our work, we sought a reusable library that would enable us to express monetary amounts in JSON while reflecting our API preferences. We couldn't find one, so we created one. +The maintainers of Jackson Datatype Money build APIs, so you might notice that this project reflects an API design +point of view. In developing our work, we sought a reusable library that would enable us to express monetary amounts in +JSON while reflecting our API preferences. We couldn't find one, so we created one. ## Features - enables you to express monetary amounts in JSON @@ -16,16 +21,22 @@ The maintainers of Jackson Datatype Money build APIs, so you might notice that t - allows you to implement RESTful API endpoints that format monetary amounts based on the Accept-Language header - is unique and flexible -# Getting Started -## Requirements +```json +{ + "amount": 29.95, + "currency": "EUR" +} +``` + +## Dependencies - Java 7 or higher - Any build tool using Maven Central, or direct download - Jackson - Java Money -## Dependencies +## Installation -Run this module: +Add the following dependency to your project: ```xml @@ -36,7 +47,9 @@ Run this module: ``` For ultimate flexibility, this module is compatible with the official version as well as the backport of Java Money. The actual version will be selected by a profile based on the current JDK version. -## Using It +## Configuration + +Register the module with your `ObjectMapper`: ```java ObjectMapper mapper = new ObjectMapper() @@ -50,53 +63,20 @@ ObjectMapper mapper = new ObjectMapper() .findAndRegisterModules(); ``` -## Supported Types -The module supports de/serialization of the following types: - -**[`java.util.Currency`](https://docs.oracle.com/javase/8/docs/api/java/util/Currency.html)** - -`Currency.getInstance("EUR")` produces an [ISO-4217](http://en.wikipedia.org/wiki/ISO_4217) currency code, e.g. `"EUR"`. - -**[`javax.money.CurrencyUnit`](https://github.com/JavaMoney/jsr354-api/blob/master/src/main/java/javax/money/CurrencyUnit.java)** - -`Monetary.getCurrency("EUR")` produces an [ISO-4217](http://en.wikipedia.org/wiki/ISO_4217) currency code, e.g. `"EUR"`. - -**[`javax.money.MonetaryAmount`](https://github.com/JavaMoney/jsr354-api/blob/master/src/main/java/javax/money/MonetaryAmount.java)** - -By default, the `MoneyModule` will use `org.javamoney.moneta.Money` as an implementation for `javax.money.MonetaryAmount` when deserializing money values. If you need a different implementation, you can pass an implementation of `MonetaryAmountFactory` to the `MoneyModule`: - -```java -ObjectMapper mapper = new ObjectMapper() - .registerModule(new MoneyModule(new FastMoneyFactory())); -``` - -These implementations come with Java Money: - -| `MonetaryAmount` Implementation | Factory | -|-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| -| `org.javamoney.moneta.FastMoney` | [`org.zalando.jackson.datatype.money.FastMoneyFactory`](src/main/java/org/zalando/jackson/datatype/money/FastMoneyFactory.java) | -| `org.javamoney.moneta.Money` | [`org.zalando.jackson.datatype.money.MoneyFactory`](src/main/java/org/zalando/jackson/datatype/money/MoneyFactory.java) | -| `org.javamoney.moneta.RoundedMoney` | [`org.zalando.jackson.datatype.money.RoundedMoneyFactory`](src/main/java/org/zalando/jackson/datatype/money/RoundedMoneyFactory.java) | | - -If you're using Java 8, you can also pass in a method reference: - -```java -ObjectMapper mapper = new ObjectMapper() - .registerModule(new MoneyModule(FastMoney::of)); -``` +### Serialization -`Money.of(29.95, "EUR")` produces the following structure: +For serialization this module currently supports the following data types: -```json -{ - "amount": 29.95, - "currency": "EUR" -} -``` +| Input | Standard | Output | +|-----------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|----------------------------------------| +| [`java.util.Currency`](https://docs.oracle.com/javase/8/docs/api/java/util/Currency.html) | [ISO-4217](http://en.wikipedia.org/wiki/ISO_4217) | `EUR` | +| [`javax.money.CurrencyUnit`](https://github.com/JavaMoney/jsr354-api/blob/master/src/main/java/javax/money/CurrencyUnit.java) | [ISO-4217](http://en.wikipedia.org/wiki/ISO_4217) | `EUR` | +| [`javax.money.MonetaryAmount`](https://github.com/JavaMoney/jsr354-api/blob/master/src/main/java/javax/money/MonetaryAmount.java) | | `{"amount": 99.95, "currency": "EUR"}` | -## Formatting +### Formatting -Formatting of monetary amounts is **disabled by default**. To enable it, you have to pass in a `MonetaryAmountFormatFactory` implementation to the `MoneyModule`: +A special feature for serializing monetary amounts is *formatting*, which is **disabled by default**. To enable it, you +have to pass in a `MonetaryAmountFormatFactory` implementation to the `MoneyModule`: ```java ObjectMapper mapper = new ObjectMapper() @@ -105,7 +85,9 @@ ObjectMapper mapper = new ObjectMapper() The `DefaultMonetaryAmountFormatFactory` delegates directly to `MonetaryFormats.getAmountFormat(Locale, String...)`. -Formatting only affects the serialization and can be customized based on the *current* locale, as defined by the [`SerializationConfig`](http://wiki.fasterxml.com/SerializationConfig). This allows to implement RESTful API endpoints that format monetary amounts based on the `Accept-Language` header. +Formatting only affects the serialization and can be customized based on the *current* locale, as defined by the +[`SerializationConfig`](http://wiki.fasterxml.com/SerializationConfig). This allows to implement RESTful API endpoints +that format monetary amounts based on the `Accept-Language` header. The first example serializes a monetary amount using the `de_DE` locale: @@ -137,5 +119,39 @@ writer.writeValueAsString(Money.of(29.95 "USD")); } ``` -## Contributing -To contribute to Jackson Datatype Money, simply make a pull request and add a brief description (1-2 sentences) of your addition or change. Please note that we aim to keep this project straightforward and focused. We are not looking to add lots of features; we just want it to keep doing what it does, as well and as powerfully as possible. +More sophisticated formatting rules can be supported by implementing `MonetaryAmountFormatFactory` directly. + +### Deserialization + +This module will use `org.javamoney.moneta.Money` as an implementation for `javax.money.MonetaryAmount` when +deserializing money values. If you need a different implementation, you can pass an implementation of +`MonetaryAmountFactory` to the `MoneyModule`: + +```java +ObjectMapper mapper = new ObjectMapper() + .registerModule(new MoneyModule(new FastMoneyFactory())); +``` + +If you're using Java 8, you can also pass in a method reference: + +```java +ObjectMapper mapper = new ObjectMapper() + .registerModule(new MoneyModule(FastMoney::of)); +``` + +*Jackson Datatype Money* comes with the following factories: + +| `MonetaryAmount` Implementation | Factory | +|-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| +| `org.javamoney.moneta.FastMoney` | [`org.zalando.jackson.datatype.money.FastMoneyFactory`](src/main/java/org/zalando/jackson/datatype/money/FastMoneyFactory.java) | +| `org.javamoney.moneta.Money` | [`org.zalando.jackson.datatype.money.MoneyFactory`](src/main/java/org/zalando/jackson/datatype/money/MoneyFactory.java) | +| `org.javamoney.moneta.RoundedMoney` | [`org.zalando.jackson.datatype.money.RoundedMoneyFactory`](src/main/java/org/zalando/jackson/datatype/money/RoundedMoneyFactory.java) | | + +## Getting help + +If you have questions, concerns, bug reports, etc, please file an issue in this repository's Issue Tracker. + +## Getting involved + +To contribute, simply make a pull request and add a brief description (1-2 sentences) of your addition or change. For +more details check the [contribution guidelines](CONTRIBUTING.md). \ No newline at end of file From ed94da60c93cc94c740fc46ea2fc6394ae84b875 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Willi=20Sch=C3=B6nborn?= Date: Fri, 25 Mar 2016 10:59:51 +0100 Subject: [PATCH 2/8] Moved example --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 3edd575..39ef82f 100644 --- a/README.md +++ b/README.md @@ -12,14 +12,7 @@ developer effort. In doing so, it aims to perform a small but repetitive task The maintainers of Jackson Datatype Money build APIs, so you might notice that this project reflects an API design point of view. In developing our work, we sought a reusable library that would enable us to express monetary amounts in -JSON while reflecting our API preferences. We couldn't find one, so we created one. - -## Features -- enables you to express monetary amounts in JSON -- can be used in a REST APIs -- offers customizable serialization by locale -- allows you to implement RESTful API endpoints that format monetary amounts based on the Accept-Language header -- is unique and flexible +JSON while reflecting our API preferences, as shown in the following example. We couldn't find one, so we created one. ```json { @@ -28,6 +21,13 @@ JSON while reflecting our API preferences. We couldn't find one, so we created o } ``` +## Features +- enables you to express monetary amounts in JSON +- can be used in a REST APIs +- offers customizable serialization by locale +- allows you to implement RESTful API endpoints that format monetary amounts based on the Accept-Language header +- is unique and flexible + ## Dependencies - Java 7 or higher - Any build tool using Maven Central, or direct download From 28f6907ca8f9d1199ad1c63d45d27f7d2fe54298 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Willi=20Sch=C3=B6nborn?= Date: Fri, 25 Mar 2016 11:04:54 +0100 Subject: [PATCH 3/8] Added usage --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index 39ef82f..3cd919c 100644 --- a/README.md +++ b/README.md @@ -147,6 +147,20 @@ ObjectMapper mapper = new ObjectMapper() | `org.javamoney.moneta.Money` | [`org.zalando.jackson.datatype.money.MoneyFactory`](src/main/java/org/zalando/jackson/datatype/money/MoneyFactory.java) | | `org.javamoney.moneta.RoundedMoney` | [`org.zalando.jackson.datatype.money.RoundedMoneyFactory`](src/main/java/org/zalando/jackson/datatype/money/RoundedMoneyFactory.java) | | +## Usage + +After registering and configuring the module you're now free to directly use `MonetaryAmount` in your data types: + +```java +import javax.money.MonetaryAmount; + +public class Product { + private String sku; + private MonetaryAmount price; + ... +} +``` + ## Getting help If you have questions, concerns, bug reports, etc, please file an issue in this repository's Issue Tracker. From 4d8b5dd82b07b2710596574786ff405b28d02fb2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Willi=20Sch=C3=B6nborn?= Date: Fri, 25 Mar 2016 11:06:12 +0100 Subject: [PATCH 4/8] Wording --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3cd919c..e17d23e 100644 --- a/README.md +++ b/README.md @@ -123,7 +123,7 @@ More sophisticated formatting rules can be supported by implementing `MonetaryAm ### Deserialization -This module will use `org.javamoney.moneta.Money` as an implementation for `javax.money.MonetaryAmount` when +This module will use `org.javamoney.moneta.Money` as an implementation for `javax.money.MonetaryAmount` by default when deserializing money values. If you need a different implementation, you can pass an implementation of `MonetaryAmountFactory` to the `MoneyModule`: From a85a77f8ee2e7834bf39b129e75642fedc9b8d22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Willi=20Sch=C3=B6nborn?= Date: Fri, 25 Mar 2016 11:08:57 +0100 Subject: [PATCH 5/8] More wording --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e17d23e..51c36f1 100644 --- a/README.md +++ b/README.md @@ -124,8 +124,8 @@ More sophisticated formatting rules can be supported by implementing `MonetaryAm ### Deserialization This module will use `org.javamoney.moneta.Money` as an implementation for `javax.money.MonetaryAmount` by default when -deserializing money values. If you need a different implementation, you can pass an implementation of -`MonetaryAmountFactory` to the `MoneyModule`: +deserializing money values. If you need a different implementation, you can pass a different `MonetaryAmountFactory` +to the `MoneyModule`: ```java ObjectMapper mapper = new ObjectMapper() @@ -139,7 +139,7 @@ ObjectMapper mapper = new ObjectMapper() .registerModule(new MoneyModule(FastMoney::of)); ``` -*Jackson Datatype Money* comes with the following factories: +*Jackson Datatype Money* comes with support for all `MonetaryAmount` implementations from the Moneta: | `MonetaryAmount` Implementation | Factory | |-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| From 4c7e4ad5c235f37fa26372c57f0368b449f00a89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Willi=20Sch=C3=B6nborn?= Date: Fri, 25 Mar 2016 11:09:37 +0100 Subject: [PATCH 6/8] Fixed grammar --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 51c36f1..edcff4c 100644 --- a/README.md +++ b/README.md @@ -139,7 +139,8 @@ ObjectMapper mapper = new ObjectMapper() .registerModule(new MoneyModule(FastMoney::of)); ``` -*Jackson Datatype Money* comes with support for all `MonetaryAmount` implementations from the Moneta: +*Jackson Datatype Money* comes with support for all `MonetaryAmount` implementations from Moneta, the reference +implementation of Java Money: | `MonetaryAmount` Implementation | Factory | |-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| From 61b3ede2202f8edb6e8eddf1b6cad55ffac9f3cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Willi=20Sch=C3=B6nborn?= Date: Fri, 25 Mar 2016 11:29:38 +0100 Subject: [PATCH 7/8] Fixed travis config --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 5d18f1e..883665e 100644 --- a/.travis.yml +++ b/.travis.yml @@ -10,7 +10,7 @@ script: - mvn clean verify after_success: - - coveralls:report + - mvn coveralls:report notifications: email: From 1b74af46c23e8b0ec377953d56860e04c38b0aa6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Willi=20Sch=C3=B6nborn?= Date: Sat, 26 Mar 2016 20:41:57 +0100 Subject: [PATCH 8/8] Reverted deletion of contribution guideline --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index edcff4c..7e2fcb8 100644 --- a/README.md +++ b/README.md @@ -168,5 +168,7 @@ If you have questions, concerns, bug reports, etc, please file an issue in this ## Getting involved -To contribute, simply make a pull request and add a brief description (1-2 sentences) of your addition or change. For -more details check the [contribution guidelines](CONTRIBUTING.md). \ No newline at end of file +To contribute, simply make a pull request and add a brief description (1-2 sentences) of your addition or change. +Please note that we aim to keep this project straightforward and focused. We are not looking to add lots of features; +we just want it to keep doing what it does, as well and as powerfully as possible. For more details check the +[contribution guidelines](CONTRIBUTING.md). \ No newline at end of file