Skip to content

Latest commit

 

History

History
165 lines (112 loc) · 5.19 KB

File metadata and controls

165 lines (112 loc) · 5.19 KB

Serialization

Azure Core provides two serialization abstractions:

Abstraction Purpose
SerializerAdapter / JacksonAdapter Default (JSON + XML) for SDK internals; not intended for replacement
JsonSerializer / ObjectSerializer Pluggable interface; users and SDKs can supply custom implementations

Customizable Serialization (JsonSerializer)

SPI Pattern

JsonSerializerProvider is a SPI loaded via ServiceLoader. Include one of the following on the classpath to override the default:

Package Implementation Default?
azure-core-serializer-json-jackson JacksonJsonSerializer Yes (wraps JacksonAdapter)
azure-core-serializer-json-gson GsonJsonSerializer No
azure-core-serializer-avro-apache ApacheAvroSerializer (experimental) No

Getting an Instance

// Use the SPI-discovered implementation; falls back to default if none found
JsonSerializer serializer = JsonSerializerProviders.createInstance(true);

// Disable fallback (throws if no provider on classpath)
JsonSerializer strictSerializer = JsonSerializerProviders.createInstance(false);

Example: Supporting a User-Provided Serializer

public final class User {
    private static final JsonSerializer SERIALIZER = JsonSerializerProviders.createInstance(true);

    @JsonProperty public String firstName;
    @JsonProperty public String lastName;

    public static User fromString(String str) {
        return SERIALIZER.deserializeFromBytes(
            str.getBytes(StandardCharsets.UTF_8),
            TypeReference.createInstance(User.class));
    }

    public String toString() {
        return new String(SERIALIZER.serializeToBytes(this), StandardCharsets.UTF_8);
    }
}

Example: Using JacksonJsonSerializerBuilder (Customized Jackson)

JsonSerializer serializer = new JacksonJsonSerializerBuilder()
    .serializer(new ObjectMapper()
        .registerModule(new SimpleModule()
            .addSerializer(User.class, new UserSerializer())
            .addDeserializer(User.class, new UserDeserializer())))
    .build();

Default Serialization (JacksonAdapter)

Used internally by SDK implementation code (not swappable by users):

// Singleton (preferred for SDK internals)
SerializerAdapter adapter = JacksonAdapter.createDefaultSerializerAdapter();

// New instance (allows customization without affecting the singleton)
SerializerAdapter adapter = new JacksonAdapter();
// Optionally customize: adapter.serializer().configure(...)

⚠️ Do not modify configuration on the createDefaultSerializerAdapter() singleton — it is shared across the SDK.


Default Configuration Behavior

These defaults apply to both JacksonAdapter and JacksonJsonSerializer (unless customized).

Null / Empty Properties

Scenario JSON XML
Null field serialization JacksonAdapter: excluded; JacksonJsonSerializer: written as null Excluded
null deserialization As null As null
Empty string serialization "" <a></a>

Case Sensitivity

  • JSON: case-sensitive
  • XML: case-insensitive

Arrays / Collections

  • Null arrays: not serialized; deserialized as null
  • Empty arrays: serialized as [] (JSON) or self-closing tag <a/> (XML)
  • Byte arrays: base64-encoded strings

Dates and Times

Type Serialization format
OffsetDateTime UTC ISO-8601: "2021-07-06T20:09:01.465Z"
Duration ISO-8601 with days: "P1DT10H17M36.789S"
Instant Instant UTC ISO: "2021-07-06T19:47:12.728Z"
UnixTime Epoch seconds: 1625602953.0
DateTimeRfc1123 RFC-1123: "Tue, 06 Jul 2021 20:31:19 GMT"

@JsonFlatten

Allows writing nested JSON from flat model properties:

@JsonFlatten
class Model {
    @JsonProperty("property.name") private String name = "foo";    // → {"property": {"name": "foo"}}
    @JsonProperty("property\\.escaped") private String esc = "baz"; // → {"property.escaped": "baz"}
}

additionalProperties

Magic field name: a Map<String, Object> field named additionalProperties is serialized as top-level JSON properties. Prefer @JsonAnyGetter / @JsonAnySetter in performance-sensitive code (10× less overhead).

Error Tolerance

  • Unknown properties: ignored (no error)
  • Empty bean: serialized as {}
  • Exceptions: JacksonJsonSerializer logs and re-throws as UncheckedIOException; JacksonAdapter does not catch/log

Serializable Models in azure-core

These models use the pluggable JsonSerializerProvider:

  • CloudEvent
  • BinaryData
  • RequestContent
  • JsonPatchDocument

Custom serializers can be passed to these models via their constructors or builders.


Migration to azure-json

For new code and libraries migrating away from Jackson, see Azure JSON Migration.


See Also