Move jackson-datatype-money module from zalando

README.md

@@ -6,6 +6,7 @@ datatype modules to support 3rd party libraries.
 Currently included are:
 
 * [jackson-datatype-joda-money](joda-money/) for [Joda-Money](https://www.joda.org/joda-money/) datatypes
+* [jackson-datatype-money](javax-money/) for [JavaMoney](https://javamoney.github.io/) datatypes (starting with Jackson 2.19)
 * JSR-353/JSON-P: 2 variants (starting with Jackson 2.12.2)
     * [jackson-datatype-jsr353](jsr-353/) for older "javax.json" [JSR-353](https://www.jcp.org/en/jsr/detail?id=353) (aka JSON-P) datatypes (package `javax.json`)
     * [jackson-datatype-jakarta-jsonp](jakarta-jsonp/) for newer "Jakarta" JSON-P datatypes (package `jakarta.json`)
@@ -16,6 +17,7 @@ Currently included are:
 Note that this repo was created for Jackson 2.11: prior to this, individual datatype
 modules had their own repositories.
 
+
 ## License
 
 All modules are licensed under [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt).
@@ -62,6 +64,7 @@ mapper.registerModule(new JSONPModule()); // new (jakarta) json-P API
 ObjectMapper mapper = JsonMapper.builder()
     .addModule(new JsonOrgModule())
     .addModule(new JodaMoneyModule())
+    .addModule(new MoneyModule())
     // ONE of these (not both):
     .addModule(new JSR353Module()) // old (javax) json-p API
     .addModule(new JSONPModule()) // new (jakarta) json-P API

javax-money/MONEY.md

@@ -0,0 +1,118 @@
+# Representing Money in JSON
+
+> A large proportion of the computers in this world manipulate money, so it's always puzzled me that money isn't actually a first class data type in any mainstream programming language.
+>
+> [Martin Fowler](https://martinfowler.com/eaaCatalog/money.html)
+
+Unfortunately JSON is no different. This document tries to change that by proposing and comparing different styles to represent money, some inspired by external sources and some based on our own experience.
+
+## ⚠️ Monetary amounts ≠ floats
+
+Before we dive into details, always keep the following in mind. However you desire to format money in JSON, nothing changes the fact that you should...
+
+> **Never hold monetary values [..] in a float variable.** Floating point is not suitable for this work, and you must use either [fixed-point](#fixed-point) or [decimal](#decimal) values.
+>  
+> [Coinkite: Common Terms and Data Objects](https://web.archive.org/web/20150924073850/https://docs.coinkite.com/api/common.html)
+
+## Styles
+
+We identified the following styles that all of different advantages and disadvantages that are discussed in their respective section.
+
+| Style                              | Expressive | Arithmetic | Pitfalls / Misuses |
+|------------------------------------|------------|------------|--------------------|
+| [Decimal](#decimal)                | ✔          | ✔          | Precision          |
+| [Quoted Decimal](#quoted-decimal)  | ✔          | ✘          | Parsing            |
+| [Fixed Point](#fixed-point)        | ✘          | ✔          | Mixed scales       |
+| [Mixed](#mixed)                    | ✘          | ✔          | Consistency        |
+
+### Decimal
+
+The most straightforward way to represent a monetary amount would be a base-10 decimal number:
+
+```json
+{
+  "amount": 49.95,
+  "currency": "EUR"
+}
+```
+
+It's expressive, readable and allows arithmetic operations. The downside is that most [JSON decoders will treat it as a floating point](https://tools.ietf.org/html/rfc7159#section-6) number which is very much undesirable.
+
+Most programming languages have support for arbitrary-precision [decimals](#decimal-implementations) and JSON decoders that can be configured to use them. In general it can be considered to be a problem of the implementation, not the format itself.
+
+### Quoted Decimal
+
+Same as  [Decimal](#decimal) but quoted so your JSON decoder treats it as a string:
+
+```json
+{
+  "amount": "49.95",
+  "currency": "EUR"
+}
+```
+
+It solves the precision problem of decimals on the expense of performing arithmetic operations on it. It also requires a two-phase parsing, i.e. parsing the JSON text into a data structure and then parsing quoted amounts into decimals.
+
+### Fixed Point
+
+> A value of a fixed-point data type is essentially an integer that is scaled by an implicit specific factor determined by the type.
+>
+> [Wikipedia: Fixed-point arithmetic](https://en.wikipedia.org/wiki/Fixed-point_arithmetic)
+
+```json
+{
+  "amount": 4995,
+  "currency": "EUR"
+}
+```
+
+The implicit scaling factor is defined as (0.1 raised to the power of) the currency's [default number of fraction digits](http://www.localeplanet.com/icu/currency.html).
+
+In rare cases one might need a higher precision, e.g. to have sub-cent. In this case the scale can be defined explicitly:
+
+```json
+{
+  "amount": 499599,
+  "currency": "EUR",
+  "scale": 4
+}
+```
+
+The downside with fixed-point amounts is that reading them is a bit harder and arithmetic with mixed scale amounts can be tricky and error-prone. 
+
+### Mixed
+
+As a way to counter all negative aspects of the styles above one idea would be to have a single object that contains all of the formats:
+
+```json
+{
+  "decimal": 49.95,
+  "quoted_decimal": "49.95",
+  "fixed_point": 4995,
+  "scale": 2,
+  "currency": "EUR"
+}
+```
+
+Decoders can choose the representation that fits them the best. Encoders on the other hand have the harder task by providing all of them and making sure that all values are in fact consistent.
+
+## Decimal Implementations
+
+| Language   | Implementation                                                                              |
+|------------|---------------------------------------------------------------------------------------------|
+| C#         | [decimal](https://msdn.microsoft.com/en-us/library/364x0z75.aspx)                           |
+| Java       | [java.math.BigDecimal](https://docs.oracle.com/javase/8/docs/api/java/math/BigDecimal.html) |
+| JavaScript | [decimal.js](https://github.com/MikeMcl/decimal.js/)                                        |
+| Python     | [decimal.Decimal](https://docs.python.org/2/library/decimal.html)                           |
+
+## Credits and References
+
+- [Coinkite: Currency Amounts](https://web.archive.org/web/20150924073850/https://docs.coinkite.com/api/common.html#currency-amounts)
+- [Culttt: How to handle money and currency in web applications](http://culttt.com/2014/05/28/handle-money-currency-web-applications/)
+- [Currency codes - ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)
+- [LocalePlanet: ICU Currencies](http://www.localeplanet.com/icu/currency.html)
+- [RFC 7159:  The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc7159#section-6)
+- [Stackoverflow: What is the standard for formatting currency values in JSON?](http://stackoverflow.com/questions/30249406/what-is-the-standard-for-formatting-currency-values-in-json)
+- [Stackoverflow: Why not use Double or Float to represent currency?](http://stackoverflow.com/questions/3730019/why-not-use-double-or-float-to-represent-currency/3730040#3730040)
+- [TechEmpower: Mangling JSON numbers](https://www.techempower.com/blog/2016/07/05/mangling-json-numbers/)
+- [Wikipedia: Fixed-point arithmetic](https://en.wikipedia.org/wiki/Fixed-point_arithmetic)

javax-money/README.md

@@ -0,0 +1,214 @@
+# Jackson Datatype Money
+
+*Jackson Datatype Money* is a [Jackson](https://github.com/codehaus/jackson) module to support JSON serialization and
+deserialization of [JavaMoney](https://github.com/JavaMoney/jsr354-api) data types. It fills a niche, in that it
+integrates JavaMoney and Jackson 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.
+
+This library reflects an opinionated API [representation of monetary amounts in JSON](MONEY.md)
+
+With this library, it is possible to represent monetary amounts in JSON as follows:
+
+```json
+{
+  "amount": 29.95,
+  "currency": "EUR"
+}
+```
+
+## Features
+
+- enables you to express monetary amounts in JSON
+- can be used in a REST APIs
+- customized field names
+- localization of formatted monetary amounts
+- allows you to implement RESTful API endpoints that format monetary amounts based on the Accept-Language header
+- is unique and flexible
+
+## Dependencies
+
+- Java 8 or higher
+- Any build tool using Maven Central, or direct download
+- Jackson
+- JavaMoney
+
+## Installation
+
+Add the following dependency to your project:
+
+```xml
+
+<dependency>
+    <groupId>com.fasterxml.jackson.datatype</groupId>
+    <artifactId>jackson-datatype-money</artifactId>
+    <version>${jackson-datatype-money.version}</version>
+</dependency>
+```
+
+For ultimate flexibility, this module is compatible with the official version as well as the backport of JavaMoney. The
+actual version will be selected by a profile based on the current JDK version.
+
+## Configuration
+
+Register the module with your `ObjectMapper`:
+
+```java
+ObjectMapper mapper = new ObjectMapper()
+        .registerModule(new MoneyModule());
+```
+
+Alternatively, you can use the SPI capabilities:
+
+```java
+ObjectMapper mapper = new ObjectMapper()
+        .findAndRegisterModules();
+```
+
+### Serialization
+
+For serialization this module currently supports
+[
+`javax.money.MonetaryAmount`](https://github.com/JavaMoney/jsr354-api/blob/master/src/main/java/javax/money/MonetaryAmount.java)
+and will, by default, serialize it as:
+
+```json
+{
+  "amount": 99.95,
+  "currency": "EUR"
+}
+```
+
+To serialize number as a JSON string, you have to configure the quoted decimal number value serializer:
+
+```java
+ObjectMapper mapper = new ObjectMapper()
+        .registerModule(new MoneyModule().withQuotedDecimalNumbers());
+```
+
+```json
+{
+  "amount": "99.95",
+  "currency": "EUR"
+}
+```
+
+### Formatting
+
+A special feature for serializing monetary amounts is *formatting*, which is **disabled by default**. To enable it, you
+have to either enable default formatting:
+
+```java
+ObjectMapper mapper = new ObjectMapper()
+        .registerModule(new MoneyModule().withDefaultFormatting());
+```
+
+... or pass in a `MonetaryAmountFormatFactory` implementation to the `MoneyModule`:
+
+```java
+ObjectMapper mapper = new ObjectMapper()
+        .registerModule(new MoneyModule()
+                .withFormatting(new CustomMonetaryAmountFormatFactory()));
+```
+
+The default formatting 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`](https://fasterxml.github.io/jackson-databind/javadoc/2.0.0/com/fasterxml/jackson/databind/SerializationConfig.html#with\(java.util.Locale\)).
+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:
+
+```java
+ObjectWriter writer = mapper.writer().with(Locale.GERMANY);
+writer.
+
+writeValueAsString(Money.of(29.95, "EUR"));
+```
+
+```json
+{
+  "amount": 29.95,
+  "currency": "EUR",
+  "formatted": "29,95 EUR"
+}
+```
+
+The following example uses `en_US`:
+
+```java
+ObjectWriter writer = mapper.writer().with(Locale.US);
+writer.
+
+writeValueAsString(Money.of(29.95, "USD"));
+```
+
+```json
+{
+  "amount": 29.95,
+  "currency": "USD",
+  "formatted": "USD29.95"
+}
+```
+
+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` by default when
+deserializing money values. If you need a different implementation, you can pass a different `MonetaryAmountFactory`
+to the `MoneyModule`:
+
+```java
+ObjectMapper mapper = new ObjectMapper()
+        .registerModule(new MoneyModule()
+                .withMonetaryAmount(new CustomMonetaryAmountFactory()));
+```
+
+You can also pass in a method reference:
+
+```java
+ObjectMapper mapper = new ObjectMapper()
+        .registerModule(new MoneyModule()
+                .withMonetaryAmount(FastMoney::of));
+```
+
+*Jackson Datatype Money* comes with support for all `MonetaryAmount` implementations from Moneta, the reference
+implementation of JavaMoney:
+
+| `MonetaryAmount` Implementation     | Factory                                                                                                               |
+|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| `org.javamoney.moneta.FastMoney`    | [`new MoneyModule().withFastMoney()`](src/main/java/com/fasterxml/jackson/datatype/money/FastMoneyFactory.java)       |
+| `org.javamoney.moneta.Money`        | [`new MoneyModule().withMoney()`](src/main/java/com/fasterxml/jackson/datatype/money/MoneyFactory.java)               |
+| `org.javamoney.moneta.RoundedMoney` | [`new MoneyModule().withRoundedMoney()`](src/main/java/com/fasterxml/jackson/datatype/money/RoundedMoneyFactory.java) |                                                                                                                             |
+
+Module supports deserialization of amount number from JSON number as well as from JSON string without any special
+configuration required.
+
+### Custom Field Names
+
+As you have seen in the previous examples the `MoneyModule` uses the field names `amount`, `currency` and `formatted`
+by default. Those names can be overridden if desired:
+
+```java
+ObjectMapper mapper = new ObjectMapper()
+        .registerModule(new MoneyModule()
+                .withAmountFieldName("value")
+                .withCurrencyFieldName("unit")
+                .withFormattedFieldName("pretty"));
+```
+
+## 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;
+    ...
+}
+```