Serialize and Deserialize Enums with Jackson

In this section, we will understand how we can serialize and deserialize Java Enums by using Jackson 2. In Java, Enumeration is a list of named constants that are used to define a class type. Just like the Java class, Java Enumeration can also have methods, constructors, and instance variables. Java Enums are created by using the enum keyword.

Controlling the Enum Representation

Let's use the enum keyword and understand how we can define Enum:

Shape.Java

enum Shape {
	Circle,
    	Square,
    	Triangle;
 
    	// enum constructor for each constant
    	private Shape() {
        	System.out.println("Constructor called for shape : "+ this.toString());
    	}

	// enum method
	public void shapeInfo() {
        	System.out.println("Universal Shape");
    	}
}

Distance.Java

public enum Distance {
	KILOMETER("km", 1000), 
    	MILE("miles", 1609.34),
    	METER("meters", 1), 
    	INCH("inches", 0.0254),
    	CENTIMETER("cm", 0.01), 
    	MILLIMETER("mm", 0.001);
	
    	private String unit;
    	private final double meters;
	
    	private Distance(String unit, double meters) {
        		this.unit = unit;
        		this.meters = meters;
    	}
    	// standard getters and setters
}

Serializing Enums to JSON

In order to serialize Enum, we take the help of ObjectMapper class. We use the writeValueAsString() method of ObjectMapper class for serializing Enum. If we serialize Enum by using the writeValueAsString() method, it will represent Java Enums as a simple string.

SerializeEnumExample1.java

// import required classes and package if any
import java.util.Scanner;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
// create class SerializeEnumExample1 to serialize Enum with jackson
public class SerializeEnumExample1 {
	// main() method start
	public static void main(String args[]) throws JsonProcessingException {
		// create instance variable
		String enumStr, jsonString;
		// Create scanner class object 
		Scanner sc = new Scanner(System.in);
		// create an instance of ObjectMapper class
		ObjectMapper mapper = new ObjectMapper();
		System.out.println("Enter Enum to serialize.");
		enumStr = sc.nextLine();
		if(enumStr.equals("KILOMETER")) {
			// serialize Enum KILOMETER
			jsonString = mapper.writeValueAsString(Distance.KILOMETER);
		} else if(enumStr.equals("MILE")) {
			// serialize Enum MILE
			jsonString = mapper.writeValueAsString(Distance.MILE);
		} else if(enumStr.equals("METER")) {
			// serialize Enum METER
			jsonString = mapper.writeValueAsString(Distance.METER);
		} else if(enumStr.equals("INCH")) {
			// serialize Enum INCH
			jsonString = mapper.writeValueAsString(Distance.INCH);
		} else if(enumStr.equals("CENTIMETER")) {
			// serialize Enum CENTIMETER
			jsonString = mapper.writeValueAsString(Distance.CENTIMETER);
		} else if(enumStr.equals("MILLIMETER")) {
			// serialize Enum MILLIMETER
			jsonString = mapper.writeValueAsString(Distance.MILLIMETER);
		} else {
			// serialize Enum UNKNOWN
			jsonString = mapper.writeValueAsString(Distance.UNKNOWN);
		}
		
		// close Scanner class object
		sc.close();
		
		System.out.println("Serialize Enum=====>"+jsonString);
		
	}
	
}

Output:

Serialize and Deserialize Enums with Jackson

However, if we marshal Enum to a JSON Object, it will represent the Enum as a proper JSON string. We simply need to alter the Distance.java by simply using the @JsonFormat and making fields public in the following way:

Distance.java

import com.fasterxml.jackson.annotation.JsonFormat;

@JsonFormat(shape = JsonFormat.Shape.OBJECT)
public enum Distance {
	KILOMETER("km", 1000), 
    	MILE("miles", 1609.34),
    	METER("meters", 1), 
    	INCH("inches", 0.0254),
    	CENTIMETER("cm", 0.01), 
    	MILLIMETER("mm", 0.001),
	UNKNOWN("unkown", 0);
	
    	public String unit;
    	public final double meters;
    
    	private Distance(String unit, double meters) {
    		this.unit = unit;
    		this.meters = meters;
    	}
    	// standard getters and setters
}

Now, if we run SerializeEnumExample1.java class, it represents the result in the following JSON string format:

Output:

Enums and @JsonValue

By using the @JsonValue annotation, we can also control the marshaling output for an enum. We simply add @JsonValue annotation on a getter function. In our Distance.java class, we add a getter method by using the @JsonValue annotation. Let's have a look on the updated Distance.java class:

Distance.java

