JSON Deserialization with Multiple Parameters Constructor Using Jackson

1. Introduction

In this tutorial, we’ll learn how to deserialize JSON into Java objects using multi-parameter constructors with Jackson.

By default, Jackson requires a default constructor that doesn’t accept any parameters. The fields are set using setter methods or reflection. If we want Jackson to use a non-default constructor, we need to annotate that constructor with the @JsonCreator annotation. This annotation can be applied to constructors and static factory methods of records and enums. In this tutorial, we’ll have a look at all these cases.

We’ll also look at the options Jackson provides to reduce the number of annotations needed for deserialization.

2. Setup

2.1. Maven Dependencies

In addition to the basic Jackson dependency, we need Jackson’s parameter names module:

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>2.17.2</version>
</dependency>

<dependency>
    <groupId>com.fasterxml.jackson.module</groupId>
    <artifactId>jackson-module-parameter-names</artifactId>
    <version>2.17.2</version>
<dependency>

2.2. Java Classes

Throughout the tutorial, we’ll use the Ticket class:

public class Ticket {
    @JsonProperty("event")
    private String eventName;

    private String guest;

    private final Currency currency;

    private final int price;

    public Ticket() {
        this.price = 0;
        this.currency = Currency.EUR;
    }

    public void setGuest(String guest) {
        this.guest = guest;
    }
    
    // getters for all attributes
}

Note that we defined a setter method only for the guest attributes, while providing getters for all attributes. Here, we intentionally omit the setters for the three other attributes to demonstrate the behavior of the deserialization. Also, we use @JsonProperty on the eventName attribute to demonstrate the different ways Jackson offers to serialize a field.

Here’s the currency enum:

public enum Currency {
    EUR("Euro", "cent"),
    GBP("Pound sterling", "penny"),
    CHF("Swiss franc", "Rappen");

    private String fullName;
    private String fractionalUnit;

    Currency(String fullName, String fractionalUnit) {
        this.fullName = fullName;
        this.fractionalUnit = fractionalUnit;
    }
}

2.3. JSON To Deserialize

Here’s the JSON that we want to deserialize in the examples:

{
  "event": "Devoxx",
  "guest": "Maria Monroe",
  "currency": "EUR",
  "price": 50
}

3. Default Deserialization

We need to define a default, no-argument constructor because the class has a final attribute. If we only define a constructor that takes the currency and price as arguments, Jackson won’t be able to deserialize the object:

public Ticket(Currency currency, int price) {
    this.price = price;
    this.currency = currency;
}

Jackson will throw an exception:

com.fasterxml.jackson.databind.exc.MismatchedInputException: 
  Cannot construct instance of `com.baeldung.jackson.multiparameterconstructor.Ticket` 
  (no Creators, like default constructor, exist): cannot deserialize from Object value

4. Deserialization Using @JsonCreator

To indicate which constructor should be used for deserialization, we can use the @JsonCreator annotation.

4.1. Defining a Constructor With @JsonCreator and @JsonProperty

If we want to use the two-argument constructor, we need to annotate it with @JsonCreator and annotate the parameters with @JsonProperty:

@JsonCreator
public Ticket(@JsonProperty("currency") Currency currency, @JsonProperty("price") int price) {
    this.price = price;
    this.currency = currency;
}

Jackson will deserialize the JSON as follows:

• The two attributes, currency and price, are set in the constructor.
• The guest attribute is set using its setter method.
• The eventName attribute doesn’t have a setter method and is set using reflection.

If there is no setter method for an attribute, Jackson sets the attribute using reflection based on its name. If the Java attribute name differs from the JSON field name, we can use the @JsonProperty annotation to define the JSON field name. In our example, we annotate the eventName attribute with @JsonProperty(“event”) to indicate that the JSON field name is event, while the Java attribute name is eventName.

We can annotate only one constructor with @JsonCreator. If we annotate a second constructor in addition to the one we have already defined:

@JsonCreator
public Ticket(@JsonProperty("currency") Currency currency, @JsonProperty("price") int price, @JsonProperty("guest") String guest) {
    this.price = price;
    this.currency = currency;
    this.guest = guest;
}

Jackson will throw an exception:

