opened
alzimmermsft
username_0
Related to #1578

## The Basics

We're looking to add the interfaces `ObjectSerializer` and `JsonSerializer` into Azure Core. In addition two implementation libraries backed by Jackson and GSON.

* Service team: The ADP Java folks
* ApiView: https://apiview.dev/Assemblies/Review/9264dc900f4e45b186d9a698a63957f3
* Contact: @username_0 and @JonathanGiles 

## Champion Scenarios

We're looking to allow customers to use their own serializers when interacting with services that handle customer types such as Cosmos and Search documents and EventHubs and Service Bus messages. This will unblock scenarios where customer must use their own serializer for their own custom types. [ObjectSerializer
](https://apiview.dev/Assemblies/Review/9264dc900f4e45b186d9a698a63957f3#com.azure.core.experimental.serializer.ObjectSerializer) is the base abstraction which will be capable of spanning multiple serialization formats. [JsonSerializer](https://apiview.dev/Assemblies/Review/9264dc900f4e45b186d9a698a63957f3#com.azure.core.experimental.serializer.JsonSerializer) is a sub interface to `ObjectSerializer` containing operations more specific to JSON such as converting Objects or JSON into a tree representation.

As a customer during configuration of your service client you will configure on of the interfaces mentioned above. When APIs in the client that take a `Class<T>` parameter your configured serializer will be invoked to handle serialization/deserialization.

As an SDK developer you'll add new builder API which accepts either `ObjectSerializer` or `JsonSerializer` based on your requirements. If your SDK is tied strongly to JSON you'll want to target `JsonSerializer`, for example Search only works with JSON data. If your SDK is more flexible in what data can be passed you'll want to target `ObjectSerializer`, for example EventHubs queues are format agnostic. For customer types APIs you'll update logic to use the customer passed serializer, depending on if this functionality is being added post GA you'll default to using the current serializer implementation you are using.

## Samples

### Using clients with a custom model and default serializer

```java
public class MyModel {
    private String name;

    public String getName() {
        return name;
    }

    public MyModel setName(String name) {
        this.name = name;
        return this;
    }
}

SearchClient client = new SearchClientBuilder()
    .endpoint("<endpoint>")
    .index("<index>")
    .credential(new AzureKeyCredential("<key>"))
    .buildClient()

MyModel myDocument = client.getDocument("<documentKey>", MyModel.class);
```

### Using clients with a custom model with Jackson attributes and default serializer

```java
public class MyModel {
    @JsonProperty
    private String name;

    public String getName() {
        return name;
    }

    public MyModel setName(String name) {
        this.name = name;
        return this;
    }
}

SearchClient client = new SearchClientBuilder()
    .endpoint("<endpoint>")
    .index("<index>")
    .credential(new AzureKeyCredential("<key>"))
    .buildClient()

MyModel myDocument = client.getDocument("<documentKey>", MyModel.class);
```

### Using clients with a custom model with customized default serializer

```java
public class MyModel {
    private String name;

    public String getName() {
        return name;
    }

    public MyModel setName(String name) {
        this.name = name;
        return this;
    }
}

SearchClient client = new SearchClientBuilder()
    .endpoint("<endpoint>")
    .index("<index>")
    .credential(new AzureKeyCredential("<key>"))
    .serializer(new JacksonJsonSerializerBuilder().build())
    .buildClient()

MyModel myDocument = client.getDocument("<documentKey>", MyModel.class);
```

### Using clients with a custom model with GSON serializer

```java
public class MyModel {
    private String name;

    public String getName() {
        return name;
    }

    public MyModel setName(String name) {
        this.name = name;
        return this;
    }
}

SearchClient client = new SearchClientBuilder()
    .endpoint("<endpoint>")
    .index("<index>")
    .credential(new AzureKeyCredential("<key>"))
    .serializer(new GsonJsonSerializerBuilder().build())
    .buildClient()

MyModel myDocument = client.getDocument("<documentKey>", MyModel.class);
```
Board Review: ObjectSerializer and JsonSerializer for Java
issue
created
ramya-rao-a
username_1
@username_0 Am guessing this proposal has approval from @JonathanGiles just like how https://github.com/Azure/azure-sdk/issues/1578 has approval from @KrzysztofCwalina?

@bterlson, @johanste, @KrzysztofCwalina, 

We won't be having a separate meeting to review this API.
Assuming this is already approved by the Java architect @JonathanGiles, can the rest of you take a look and provide your approval if you have no concerns with the proposed design?

Please note that the ObjectSerializer is being shipped out of Azure.Core in less than 2 weeks.

@username_0 to confirm if JSONSerializer is being shipped in the same time as well
comment
created
ramya-rao-a
username_1
cc @annatisch, @tg-msft, @xirzec
comment
created
alzimmermsft
username_0
Yes, `JsonSerializer` will ship at the same time as `ObjectSerializer` for Java.
comment