import com.fasterxml.jackson.annotation.JsonValue;
public enum Distance {
	KILOMETER("km", 1000), 
    	MILE("miles", 1609.34),
    	METER("meters", 1), 
    	INCH("inches", 0.0254),
    	CENTIMETER("cm", 0.01), 
    	MILLIMETER("mm", 0.001),
	UNKNOWN("unkown", 0);
	
    public String unit;
    public final double meters;
    
    private Distance(String unit, double meters) {
    	this.unit = unit;
    	this.meters = meters;
    }
    // standard getters and setters
    
    @JsonValue
    public double getEnumValue() {
    	return meters;
    }
}

Now, if we run SerializeEnumExample1.java class, it represents the result in the following format:

Output:

Custom Serializer for Enum

Custom Serializer is another way of controlling the marshaling output for an Enum. We use the custom serializer when we use the older version of Jackson or when we need more customization for the Enum.

Let's first create the custom serializer for the Distance enum:

DistanceCustomSerializer.java

import java.io.IOException;
import com.fasterxml.jackson.core.JsonGenerator;
import com.fasterxml.jackson.databind.JsonSerializer;
import com.fasterxml.jackson.databind.SerializerProvider;

public class DistanceCustomSerializer extends JsonSerializer<Distance> {
@Override
	public void serialize(Distance obj, JsonGenerator gen, SerializerProvider provider) throws IOException {
    	
    		// form JSON using JsonGenerator
    		// writeFieldName() method is used to set the field name
    		// writeString() and writeNumber() methods are used to write String and Number values
		gen.writeStartObject();
		gen.writeFieldName("name");
		gen.writeString(obj.name());
		// check name of the field
		if(obj.name().equals("UNKOWN")) {
			gen.writeFieldName("unknown");
			gen.writeNumber(0);
		} else {
			gen.writeFieldName("unit");
			gen.writeString(obj.getUnitValue());
			gen.writeFieldName("meters");
			gen.writeNumber(obj.getMeterValue());
		}
		gen.writeEndObject();
	}
}

Now, we modify Distance.java class by using the DistanceCustomSerializer with the help of the @JsonSerialize annotation. Let's have a look at the updated Distance.java class.

Distance.java

// import required classes and package if any
import com.fasterxml.jackson.annotation.JsonValue;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;

// use @JsonSerialize annotation to use DistanceCustomSerializer
@JsonSerialize(using = DistanceCustomSerializer.class)
public enum Distance {
	KILOMETER("km", 1000), 
	CENTIMETER("cm", 0.01), 
    	INCH("inches", 0.0254),
    	MILE("miles", 1609.34),
    	MILLIMETER("mm", 0.001),
    	METER("meters", 1), 
    	UNKNOWN("unkown", 0);
	
    	// instance variables
	public String unit;
    	public final double meters;
    
    	// parameterized constructors
    	private Distance(String unit, double meters) {
    		this.unit = unit;
    		this.meters = meters;
    	}
    
    	// standard getters and setters
    	@JsonValue
    	public double getMeterValue() {
    		return meters;
    	}
    	@JsonValue
    	public String getUnitValue() {
    		return unit;
    	}
}

Now, if we run SerializeEnumExample1.java class, it represents the result in the following format:

Output:

Deserialize JSON to Enum

Let's first understand the default behavior of Jackson. By default, the Enum name is used by Jackson to deserialize from JSON.

We have the following JSON string to deserialize:

Now, we deserialize the above string into the Distance.INCH object.

Let's understand how deserialization is done with the help of an example.

Distance.java

// import required classes and package if any
// create Enum Distance
public enum Distance {
	KILOMETER("km", 1000), 
	CENTIMETER("cm", 0.01), 
    	INCH("inches", 0.0254),
    	MILE("miles", 1609.34),
    	MILLIMETER("mm", 0.001),
    	METER("meters", 1), 
    	UNKNOWN("unkown", 0);
	
    	// instance variables
	public String unit;
    	public final double meters;
    
    	// parameterized constructors
    	private Distance(String unit, double meters) {
    		this.unit = unit;
    		this.meters = meters;
    	}
}

DeserializeEnumExample1.java

//import required classes and package, if any

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.JsonMappingException;
import com.fasterxml.jackson.databind.ObjectMapper;

