Jackson Datatype Money
Jackson Datatype Money is a Jackson module to support JSON serialization and deserialization of JavaMoney 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 our API preferences for representing monetary amounts in 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:
<dependency>
<groupId>org.zalando</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:
ObjectMapper mapper = new ObjectMapper()
.registerModule(new MoneyModule());
Alternatively, you can use the SPI capabilities:
ObjectMapper mapper = new ObjectMapper()
.findAndRegisterModules();
Serialization
For serialization this module currently supports javax.money.MonetaryAmount and will, by default, serialize it as:
{
"amount": 99.95,
"currency": "EUR"
}
To serialize number as a JSON string, you have to configure the quoted decimal number value serializer:
ObjectMapper mapper = new ObjectMapper()
.registerModule(new MoneyModule().withQuotedDecimalNumbers());
{
"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:
ObjectMapper mapper = new ObjectMapper()
.registerModule(new MoneyModule().withDefaultFormatting());
... or pass in a MonetaryAmountFormatFactory implementation to the MoneyModule:
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. 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:
ObjectWriter writer = mapper.writer().with(Locale.GERMANY);
writer.writeValueAsString(Money.of(29.95, "EUR"));
{
"amount": 29.95,
"currency": "EUR",
"formatted": "29,95 EUR"
}
The following example uses en_US:
ObjectWriter writer = mapper.writer().with(Locale.US);
writer.writeValueAsString(Money.of(29.95, "USD"));
{
"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:
ObjectMapper mapper = new ObjectMapper()
.registerModule(new MoneyModule()
.withMonetaryAmount(new CustomMonetaryAmountFactory()));
You can also pass in a method reference:
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() |
org.javamoney.moneta.Money |
new MoneyModule().withMoney() |
org.javamoney.moneta.RoundedMoney |
new MoneyModule().withRoundedMoney() |
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:
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:
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.
Getting involved
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.
372 Dec 23, 2022
4 Sep 24, 2021
13 Oct 10, 2022
11 May 24, 2022
19 Aug 12, 2022
2 Feb 17, 2022
3 Jul 7, 2022
41 Dec 18, 2022
4 Dec 30, 2021
1 Oct 21, 2021
4 Dec 19, 2022
1.4k Dec 30, 2022
2k Jan 9, 2023
1.6k Dec 29, 2022
739 Dec 17, 2022
2.4k Dec 29, 2022
1k Dec 22, 2022
2.8k Jan 4, 2023