Serialization Utilities

/**
 * BinaryData is a convenient data interchange class for use throughout the Azure SDK for Java.
 */
class BinaryData {
    /**
     * Creates an instance of BinaryData from the given InputStream.
     * @param inputStream InputStream that BinaryData will represent
     * @return BinaryData representing the InputStream
     */
    public static BinaryData fromStream(InputStream inputStream);
    
    /**
     * Creates an instance of BinaryData from the given InputStream.
     * @param inputStream InputStream that BinaryData will represent
     * @param length The length of the InputStream in bytes
     * @return BinaryData representing the InputStream
     */
    public static BinaryData fromStream(InputStream inputStream, Long length);
    
    /**
     * Creates an instance of BinaryData from the given Flux of ByteBuffer.
     * @param data Flux of ByteBuffer that BinaryData will represent
     * @return BinaryData representing the Flux of ByteBuffer
     */
    public static BinaryData fromFlux(Flux<ByteBuffer> data);
    
    /**
     * Creates an instance of BinaryData from the given Flux of ByteBuffer.
     * @param data Flux of ByteBuffer that BinaryData will represent
     * @param length The length of the data in bytes
     * @param bufferAggregation Whether to aggregate the Flux into a single buffer
     * @return BinaryData representing the Flux of ByteBuffer
     */
    public static BinaryData fromFlux(Flux<ByteBuffer> data, Long length, boolean bufferAggregation);
    
    /**
     * Creates an instance of BinaryData from the given byte array.
     * @param data byte array that BinaryData will represent
     * @return BinaryData representing the byte array
     */
    public static BinaryData fromBytes(byte[] data);
    
    /**
     * Creates an instance of BinaryData from the given String.
     * @param data String that BinaryData will represent
     * @return BinaryData representing the String
     */
    public static BinaryData fromString(String data);
    
    /**
     * Creates an instance of BinaryData by serializing the given Object using default JsonSerializer.
     * @param data Object that BinaryData will represent
     * @return BinaryData representing the serialized Object
     */
    public static BinaryData fromObject(Object data);
    
    /**
     * Creates an instance of BinaryData by serializing the given Object using provided JsonSerializer.
     * @param data Object that BinaryData will represent
     * @param serializer JsonSerializer to use for serialization
     * @return BinaryData representing the serialized Object
     */
    public static BinaryData fromObject(Object data, ObjectSerializer serializer);
    
    /**
     * Creates an instance of BinaryData from the given file.
     * @param file Path to the file that BinaryData will represent
     * @return BinaryData representing the file content
     */
    public static BinaryData fromFile(Path file);
    
    /**
     * Creates an instance of BinaryData from the given file.
     * @param file Path to the file that BinaryData will represent
     * @param chunkSize Size of each chunk to read from the file
     * @return BinaryData representing the file content
     */
    public static BinaryData fromFile(Path file, int chunkSize);
    
    /**
     * Returns the content of this BinaryData instance as a byte array.
     * @return byte array representation of this BinaryData
     */
    public byte[] toBytes();
    
    /**
     * Returns the content of this BinaryData as a String.
     * @return String representation of this BinaryData
     */
    @Override
    public String toString();
    
    /**
     * Returns the content of this BinaryData as a String using the provided charset.
     * @param charset Charset to use for decoding
     * @return String representation using the specified charset
     */
    public String toString(Charset charset);
    
    /**
     * Returns the content of this BinaryData as an Object of the given type.
     * @param <T> Type of the Object
     * @param clazz Class representing the Object's type
     * @return Object representation of this BinaryData
     */
    public <T> T toObject(Class<T> clazz);
    
    /**
     * Returns the content of this BinaryData as an Object of the given type.
     * @param <T> Type of the Object
     * @param typeReference TypeReference representing the Object's type
     * @return Object representation of this BinaryData
     */
    public <T> T toObject(TypeReference<T> typeReference);
    
    /**
     * Returns the content of this BinaryData as an Object of the given type using the provided ObjectSerializer.
     * @param <T> Type of the Object
     * @param clazz Class representing the Object's type  
     * @param serializer ObjectSerializer to use for deserialization
     * @return Object representation of this BinaryData
     */
    public <T> T toObject(Class<T> clazz, ObjectSerializer serializer);
    