// create class DeserializeEnumExample1 to deserialize JSON to Enum
public class DeserializeEnumExample1 {
	// main() method start
	public static void main(String args[]) throws JsonMappingException, JsonProcessingException {
		
		// jsons string to deserialize
		String jsonString = "{\"distance\":\"INCH\"}";
		
		// create an instance of the ObjectMapper class
		ObjectMapper mapper = new ObjectMapper();
	
		//  deserialize jsonString by using readValue() method of ObjectMapper class
		City obj = mapper.readValue(jsonString, City.class);
		
		// print distance of the City
		System.out.println("Distance of the City: "+ obj.getDistance());
	}	
}
// create class city having a member of type Distance
class City{
	//class variable
	Distance distance;
	// getter/ setters
	public Distance getDistance() {
		return distance;
	}
}

Output:

Deserializing JSON String to Enum Using @JsonValue Annotation

The @JsonValue annotation is one of the annotations which we can use for both serializing and deserializing enums. Enum values are constants, and due to this, @JsonValue annotation can be used for both.

First we simply add the getter method to our Distance.java by using the @JsonValue annotation.

Distance.java

// import required classes and package if any
import com.fasterxml.jackson.annotation.JsonValue;
// create enum Distance by using enum keyword
public enum Distance {
	KILOMETER("km", 1000),
    	METER("meters", 1), 
    	MILLIMETER("mm", 0.001), 
    	INCH("inches", 0.0254),
    	CENTIMETER("cm", 0.01), 
    	MILE("miles", 1609.34),
	UNKNOWN("unkown", 0);
	// instance variable
    	public String unit;
   	public final double meters;
	//parameterized constructor
    	private Distance(String unit, double meters) {
    		this.unit = unit;
    		this.meters = meters;
    	}
    	// getter method annotated with @JsonValue
    	@JsonValue
   	public double getEnumValue() {
    		return meters;
    	}
}

We have the following JSON string to deserialize:

Now, we deserialize the above string into the Distance.INCH object.

Let's understand how deserialization is done with the help of an example.

DeserializeEnumExample2.java

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.JsonMappingException;
import com.fasterxml.jackson.databind.ObjectMapper;

// create class DeserializeEnumExample2 to deserialize JSON to Enum
public class DeserializeEnumExample2 {	
	// main() method start
	public static void main(String args[]) throws JsonMappingException, JsonProcessingException {
		// jsons string to deserialize
		String jsonString = "{\"distance\":\"0.0254\"}";
		// create an instance of the ObjectMapper class
		ObjectMapper mapper = new ObjectMapper();
		//  deserialize jsonString by using readValue() method of ObjectMapper class
		City obj = mapper.readValue(jsonString, City.class);
		// print distance of the City
		System.out.println("Distance of the City: "+ obj.getDistance());
	}
}
// create class city having a member of type Distance
class City{
	
	//class variable
	Distance distance;
	
	// getter/ setters
	public Distance getDistance() {
		return distance;
	}
}

Output:

Deserializing JSON String to Enum using @JsonProperty Annotation

Another way of deserializing the JSON string to Enum is by using the @JsonProperty annotation. In order to deserialize a JSON string, we use the @JsonProperty annotation on the enumeration instance in the following way:

Distance.java

// import required classes and package, if any
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonValue;

//create enum Distance by using enum keyword
public enum Distance {
	@JsonProperty("KM-Distance")
	KILOMETER("km", 1000),
	@JsonProperty("Meter-Distance")
 	METER("meters", 1), 
 	@JsonProperty("Mili-Meter-Distance")
 	MILLIMETER("mm", 0.001), 
 	@JsonProperty("Inch-Distance")
 	INCH("inches", 0.0254),
 	@JsonProperty("CM-Distance")
 	CENTIMETER("cm", 0.01), 
 	@JsonProperty("Mile-Distance")
 	MILE("miles", 1609.34),
 	@JsonProperty("Unkown-Distance")
	UNKNOWN("unkown", 0);
	
	// instance variable
 	public String unit;
	public final double meters;

	//parameterized constructor
 	private Distance(String unit, double meters) {
 		this.unit = unit;
 		this.meters = meters;
 	}
 	// getter method annotated with @JsonValue
}

DeserializeEnumExample3.java

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.JsonMappingException;
import com.fasterxml.jackson.databind.ObjectMapper;

// create class DeserializeEnumExample3 to deserialize JSON to Enum
public class DeserializeEnumExample3 {
	
	// main() method start
	public static void main(String args[]) throws JsonMappingException, JsonProcessingException {
		
		// jsons string to deserialize
		String jsonString = "{\"distance\": \"Mili-Meter-Distance\"}";
		
		// create an instance of the ObjectMapper class
		ObjectMapper mapper = new ObjectMapper();
	
		//deserialize jsonString by using readValue() method of ObjectMapper class
		City obj = mapper.readValue(jsonString, City.class);
		
		// print distance of the City
		System.out.println("Distance of the City: "+ obj.getDistance());
	}
}

