A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://github.com/Azure/azure-sdk-for-java/wiki/Serialization below:

Serialization · Azure/azure-sdk-for-java Wiki · GitHub

Customizable serialization

Azure Core offers the ObjectSerializer and JsonSerializer interfaces as a standard way to handle serialization and deserialization of specific serialization formats. There is a default implementation of these interfaces built into Azure Core, but users and Azure SDKs can specify their own through service provider interface (SPI). The SPI allows for the serialization layer to be plug-able and removes dependencies on given implementations. Here are the Azure Core models that support serializer customization

If you're a user looking to provide your serializer implementation, please refer to Custom JSON serializer.

If you're Azure Core developer and want to support customer serializers, use ObjectSerializer abstraction and resolve instance with JsonSerializerProviders.createInstance (or AvroSerializerProviders)

  1. com.azure.core.util.serializer.ObjectSerializer - Generic interface for (de)serializing objects. Abstracts format-specific serializers.
  2. com.azure.core.util.serializer.JsonSerializer - Generic interface covering basic JSON (de)serialization methods.
  3. com.azure.core.util.serializer.JsonSerializerProvider - extension point - resolves JsonSerializer implementation in runtime.
  1. Package azure-core-serializer-json-jackson: com.azure.core.serializer.json.jackson.JacksonJsonSerializer - JsonSerializer implementation of the JsonSerializer defaulting to Azure Core internal implementation.
  2. Package azure-core-serializer-json-gson: com.azure.core.serializer.json.gson.GsonJsonSerializer - JsonSerializer based on Gson. Intended for consumers.
  3. Package azure-core-serializer-avro-apache - includes experimental com.azure.core.serializer.avro.apache.ApacheAvroSerializer - AvroSerializer based on apache apache (de)serializer. Intended for consumers.

All of them come with a builder and provider.

If you're a library developer and want users to be able to provide their own serializer - take a dependency on one of the implementation packages. We recommend using azure-core-serializer-json-jackson for Json and azure-core-serializer-avro-apache for Avro.

If you don't want users to be able to replace serializers and can't use the default one, you can create your implementation and instantiate it directly without calling into JsonSerializerProviders.createInstance.

Please refer to the reference docs for more details.

Supporting user-provided serializer instance 
public final class User {
    private static final JsonSerializer SERIALIZER = JsonSerializerProviders.createInstance(true);

    public User() {}

    @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);
    }
}
Using JacksonJsonSerializerBuilder

If you don't need to support customizable serializers for the model, but want to configure some settings on the serializer, please use JacksonJsonSerializerBuilder from azure-core-serializer-json-jackson. A similar approach can be used with ApacheAvroSerializerBuilder or GsonJsonSerializerBuilder.

public final class User {

    private static final JsonSerializer SERIALIZER = new JacksonJsonSerializerBuilder()
            .serializer(new ObjectMapper().registerModule(
                    new SimpleModule().addSerializer(User.class, new UserSerializer())
                            .addDeserializer(User.class, new UserDeserializer())))
            .build();
    
    public User() {}

    @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);
    }
}

If you're an Azure Core or Azure SDK developer and don't want customers to provide their own serializer, use SerializerAdapter abstraction and JacksonAdapter implementation.

  1. com.azure.core.util.serializer.SerializerAdapter - interface for all serialization (Json and XML).
  2. com.azure.core.util.serializer.JacksonAdapter - implements SerializerAdapter - default (de)serialization (json and XML) implementation.
Default configuration settings

Here is the default configuration applied on json/xml serialization in Azure Core.

Applies to:

Configuration does not apply to GsonJsonSerializer, JacksonAvroSerializer or ApacheAvroSerializer - they use corresponding underlying package (jackson, gson, apache avro) defaults unless customized.

Note: Jackson behavior regarding null/empty (de)serialization edge cases depends on version and subject to change (especially in xml). Please support variety of cases and avoid depending on specific behavior.

JacksonJsonSerializer uses Jackson defaults (unless customized).

Annotated properties/fields are always serialized regardless of visibility. For auto-detected fields/properties/etc JacksonAdapter and JacksonJsonSerializer have different settings. JacksonJsonSerializer uses jackson defaults (unless customized).

Json-specific. Not supported in XML.

additionalProperties is a magic word that allows to serialize map with String keys as top-level properties.

Please use @JsonAnyGetter/@JsonAnySetter instead (if you can) for performance reasons.

additionalProperties vs @JsonAnyGetter/@JsonAnySetter

additionalProperties are Azure SDK concept, @JsonAnyGetter/@JsonAnySetter is jackson annotations. Please use @JsonAnyGetter/@JsonAnySetter when possible. Usage of additionalProperties adds extra performance overhead (~10x) and is not recommended in perf-sensitive scenarios.

Flattening is Azure SDK concept that allows to write more compact models.

Class-level flattening example 
@JsonFlatten
class Model {
  @JsonProperty("property.name")
  private String name = "foo";

  @JsonProperty("property.value")
  private String value = "bar";

  @JsonProperty("property\\.escaped")
  private String escaped = "baz";
}

translates into

{
  "property" : {
    "name" : "foo",
    "value" : "bar"
  },
  "property.escaped" : "baz" 
}
Field-level flattening example 
class Model {
  @JsonFlatten
  @JsonProperty("property.name")
  private String name = "foo"; 

  @JsonFlatten
  @JsonProperty("property.value")
  private String value = "bar";

  @JsonProperty("property.not.escaped")
  private String notEscaped = "baz";
}

translates into

{
  "property" : {
    "name" : "foo",
    "value" : "bar"
  },
  "property.not.escaped" : "baz" 
}
Dates, times and duration

Any few more with the same (de)serialization behavior as ZonedDateTime:

com.azure.core.util.Base64Url com.azure.core.http.HttpHeaders

Serialized as Map<String, String>. If a header has multiple values, they are joined in a comma-separated string. Using headers along with additionalProperties (or @JsonAnyGetter/@JsonAnySetter) is not supported.

Serializable models included in azure-core

Following models are (de)serialized using serializer provided with JsonSerializerProvider, defaulting to JacksonAdapter which no custom serializer is provided:

Consumers and Azure SDKs are encouraged to bring their own serializers to customize serialization for these models.

GeoObject and its friends are pure models and don't handle their own (de)serialization. DynamicRequest accepts any ObjectSerializer implementation in constructor to serialize request body.

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4