    /**
     * Returns the content of this BinaryData as an Object of the given type using the provided ObjectSerializer.
     * @param <T> Type of the Object
     * @param typeReference TypeReference representing the Object's type
     * @param serializer ObjectSerializer to use for deserialization
     * @return Object representation of this BinaryData
     */
    public <T> T toObject(TypeReference<T> typeReference, ObjectSerializer serializer);
    
    /**
     * Returns the content of this BinaryData as an InputStream.
     * @return InputStream representation of this BinaryData
     */
    public InputStream toStream();
    
    /**
     * Returns the content of this BinaryData as a Flux of ByteBuffer.
     * @return Flux of ByteBuffer representation of this BinaryData
     */
    public Flux<ByteBuffer> toFluxByteBuffer();
    
    /**
     * Returns the content of this BinaryData as a ReplayableStream.
     * @return ReplayableStream representation of this BinaryData
     */
    public ReplayableStream toReplayableStream();
    
    /**
     * Writes the contents of this BinaryData to the given OutputStream.
     * @param outputStream OutputStream to write to
     */
    public void writeTo(OutputStream outputStream);
    
    /**
     * Writes the contents of this BinaryData to the given WritableByteChannel.
     * @param channel WritableByteChannel to write to
     * @return Number of bytes written
     */
    public long writeTo(WritableByteChannel channel);
    
    /**
     * Returns the length of the content.
     * @return Length of the content, or null if unknown
     */
    public Long getLength();
    
    /**
     * Checks if the content can be replayed.
     * @return true if content can be replayed, false otherwise
     */
    public boolean isReplayable();
}

/**
 * Generic interface covering basic JSON serialization and deserialization methods.
 */
interface JsonSerializer {
    /**
     * Reads a JSON stream into its object representation.
     * @param <T> Type of the object
     * @param stream JSON stream
     * @param type Type to deserialize into
     * @return Object representation of the JSON
     */
    <T> T deserialize(InputStream stream, Type type);
    
    /**
     * Reads a JSON byte array into its object representation.
     * @param <T> Type of the object
     * @param bytes JSON byte array
     * @param type Type to deserialize into
     * @return Object representation of the JSON
     */
    <T> T deserialize(byte[] bytes, Type type);
    
    /**
     * Reads a JSON string into its object representation.
     * @param <T> Type of the object
     * @param json JSON string
     * @param type Type to deserialize into
     * @return Object representation of the JSON
     */
    <T> T deserialize(String json, Type type);
    
    /**
     * Reads a JSON stream into its object representation.
     * @param <T> Type of the object
     * @param stream JSON stream
     * @param type Type to deserialize into
     * @return Mono containing object representation of the JSON
     */
    <T> Mono<T> deserializeAsync(InputStream stream, Type type);
    
    /**
     * Converts the object into a JSON string.
     * @param value Object to serialize
     * @return JSON string representation
     */
    String serialize(Object value);
    
    /**
     * Converts the object into a JSON byte array.
     * @param value Object to serialize
     * @return JSON byte array representation
     */
    byte[] serializeToBytes(Object value);
    
    /**
     * Writes the object to the provided OutputStream as JSON.
     * @param stream OutputStream to write to
     * @param value Object to serialize
     */
    void serialize(OutputStream stream, Object value);
    
    /**
     * Writes the object to the provided OutputStream as JSON asynchronously.
     * @param stream OutputStream to write to
     * @param value Object to serialize
     * @return Mono representing the operation
     */
    Mono<Void> serializeAsync(OutputStream stream, Object value);
}

/**
 * Generic interface covering basic serialization and deserialization methods.
 */
interface ObjectSerializer {
    /**
     * Reads an object representation from a stream.
     * @param <T> Type of the object
     * @param stream Stream to read from
     * @param type Type to deserialize into
     * @return Object representation
     */
    <T> T deserialize(InputStream stream, Type type);
    
    /**
     * Reads an object representation from a byte array.
     * @param <T> Type of the object
     * @param bytes Byte array to read from
     * @param type Type to deserialize into
     * @return Object representation
     */
    <T> T deserialize(byte[] bytes, Type type);
    
    /**
     * Reads an object representation from a string.
     * @param <T> Type of the object
     * @param data String to read from
     * @param type Type to deserialize into
     * @return Object representation
     */
    <T> T deserialize(String data, Type type);
    
    /**
     * Reads an object representation from a stream asynchronously.
     * @param <T> Type of the object
     * @param stream Stream to read from
     * @param type Type to deserialize into
     * @return Mono containing object representation
     */
    <T> Mono<T> deserializeAsync(InputStream stream, Type type);
    
