Jackson databind

To support deserialization into objects that use the Builder pattern, follow these steps:

1. Annotate the target class with @JsonDeserialize(builder = YourBuilder.class).
2. Annotate the inner Builder class with @JsonPOJOBuilder.

If your builder uses a different method name than build() or a different prefix than the default, configure it via @JsonPOJOBuilder(buildMethodName = "...", withPrefix = "...").

To handle different JSON property names within the builder, use @JsonProperty on the builder's fields. If a property has multiple possible names in the JSON, use @JsonAlias (note: @JsonAlias requires a corresponding @JsonProperty to be present).

@JsonDeserialize(builder = Person.Builder.class)
public class Person {
    private final String name;
    private final Integer age;

    @JsonPOJOBuilder(buildMethodName = "create", withPrefix = "set")
    static class Builder {
        @JsonProperty("known_as")
        @JsonAlias({"identifier", "first_name"})
        String name;
        Integer age;

        Builder setName(String name) { this.name = name; return this; }
        Builder setAge(Integer age) { this.age = age; return this; }

        public Person create() { return new Person(name, age); }
    }
}

In Jackson 3.x, ObjectMapper instances are immutable and thread-safe, requiring the use of the JsonMapper.builder() pattern for configuration. You can enable or disable various features for serialization, deserialization, and low-level JSON parsing/generation.

Commonly used features include:

• SerializationFeature: Controls how JSON is written (e.g., INDENT_OUTPUT for pretty-printing).
• DeserializationFeature: Controls how JSON is read (e.g., FAIL_ON_UNKNOWN_PROPERTIES).
• JsonReadFeature / JsonWriteFeature: Low-level JSON-specific settings (e.g., allowing comments or single quotes).
• StreamReadFeature / StreamWriteFeature: Format-agnostic settings.

// SerializationFeature for changing how JSON is written
// to enable standard indentation ("pretty-printing"):
// to allow serialization of "empty" POJOs (no properties to serialize)
// to write java.util.Date, Calendar as number (timestamp):
// DeserializationFeature for changing how JSON is read as POJOs:
// to prevent exception when encountering unknown property:
// to allow coercion of JSON empty String ("") to null Object value:

ObjectMapper mapper = JsonMapper.builder()
    .enable(SerializationFeature.INDENT_OUTPUT)
    .disable(SerializationFeature.FAIL_ON_EMPTY_BEANS)
    .disable(DateTimeFeature.WRITE_DATES_AS_TIMESTAMPS)
    .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
    .enable(DeserializationFeature.ACCEPT_EMPTY_STRING_AS_NULL_OBJECT)

    // StreamReadFeatures for configuring parsing settings:
    // to allow C/C++ style comments in JSON (non-standard, disabled by default)
    // to allow (non-standard) unquoted field names in JSON:
    // to allow use of apostrophes (single quotes), non standard
    .configure(JsonReadFeature.ALLOW_JAVA_COMMENTS, true)
    .configure(JsonReadFeature.ALLOW_UNQUOTED_PROPERTY_NAMES, true)
    .configure(JsonReadFeature.ALLOW_SINGLE_QUOTES, true)

    // JsonWriteFeature for configuring low-level JSON generation:
    // to force escaping of non-ASCII characters:
    .configure(JsonWriteFeature.ESCAPE_NON_ASCII, true)
    
    .build();

Instead of failing on the first error, you can configure Jackson to collect multiple deserialization problems (such as type mismatches or unknown properties) into a single exception. This is useful for validation scenarios where you want to report all errors to a client at once.

Key Details:

• Method: Use ObjectReader.problemCollectingReader() to create a reader that collects errors.
• Execution: Call reader.readValueCollectingProblems(json) to perform the deserialization.
• Error Handling: Caught errors are thrown as a DeferredBindingException. You can iterate through ex.getProblems() to access CollectedProblem objects.
• Problem Details: Each CollectedProblem provides .getPath() (using JSON Pointer notation, RFC 6901), .getMessage(), and .getRawValue().
• Limits: By default, Jackson collects up to 100 problems to prevent DoS attacks. You can customize this limit using problemCollectingReader(int limit).
• Limitations: Structural/malformed JSON errors (e.g., missing braces) will still cause immediate failure. If errors are collected, the partial result is not returned; only the exception is thrown.

ObjectMapper mapper = new JsonMapper();
ObjectReader reader = mapper.readerFor(Order.class).problemCollectingReader();

try {
    Order result = reader.readValueCollectingProblems(json);
    // worked fine
} catch (DeferredBindingException ex) {
    System.out.println("Found " + ex.getProblems().size() + " problems:");
    for (CollectedProblem problem : ex.getProblems()) {
        System.out.println(problem.getPath() + ": " + problem.getMessage());
        // Can also access problem.getRawValue() to see what the bad input was
    }
}

Jackson can perform arbitrary POJO-to-POJO conversions by conceptually writing a POJO to JSON and then binding that JSON to a new type. This is more efficient than actual JSON generation as it uses an intermediate representation. This is useful for:

• Converting List<Integer> to int[].
• Converting a POJO to a Map<String, Object> and vice versa.
• Decoding Base64 strings into byte[].

ResultType result = mapper.convertValue(sourceObject, ResultType.class);

// Examples:
// Convert from List<Integer> to int[]
List<Integer> sourceList = ...;
int[] ints = mapper.convertValue(sourceList, int[].class);

// Convert a POJO into Map!
Map<String,Object> propertyMap = mapper.convertValue(pojoValue, Map.class);

// decode Base64!
String base64 = "TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ5IGhpcyByZWFzb24sIGJ1dCBieSB0aGlz";
byte[] binary = mapper.convertValue(base64, byte[].class);