Last modified: November 28, 2019
The early-bird price of the new Learn Spring Security OAuth course packages will increase by $50 on Wednesday:
1. Overview
This quick tutorial will show how to control the way Java Enums are serialized and deserialized with Jackson 2.
To dig a little deeper and learn other cool things we can do Jackson 2 – head on over to the main Jackson tutorial.
2. Controlling the Enum Representation
Let’s define the following Enum:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
3. Serializing Enums to JSON
3.1. Default Enum Representation
By default, Jackson will represent Java Enums as simple String – for example:
1 |
|
Will result in:
1 |
|
What we would like to get when marshaling this Enum to a JSON Object is to give something like:
1 |
|
3.2. Enum as JSON Object
Starting with Jackson 2.1.2, there is now a configuration option that can handle this kind of representation. This can be done via the @JsonFormat annotation at the class level:
1 2 |
|
This will lead to the desired result when serializing this enum for Distance.MILE:
1 |
|
3.3. Enums and @JsonValue
Yet another simple way of controlling the marshaling output for an enum is using the @JsonValue annotation on a getter:
1 2 3 4 5 6 7 8 |
|
What we’re expressing here is that getMeters() is the actual representation of this enum. So, the result of serializing will be:
1 |
|
3.4. Custom Serializer for Enum
Before Jackson 2.1.2, or if even more customization is required for the enum, we can use a custom Jackson serializer. First, we'll need to define it:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
|
We will now apply the serializer to the class that will be serialized:
1 2 |
|
Which results in:
1 |
|
4. Deserializing JSON to Enum
First, let's define a City class that has a Distance member:
1 2 3 4 5 |
|
Next, we'll discuss the different ways of deserializing a JSON string to an Enum.
4.1. Default Behavior
By default, Jackson will use the Enum name to deserialize from JSON.
For example, it will deserialize the JSON:
1 |
|
To a Distance.KILOMETER object:
1 2 |
|
4.2. Using @JsonValue
We've learned how to use @JsonValue to serialize Enums. We can use the same annotation for deserialization as well. This is possible because Enum values are constants.
First, let's use @JsonValue with one of the getter methods — getMeters():
1 2 3 4 5 6 7 8 |
|
Now, the return value of getMeters() method represents the Enum objects. Thus, when deserializing the sample JSON:
1 |
|
Jackson will look for the Enum object that has a getMeters() return value of 0.0254. In this case, the object is Distance.INCH:
1 |
|
4.3. Using @JsonProperty
The @JsonProperty annotation is used on enumeration instances:
1 2 3 4 5 6 7 8 |
|
By using this annotation, we are simply telling Jackson to map the value of the @JsonProperty to the object annotated with this value.
As a result of the above declaration, the example JSON string:
1 |
|
Will be mapped to the Distance.KILOMETER object:
1 |
|
4.4. Using @JsonCreator
Jackson invokes methods annotated with @JsonCreator to get an instance of the enclosing class.
Consider the JSON representation:
1 2 3 4 5 6 |
|
Now, let's define the forValues() factory method with the @JsonCreator annotation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
Note the use of @JsonProperty annotation to bind the JSON fields with the method arguments.
Then, when we deserialize the JSON sample, we'll get the result:
1 |
|
4.5. Using a Custom Deserializer
A custom deserializer can be used if none of the described techniques are available. For example, we might have no access to the Enum source code, or we might be using an older Jackson version that doesn't support one or more of the annotations covered so far.
According to our custom deserialization article, in order to deserialize the JSON provided in the previous section, we'll start by creating the deserialization class:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
|
Next, we use the @JsonDeserialize annotation on the Enum to specify our custom deserializer:
1 2 3 4 |
|
And our result is:
1 |
|
5. Conclusion
This article illustrated how to gain better control over serialization and deserialization processes and formats of Java Enums.
The implementation of all these examples and code snippets can be found over on GitHub.