com.fasterxml.jackson.databind.JsonMappingException: 
  com.fasterxml.jackson.databind.exc.InvalidDefinitionException: 
    Conflicting property-based creators: 
    already had explicitly marked creator [constructor for `com.baeldung.jackson.multiparameterconstructor.Ticket` (2 args), 
    annotations: {interface com.fasterxml.jackson.annotation.JsonCreator=@com.fasterxml.jackson.annotation.JsonCreator(mode=DEFAULT)}, 
    encountered another: [constructor for `com.baeldung.jackson.multiparameterconstructor.Ticket` (3 args), 
    annotations: {interface com.fasterxml.jackson.annotation.JsonCreator=@com.fasterxml.jackson.annotation.JsonCreator(mode=DEFAULT)}

4.2. Constructor Without @JsonProperty

Jackson uses reflection to map JSON field names to Java class attributes. This works for class attributes but doesn’t work for method parameter names. Therefore, if we define a constructor without @JsonProperty annotations:

@JsonCreator
public Ticket(Currency currency, int price, String guest) {
    this.price = price;
    this.currency = currency;
    this.guest = guest;
}

We get an exception:

com.fasterxml.jackson.databind.exc.InvalidDefinitionException: 
  Invalid type definition for type `com.baeldung.jackson.multiparameterconstructor.Ticket`: 
  Argument #0 of constructor [constructor for `com.baeldung.jackson.multiparameterconstructor.Ticket` (2 args), 
  annotations: {interface com.fasterxml.jackson.annotation.JsonCreator=@com.fasterxml.jackson.annotation.JsonCreator(mode=DEFAULT)} 
  has no property name (and is not Injectable): can not use as property-based Creator

Java does not retain method parameter names at runtime, so we need to annotate the parameters with @JsonProperty to specify the JSON field name that should be mapped to each parameter.

If we want to avoid annotating the parameters with @JsonProperty, we can register the ParameterNamesModule and add the parameters flag to the compiler.

First, we need to add the Maven dependency:

<dependency>
    <groupId>com.fasterxml.jackson.module</groupId>
    <artifactId>jackson-module-parameter-names</artifactId>
    <version>2.21.1</version>
</dependency>

Then, we need to register the ParameterNamesModule with the object mapper:

ObjectMapper mapper = JsonMapper.builder()
  .constructorDetector(ConstructorDetector.USE_PROPERTIES_BASED)
  .addModule(new ParameterNamesModule(JsonCreator.Mode.PROPERTIES))
  .build();

And add the parameters flag to the compiler:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <compilerArgs>
            <arg>-parameters</arg>
        </compilerArgs>
    </configuration>
</plugin>

4.3. Configuration With ConstructorDetector

We still need to add the @JsonCreator annotation to mark the constructor that we want to use for deserialization.

As of Jackson 2.12, we can register a ConstructorDetector to specify the constructor that should be used for deserialization without the need to annotate it with @JsonCreator:

ObjectMapper mapper = JsonMapper.builder()
  .constructorDetector(ConstructorDetector.USE_PROPERTIES_BASED)
  .addModule(new ParameterNamesModule(JsonCreator.Mode.PROPERTIES))
  .constructorDetector(ConstructorDetector.USE_PROPERTIES_BASED)
  .build();

Notably,  if we configure Jackson to detect the constructor and also annotate one of multiple constructors with @JsonCreator, then the annotated constructor has preference over a constructor that would be detected otherwise.

5. Records

Jackson can deserialize records using the canonical constructor, which is present by default. Let’s consider the following record:

public record Guest(@JsonProperty("firstname") String firstname, @JsonProperty("surname") String surname) {}

And the following JSON:

{
  "firstname": "Maria",
  "surname": "Monroe"
}

Jackson can deserialize JSON to Java records without the need for a no-argument constructor. If we register the ParameterNamesModule and compile with the parameters flag, we don’t need to annotate the record components with @JsonProperty:

public record Guest(String firstname, String surname) {}

In some cases, we might want to customize the canonical constructor:

public Guest(String firstname, String surname) {
    this.firstname = firstname;
    this.surname = surname;
    // some validation
}

Again, we don’t need to annotate the constructor with @JsonCreator because Jackson will use the canonical constructor by default.

One case where we do need the @JsonCreator annotation is when we want to add a static factory method:

@JsonCreator
public static Guest fromJson(String firstname, String surname) {
    // some validation
    return new Guest(firstname, surname);
}

A difference to using a constructor is that a static factory method can have additional arguments:

@JsonCreator
public static Guest fromJson(String firstname, String surname, int id) {
    // some validation
    return new Guest(firstname, surname);
}

Whereas a non-canonical constructor won’t be used even if it’s annotated with @JsonCreator:

@JsonCreator
public Guest(String firstname, String surname, int id) {
    this(firstname, surname)
    // some validation
}

Jackson will ignore this constructor and use the canonical constructor instead.

6. Enums

@JsonCreator can also be used to deserialize enums. By default, Jackson deserializes enums using their name.

We can change the default behavior by annotating the enum with @JsonFormat:

@JsonFormat(shape = JsonFormat.Shape.OBJECT)
public enum Currency {
    EUR("Euro", "cent"),
    GBP("Pound sterling", "penny"),
    CHF("Swiss franc", "Rappen");

    private String fullName;
    private String fractionalUnit;

    Currency(String fullName, String fractionalUnit) {
        this.fullName = fullName;
        this.fractionalUnit = fractionalUnit;
    }
    
    // getters for all attributes
}

The enum value EUR will then be serialized to the following JSON:

{
  "fullName": "Euro",
  "fractionalUnit": "cent"
}

However, the deserialization will fail with the following exception:

com.fasterxml.jackson.databind.exc.MismatchedInputException: 
  Cannot deserialize value of type `com.baeldung.jackson.multiparameterconstructor.Currency` 
  from Object value (token `JsonToken.START_OBJECT`)

That’s because Jackson attempts to deserialize the enum based on its name: EUR. We might think that annotating the constructor with @JsonCreator would solve the problem:

@JsonCreator
Currency(String fullName, String fractionalUnit) {
    this.fullName = fullName;
    this.fractionalUnit = fractionalUnit;
}

That doesn’t work because enum constructors are private and cannot be used by Jackson. The solution is to define a
static factory method and annotate it with @JsonCreator:

@JsonCreator
public static Currency fromJsonString(String fullName, String fractionalUnit) {
    for (Currency c : Currency.values()) {
        if (c.fullName.equalsIgnoreCase(fullName) && c.fractionalUnit.equalsIgnoreCase(fractionalUnit)) {
            return c;
        }
    }
    throw new IllegalArgumentException("Unknown currency: " + fullName + " " + franctionalUnit);
}

7. Conclusion

In this article, we’ve learned how to deserialize JSON into a Java object using multi-parameter constructors. We’ve seen how to use the @JsonCreator in Java classes, enums, and records. In addition, we’ve learnt that the parameter names module and the constructor detector setting help reduce the number of necessary annotations.

As usual, the code in this article is available over on GitHub.