    /**
     * Writes an object to a stream.
     * @param stream Stream to write to
     * @param value Object to serialize
     */
    void serialize(OutputStream stream, Object value);
    
    /**
     * Converts an object to a string.
     * @param value Object to serialize
     * @return String representation
     */
    String serialize(Object value);
    
    /**
     * Converts an object to a byte array.
     * @param value Object to serialize
     * @return Byte array representation
     */
    byte[] serializeToBytes(Object value);
    
    /**
     * Writes an object to a stream asynchronously.
     * @param stream Stream to write to
     * @param value Object to serialize
     * @return Mono representing the operation
     */
    Mono<Void> serializeAsync(OutputStream stream, Object value);
}

/**
 * An interface defining the behaviors of a serializer.
 */
interface SerializerAdapter {
    /**
     * Serializes an object into a string.
     * @param object The object to serialize
     * @param encoding The encoding to use for serialization
     * @return The serialized string
     */
    String serialize(Object object, SerializerEncoding encoding);
    
    /**
     * Serializes an object into a raw string without encoding information.
     * @param object The object to serialize
     * @return The serialized string
     */
    String serializeRaw(Object object);
    
    /**
     * Serializes an object into a list of objects.
     * @param object The object to serialize
     * @param encoding The encoding to use for serialization
     * @return The serialized list
     */
    String serializeList(Object object, CollectionFormat format);
    
    /**
     * Deserializes a string into a specified type.
     * @param <U> The type to deserialize into
     * @param value The string to deserialize
     * @param type The type to deserialize into
     * @param encoding The encoding used for deserialization
     * @return The deserialized object
     */
    <U> U deserialize(String value, Type type, SerializerEncoding encoding);
    
    /**
     * Deserializes an HttpResponse into a specified type.
     * @param <U> The type to deserialize into
     * @param httpResponse The HTTP response to deserialize
     * @param type The type to deserialize into
     * @return The deserialized object
     */
    <U> U deserialize(HttpResponse httpResponse, Type type);
    
    /**
     * Deserializes an HttpResponse into a specified type with additional headers.
     * @param <U> The type to deserialize into
     * @param httpResponse The HTTP response to deserialize
     * @param type The type to deserialize into
     * @param headerType The type for response headers
     * @return The deserialized object with headers
     */
    <U> U deserialize(HttpResponse httpResponse, Type type, Type headerType);
}

/**
 * Supported serialization encoding formats.
 */
enum SerializerEncoding {
    /**
     * JavaScript Object Notation (JSON) format.
     */
    JSON,
    
    /**
     * eXtensible Markup Language (XML) format.
     */
    XML;
    
    /**
     * Creates a SerializerEncoding from a string value.
     * @param value String representation
     * @return Corresponding SerializerEncoding
     */
    public static SerializerEncoding fromString(String value);
}

/**
 * Service Provider Interface (SPI) for JsonSerializer.
 */
interface JsonSerializerProvider {
    /**
     * Creates a JsonSerializer instance.
     * @return JsonSerializer instance
     */
    JsonSerializer createInstance();
}

/**
 * This class represents a reference to a generic type.
 */
abstract class TypeReference<T> {
    /**
     * Protected constructor for TypeReference.
     */
    protected TypeReference();
    
    /**
     * Gets the generic type represented by this TypeReference.
     * @return Type represented by this reference
     */
    public Type getJavaType();
}

/**
 * A stream that can be replayed (reset and read again).
 */
interface ReplayableStream {
    /**
     * Gets the content of this ReplayableStream as an InputStream.
     * @return InputStream representing the stream content
     */
    InputStream toStream();
    
    /**
     * Gets the content of this ReplayableStream as a Flux of ByteBuffer.
     * @return Flux of ByteBuffer representing the stream content
     */
    Flux<ByteBuffer> toFluxByteBuffer();
    
    /**
     * Gets the length of the content in bytes.
     * @return Length in bytes, or null if unknown
     */
    Long getLength();
    
    /**
     * Resets the stream to the beginning.
     */
    void reset();
    
    /**
     * Marks the current position in the stream.
     * @param readLimit Maximum bytes that can be read before mark becomes invalid
     */
    void mark(int readLimit);
    
    /**
     * Checks if this stream supports mark and reset operations.
     * @return true if mark/reset is supported
     */
    boolean markSupported();
}

import com.azure.core.util.BinaryData;
import com.azure.core.util.serializer.TypeReference;
import java.io.InputStream;
import java.util.List;
import java.util.Map;

// Create BinaryData from different sources
BinaryData fromString = BinaryData.fromString("{\"name\":\"John\",\"age\":30}");
BinaryData fromBytes = BinaryData.fromBytes("Hello World".getBytes());

// Create from file
Path filePath = Paths.get("data.json");
BinaryData fromFile = BinaryData.fromFile(filePath);

// Create from InputStream
InputStream inputStream = // ... get input stream
BinaryData fromStream = BinaryData.fromStream(inputStream);

// Serialize objects to BinaryData
User user = new User("Alice", "alice@example.com");
BinaryData fromObject = BinaryData.fromObject(user);

// Convert BinaryData to different formats
String jsonString = fromObject.toString();
byte[] jsonBytes = fromObject.toBytes();
InputStream stream = fromObject.toStream();

// Deserialize to objects
User deserializedUser = fromObject.toObject(User.class);

// Handle generic types
List<String> stringList = List.of("item1", "item2", "item3");
BinaryData listData = BinaryData.fromObject(stringList);
List<String> deserializedList = listData.toObject(new TypeReference<List<String>>() {});

// Work with Maps
Map<String, Object> dataMap = Map.of("key1", "value1", "key2", 42);
BinaryData mapData = BinaryData.fromObject(dataMap);
Map<String, Object> deserializedMap = mapData.toObject(new TypeReference<Map<String, Object>>() {});

import com.azure.core.util.serializer.*;

// Using custom JsonSerializer
JsonSerializer customSerializer = // ... get custom serializer
User user = new User("Bob", "bob@example.com");

// Serialize with custom serializer
BinaryData customSerialized = BinaryData.fromObject(user, customSerializer);

// Deserialize with custom serializer  
User deserializedUser = customSerialized.toObject(User.class, customSerializer);

// Working with different content types
BinaryData xmlData = BinaryData.fromString("<user><name>Charlie</name></user>");
// Note: XML deserialization would require appropriate ObjectSerializer

import com.azure.core.util.BinaryData;
import reactor.core.publisher.Flux;
import java.nio.ByteBuffer;

// Create from Flux
Flux<ByteBuffer> dataFlux = // ... create flux of byte buffers
BinaryData fromFlux = BinaryData.fromFlux(dataFlux);

// Convert to Flux
Flux<ByteBuffer> backToFlux = fromFlux.toFluxByteBuffer();

// Write to OutputStream
ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
fromFlux.writeTo(outputStream);
byte[] written = outputStream.toByteArray();

// Check properties
Long length = fromFlux.getLength();
boolean isReplayable = fromFlux.isReplayable();

System.out.println("Data length: " + length);
System.out.println("Is replayable: " + isReplayable);

import com.azure.core.util.serializer.TypeReference;
import java.util.List;
import java.util.Map;

// Complex generic types
class ApiResponse<T> {
    private T data;
    private String status;
    private Map<String, String> metadata;
    
    // ... getters and setters
}

// Deserialize complex generic types
String jsonResponse = "{\"data\":[{\"id\":1,\"name\":\"Item1\"}],\"status\":\"success\"}";
BinaryData responseData = BinaryData.fromString(jsonResponse);

// Use TypeReference for complex generics
ApiResponse<List<Item>> response = responseData.toObject(
    new TypeReference<ApiResponse<List<Item>>>() {}
);

// Work with nested generics
Map<String, List<User>> userGroups = responseData.toObject(
    new TypeReference<Map<String, List<User>>>() {}
);

import com.azure.core.util.BinaryData;
import java.nio.channels.WritableByteChannel;
import java.nio.file.Files;
import java.nio.file.StandardOpenOption;

// Handle large files efficiently
Path largeFile = Paths.get("large-file.dat");
BinaryData largeFileData = BinaryData.fromFile(largeFile, 8192); // 8KB chunks

// Stream to another location
Path destination = Paths.get("copied-file.dat");
try (WritableByteChannel channel = Files.newByteChannel(destination, 
         StandardOpenOption.CREATE, StandardOpenOption.WRITE)) {
    long bytesWritten = largeFileData.writeTo(channel);
    System.out.println("Copied " + bytesWritten + " bytes");
}

// Check if content can be replayed
if (largeFileData.isReplayable()) {
    // Safe to read multiple times
    byte[] firstRead = largeFileData.toBytes();
    byte[] secondRead = largeFileData.toBytes(); // Will work for replayable content
}