// create class city having a member of type Distance
class City{
	
	//class variable
	Distance distance;
	
	// getter/ setters
	public Distance getDistance() {
		return distance;
	}
}

Output:

Deserializing JSON String to Enum Using @JsonCreator Annotation

The @JsonCreator is another annotation that we can use for deserializing Enum. All the methods annotated by @JsonCreator are invoked by Jackson for getting an instance of the enclosing class. In order to deserialize the JSON String to Enum by using the @JsonCreator, we will define the forValues() factory method with the @JsonCreator annotation.

Distance.java

// import required classes and package if any
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
//create enum Distance by using enum keyword
public enum Distance {
	KILOMETER("km", 1000),
 	METER("meters", 1), 
 	MILLIMETER("mm", 0.001), 
 	INCH("inches", 0.0254),
 	CENTIMETER("cm", 0.01), 
 	MILE("miles", 1609.34),
	UNKNOWN("unkown", 0);
	
	// instance variable
 	public String unit;
	public final double meters;
	
	//parameterized constructor
 	private Distance(String unit, double meters) {
 		this.unit = unit;
 		this.meters = meters;
 	}
 	// define the forValues() factory method with the @JsonCreator annotation
 	@JsonCreator
    	public static Distance forValues(@JsonProperty("unit") String unit, @JsonProperty("meters") double meters) {
        // iterate values of distance
 		for (Distance distance : Distance.values()) {
 			//condition to compare unit and meters
            		if (distance.unit.equals(unit) && Double.compare(distance.meters, meters) == 0) {
            			//return distance if condition match
               	 		return distance;
            		}
        	}
        	return null;
    	}
 	// getter method annotated with @JsonValue
}

We have the following JSON string to deserialize:

{
    "distance": {
        "unit":"miles", 
        "meters":1609.34
    }
}

Now, we deserialize the above string into the Distance.INCH object.

Let's understand how deserialization is done with the help of an example.

DeserializeEnumExample4.java

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.JsonMappingException;
import com.fasterxml.jackson.databind.ObjectMapper;

// create class DeserializeEnumExample4 to deserialize JSON to Enum
public class DeserializeEnumExample4 {
	// main() method start
	public static void main(String args[]) throws JsonMappingException, JsonProcessingException {
		
		// jsons string to deserialize
		String jsonString = "{\"distance\": {\"unit\":\"inches\",\"meters\":0.0254}}";
		
		// create an instance of the ObjectMapper class
		ObjectMapper mapper = new ObjectMapper();
	
		//deserialize jsonString by using readValue() method of ObjectMapper class
		City obj = mapper.readValue(jsonString, City.class);
		
		// print distance of the City
		System.out.println("Distance of the City: "+ obj.getDistance());
	}
}

// create class city having a member of type Distance
class City{
	
	//class variable
	Distance distance;
	
	// getter/ setters
	public Distance getDistance() {
		return distance;
	}
}

Output:

Deserializing JSON String to Enum using Custom Deserializer

It is the last way of deserializing JSON String to Enum, which we use when the above-discussed techniques are failed to deserialize the JSON string.

We use the custom deserializer when we use the older version of Jackson or when we have no access to Enum.

We deserialize the following JSON string by using the custom deserializer:

{
    "distance": {
        "unit":"miles", 
        "meters":1609.34
    }
}

DistanceCustomDeserializer.java

import java.io.IOException;
import com.fasterxml.jackson.core.JsonParser;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.DeserializationContext;
import com.fasterxml.jackson.databind.JsonDeserializer;
import com.fasterxml.jackson.databind.JsonNode;

public class DistanceCustomDeserializer extends JsonDeserializer<Distance> {
    @Override
    public Distance deserialize(JsonParser jsonParser, DeserializationContext ctxt) throws IOException, JsonProcessingException {
        
    	// read data as JsonNode
    	JsonNode node = jsonParser.getCodec().readTree(jsonParser);

    	// get unit value as text and store in a variable
        String unit = node.get("unit").asText();
        
        // get unit value as text and store in a variable
        double meters = node.get("meters").asDouble();
        
        //iterate all the values of Distance 
        for (Distance distance : Distance.values()) {
           
        	// compare unit and meter values
            	if (distance.getUnitValue().equals(unit) && Double.compare(distance.getMeterValue(), meters) == 0) {
                	// return distance id comparison done successfully
            		return distance;
            	}
        }
        return null;
    }
}

Now, if we run DeserializeEnumExample4.java class, it represents the result in the following JSON string format:

Output: