Package com.azure.core.util

Class BinaryData

java.lang.Object
com.azure.core.util.BinaryData
public final class BinaryData extends Object
BinaryData is a convenient data interchange class for use throughout the Azure SDK for Java. Put simply, BinaryData enables developers to bring data in from external sources, and read it back from Azure services, in formats that appeal to them. This leaves BinaryData, and the Azure SDK for Java, the task of converting this data into appropriate formats to be transferred to and from these external services. This enables developers to focus on their business logic, and enables the Azure SDK for Java to optimize operations for best performance.

BinaryData in its simplest form can be thought of as a container for content. Often this content is already in-memory as a String, byte array, or an Object that can be serialized into a String or byte[]. When the BinaryData is about to be sent to an Azure Service, this in-memory content is copied into the network request and sent to the service.

In more performance critical scenarios, where copying data into memory results in increased memory pressure, it is possible to create a BinaryData instance from a stream of data. From this, BinaryData can be connected directly to the outgoing network connection so that the stream is read directly to the network, without needing to first be read into memory on the system. Similarly, it is possible to read a stream of data from a BinaryData returned from an Azure Service without it first being read into memory. In many situations, these streaming operations can drastically reduce the memory pressure in applications, and so it is encouraged that all developers very carefully consider their ability to use the most appropriate API in BinaryData whenever they encounter an client library that makes use of BinaryData.

Refer to the documentation of each method in the BinaryData class to better understand its performance characteristics, and refer to the samples below to understand the common usage scenarios of this class.

BinaryData can be created from an InputStream, a Flux of ByteBuffer, a String, an Object, a file, or a byte array.

A note on data mutability

BinaryData does not copy data on construction. BinaryData keeps a reference to the source content and is accessed when a read request is made. So, any modifications to the underlying source before the content is read can result in undefined behavior.

To create an instance of BinaryData, use the various static factory methods available. They all start with 'from' prefix, for example fromBytes(byte[]).

Create an instance from a byte array 

 final byte[] data = "Some Data".getBytes(StandardCharsets.UTF_8);
 BinaryData binaryData = BinaryData.fromBytes(data);
 System.out.println(new String(binaryData.toBytes(), StandardCharsets.UTF_8));

Create an instance from a String 

 final String data = "Some Data";
 // Following will use default character set as StandardCharsets.UTF_8
 BinaryData binaryData = BinaryData.fromString(data);
 System.out.println(binaryData.toString());

Create an instance from an InputStream 

 final ByteArrayInputStream inputStream = new ByteArrayInputStream("Some Data".getBytes(StandardCharsets.UTF_8));
 BinaryData binaryData = BinaryData.fromStream(inputStream);
 System.out.println(binaryData);

Create an instance from an Object 

 final Person data = new Person().setName("John");

 // Provide your custom serializer or use Azure provided serializers.
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-gson
 BinaryData binaryData = BinaryData.fromObject(data);

 System.out.println(binaryData);

Create an instance from Flux<ByteBuffer> 

 final byte[] data = "Some Data".getBytes(StandardCharsets.UTF_8);
 final Flux<ByteBuffer> dataFlux = Flux.just(ByteBuffer.wrap(data));

 Mono<BinaryData> binaryDataMono = BinaryData.fromFlux(dataFlux);

 Disposable subscriber = binaryDataMono
     .map(binaryData -> {
         System.out.println(binaryData.toString());
         return true;
     })
     .subscribe();

 // So that your program wait for above subscribe to complete.
 TimeUnit.SECONDS.sleep(5);
 subscriber.dispose();

Create an instance from a file 

 BinaryData binaryData = BinaryData.fromFile(new File("path/to/file").toPath());
 System.out.println(new String(binaryData.toBytes(), StandardCharsets.UTF_8));
See Also:

  • Method Details

    • fromStream

      public static BinaryData fromStream(InputStream inputStream)
      Creates an instance of BinaryData from the given InputStream. Depending on the type of inputStream, the BinaryData instance created may or may not allow reading the content more than once. The stream content is not cached if the stream is not read into a format that requires the content to be fully read into memory.

      NOTE: The InputStream is not closed by this function.

      Create an instance from an InputStream

       final ByteArrayInputStream inputStream = new ByteArrayInputStream("Some Data".getBytes(StandardCharsets.UTF_8));
 BinaryData binaryData = BinaryData.fromStream(inputStream);
 System.out.println(binaryData);
      Parameters:
      inputStream - The InputStream that BinaryData will represent.
      Returns:
      A BinaryData representing the InputStream.
      Throws:
      UncheckedIOException - If any error happens while reading the InputStream.
      NullPointerException - If inputStream is null.

    • fromStream

      public static BinaryData fromStream(InputStream inputStream, Long length)
      Creates an instance of BinaryData from the given InputStream. Depending on the type of inputStream, the BinaryData instance created may or may not allow reading the content more than once. The stream content is not cached if the stream is not read into a format that requires the content to be fully read into memory.

      NOTE: The InputStream is not closed by this function.

      Create an instance from an InputStream

       byte[] bytes = "Some Data".getBytes(StandardCharsets.UTF_8);
 final ByteArrayInputStream inputStream = new ByteArrayInputStream(bytes);
 BinaryData binaryData = BinaryData.fromStream(inputStream, (long) bytes.length);
 System.out.println(binaryData);
      Parameters:
      inputStream - The InputStream that BinaryData will represent.
      length - The length of data in bytes.
      Returns:
      A BinaryData representing the InputStream.
      Throws:
      UncheckedIOException - If any error happens while reading the InputStream.
      NullPointerException - If inputStream is null.

    • fromStreamAsync

      public static Mono<BinaryData> fromStreamAsync(InputStream inputStream)
      Creates an instance of BinaryData from the given InputStream. NOTE: The InputStream is not closed by this function.

      Create an instance from an InputStream

       final ByteArrayInputStream inputStream = new ByteArrayInputStream("Some Data".getBytes(StandardCharsets.UTF_8));

 Mono<BinaryData> binaryDataMono = BinaryData.fromStreamAsync(inputStream);

 Disposable subscriber = binaryDataMono
     .map(binaryData -> {
         System.out.println(binaryData.toString());
         return true;
     })
     .subscribe();

 // So that your program wait for above subscribe to complete.
 TimeUnit.SECONDS.sleep(5);
 subscriber.dispose();
      Parameters:
      inputStream - The InputStream that BinaryData will represent.
      Returns:
      A Mono of BinaryData representing the InputStream.
      Throws:
      UncheckedIOException - If any error happens while reading the InputStream.
      NullPointerException - If inputStream is null.

    • fromStreamAsync

      public static Mono<BinaryData> fromStreamAsync(InputStream inputStream, Long length)
      Creates an instance of BinaryData from the given InputStream. NOTE: The InputStream is not closed by this function.

      Create an instance from an InputStream

       byte[] bytes = "Some Data".getBytes(StandardCharsets.UTF_8);
 final ByteArrayInputStream inputStream = new ByteArrayInputStream(bytes);

 Mono<BinaryData> binaryDataMono = BinaryData.fromStreamAsync(inputStream, (long) bytes.length);

 Disposable subscriber = binaryDataMono
     .map(binaryData -> {
         System.out.println(binaryData.toString());
         return true;
     })
     .subscribe();

 // So that your program wait for above subscribe to complete.
 TimeUnit.SECONDS.sleep(5);
 subscriber.dispose();
      Parameters:
      inputStream - The InputStream that BinaryData will represent.
      length - The length of data in bytes.
      Returns:
      A Mono of BinaryData representing the InputStream.
      Throws:
      UncheckedIOException - If any error happens while reading the InputStream.
      NullPointerException - If inputStream is null.

    • fromFlux

      public static Mono<BinaryData> fromFlux(Flux<ByteBuffer> data)
      Creates an instance of BinaryData from the given Flux of ByteBuffer.

      Create an instance from a Flux of ByteBuffer

      This method aggregates data into single byte array.

       final byte[] data = "Some Data".getBytes(StandardCharsets.UTF_8);
 final Flux<ByteBuffer> dataFlux = Flux.just(ByteBuffer.wrap(data));

 Mono<BinaryData> binaryDataMono = BinaryData.fromFlux(dataFlux);

 Disposable subscriber = binaryDataMono
     .map(binaryData -> {
         System.out.println(binaryData.toString());
         return true;
     })
     .subscribe();

 // So that your program wait for above subscribe to complete.
 TimeUnit.SECONDS.sleep(5);
 subscriber.dispose();
      Parameters:
      data - The Flux of ByteBuffer that BinaryData will represent.
      Returns:
      A Mono of BinaryData representing the Flux of ByteBuffer.
      Throws:
      NullPointerException - If data is null.

    • fromFlux

      public static Mono<BinaryData> fromFlux(Flux<ByteBuffer> data, Long length)
      Creates an instance of BinaryData from the given Flux of ByteBuffer.

      Create an instance from a Flux of ByteBuffer

      This method aggregates data into single byte array.

       final byte[] data = "Some Data".getBytes(StandardCharsets.UTF_8);
 final long length = data.length;
 final Flux<ByteBuffer> dataFlux = Flux.just(ByteBuffer.wrap(data));

 Mono<BinaryData> binaryDataMono = BinaryData.fromFlux(dataFlux, length);

 Disposable subscriber = binaryDataMono
     .map(binaryData -> {
         System.out.println(binaryData.toString());
         return true;
     })
     .subscribe();

 // So that your program wait for above subscribe to complete.
 TimeUnit.SECONDS.sleep(5);
 subscriber.dispose();
      Parameters:
      data - The Flux of ByteBuffer that BinaryData will represent.
      length - The length of data in bytes.
      Returns:
      A Mono of BinaryData representing the Flux of ByteBuffer.
      Throws:
      IllegalArgumentException - if the length is less than zero.
      NullPointerException - if data is null.

    • fromFlux

      public static Mono<BinaryData> fromFlux(Flux<ByteBuffer> data, Long length, boolean bufferContent)
      Creates an instance of BinaryData from the given Flux of ByteBuffer.

      If bufferContent is true and length is null the length of the returned BinaryData will be based on the length calculated by buffering. If length is non-null it will always be used as the BinaryData length even if buffering determines a different length.

      Create an instance from a Flux of ByteBuffer

       final byte[] data = "Some Data".getBytes(StandardCharsets.UTF_8);
 final long length = data.length;
 final boolean shouldAggregateData = false;
 final Flux<ByteBuffer> dataFlux = Flux.just(ByteBuffer.wrap(data));

 Mono<BinaryData> binaryDataMono = BinaryData.fromFlux(dataFlux, length, shouldAggregateData);

 Disposable subscriber = binaryDataMono
     .map(binaryData -> {
         System.out.println(binaryData.toString());
         return true;
     })
     .subscribe();

 // So that your program wait for above subscribe to complete.
 TimeUnit.SECONDS.sleep(5);
 subscriber.dispose();
      Parameters:
      data - The Flux of ByteBuffer that BinaryData will represent.
      length - The length of data in bytes.
      bufferContent - A flag indicating whether Flux should be buffered eagerly or consumption deferred.
      Returns:
      A Mono of BinaryData representing the Flux of ByteBuffer.
      Throws:
      IllegalArgumentException - if the length is less than zero.
      NullPointerException - if data is null.

    • fromString

      public static BinaryData fromString(String data)
      Creates an instance of BinaryData from the given String.

      The String is converted into bytes using String.getBytes(Charset) passing StandardCharsets.UTF_8.

      Create an instance from a String

       final String data = "Some Data";
 // Following will use default character set as StandardCharsets.UTF_8
 BinaryData binaryData = BinaryData.fromString(data);
 System.out.println(binaryData.toString());
      Parameters:
      data - The String that BinaryData will represent.
      Returns:
      A BinaryData representing the String.
      Throws:
      NullPointerException - If data is null.

    • fromBytes

      public static BinaryData fromBytes(byte[] data)
      Creates an instance of BinaryData from the given byte array.

      If the byte array is zero length an empty BinaryData will be returned. Note that the input byte array is used as a reference by this instance of BinaryData and any changes to the byte array outside of this instance will result in the contents of this BinaryData instance being updated as well. To safely update the byte array without impacting the BinaryData instance, perform an array copy first.

      Create an instance from a byte array

       final byte[] data = "Some Data".getBytes(StandardCharsets.UTF_8);
 BinaryData binaryData = BinaryData.fromBytes(data);
 System.out.println(new String(binaryData.toBytes(), StandardCharsets.UTF_8));
      Parameters:
      data - The byte array that BinaryData will represent.
      Returns:
      A BinaryData representing the byte array.
      Throws:
      NullPointerException - If data is null.

    • fromByteBuffer

      public static BinaryData fromByteBuffer(ByteBuffer data)
      Creates an instance of BinaryData from the given ByteBuffer.

      If the ByteBuffer is zero length an empty BinaryData will be returned. Note that the input ByteBuffer is used as a reference by this instance of BinaryData and any changes to the ByteBuffer outside of this instance will result in the contents of this BinaryData instance being updated as well. To safely update the ByteBuffer without impacting the BinaryData instance, perform an array copy first.

      Create an instance from a ByteBuffer

       final ByteBuffer data = ByteBuffer.wrap("Some Data".getBytes(StandardCharsets.UTF_8));
 BinaryData binaryData = BinaryData.fromByteBuffer(data);
 System.out.println(binaryData);
      Parameters:
      data - The ByteBuffer that BinaryData will represent.
      Returns:
      A BinaryData representing the ByteBuffer.
      Throws:
      NullPointerException - If data is null.

    • fromListByteBuffer

      public static BinaryData fromListByteBuffer(List<ByteBuffer> data)
      Creates an instance of BinaryData from the given List of ByteBuffer.

      The input ByteBuffer instances are used as a reference by this instance of BinaryData and any changes to a ByteBuffer outside of this instance will result in the contents of this BinaryData instance being updated as well. To safely update the byte array without impacting the BinaryData instance, perform an array copy first.

      Create an instance from a List<ByteBuffer>

       final List<ByteBuffer> data = Stream.of("Some ", "data")
     .map(s -> ByteBuffer.wrap(s.getBytes(StandardCharsets.UTF_8)))
     .collect(Collectors.toList());
 BinaryData binaryData = BinaryData.fromListByteBuffer(data);
 System.out.println(binaryData);
      Parameters:
      data - The List of ByteBuffer that BinaryData will represent.
      Returns:
      A BinaryData representing the List of ByteBuffer.

    • fromObject

      public static BinaryData fromObject(Object data)
      Creates an instance of BinaryData by serializing the Object using the default JsonSerializer.

      Note: This method first looks for a JsonSerializerProvider implementation on the classpath. If no implementation is found, a default Jackson-based implementation will be used to serialize the object.

      Creating an instance from an Object

       final Person data = new Person().setName("John");

 // Provide your custom serializer or use Azure provided serializers.
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-gson
 BinaryData binaryData = BinaryData.fromObject(data);

 System.out.println(binaryData);
      Parameters:
      data - The object that will be JSON serialized that BinaryData will represent.
      Returns:
      A BinaryData representing the JSON serialized object.
      Throws:
      NullPointerException - If data is null.
      See Also:

    • fromObjectAsync

      public static Mono<BinaryData> fromObjectAsync(Object data)
      Creates an instance of BinaryData by serializing the Object using the default JsonSerializer.

      Note: This method first looks for a JsonSerializerProvider implementation on the classpath. If no implementation is found, a default Jackson-based implementation will be used to serialize the object.

      Creating an instance from an Object

       final Person data = new Person().setName("John");

 // Provide your custom serializer or use Azure provided serializers.
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-gson
 Disposable subscriber = BinaryData.fromObjectAsync(data)
     .subscribe(binaryData -> System.out.println(binaryData.toString()));

 // So that your program wait for above subscribe to complete.
 TimeUnit.SECONDS.sleep(5);
 subscriber.dispose();
      Parameters:
      data - The object that will be JSON serialized that BinaryData will represent.
      Returns:
      A Mono of BinaryData representing the JSON serialized object.
      See Also:

    • fromObject

      public static BinaryData fromObject(Object data, ObjectSerializer serializer)
      Creates an instance of BinaryData by serializing the Object using the passed ObjectSerializer.

      The passed ObjectSerializer can either be one of the implementations offered by the Azure SDKs or your own implementation.

      Azure SDK implementations

      Create an instance from an Object

       final Person data = new Person().setName("John");

 // Provide your custom serializer or use Azure provided serializers.
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-gson
 final ObjectSerializer serializer = new MyJsonSerializer(); // Replace this with your Serializer
 BinaryData binaryData = BinaryData.fromObject(data, serializer);

 System.out.println(binaryData.toString());
      Parameters:
      data - The object that will be serialized that BinaryData will represent. The serializer determines how null data is serialized.
      serializer - The ObjectSerializer used to serialize object.
      Returns:
      A BinaryData representing the serialized object.
      Throws:
      NullPointerException - If serializer is null.
      See Also:

    • fromObjectAsync

      public static Mono<BinaryData> fromObjectAsync(Object data, ObjectSerializer serializer)
      Creates an instance of BinaryData by serializing the Object using the passed ObjectSerializer.

      The passed ObjectSerializer can either be one of the implementations offered by the Azure SDKs or your own implementation.

      Azure SDK implementations

      Create an instance from an Object

       final Person data = new Person().setName("John");

 // Provide your custom serializer or use Azure provided serializers.
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-gson
 final ObjectSerializer serializer = new MyJsonSerializer(); // Replace this with your Serializer
 Disposable subscriber = BinaryData.fromObjectAsync(data, serializer)
     .subscribe(binaryData -> System.out.println(binaryData.toString()));

 // So that your program wait for above subscribe to complete.
 TimeUnit.SECONDS.sleep(5);
 subscriber.dispose();
      Parameters:
      data - The object that will be serialized that BinaryData will represent. The serializer determines how null data is serialized.
      serializer - The ObjectSerializer used to serialize object.
      Returns:
      A Mono of BinaryData representing the serialized object.
      Throws:
      NullPointerException - If serializer is null.
      See Also:

    • fromFile

      public static BinaryData fromFile(Path file)
      Creates a BinaryData that uses the content of the file at Path as its data. This method checks for the existence of the file at the time of creating an instance of BinaryData. The file, however, is not read until there is an attempt to read the contents of the returned BinaryData instance.

      Create an instance from a file

      The BinaryData returned from this method uses 8KB chunk size when reading file content.

       BinaryData binaryData = BinaryData.fromFile(new File("path/to/file").toPath());
 System.out.println(new String(binaryData.toBytes(), StandardCharsets.UTF_8));
      Parameters:
      file - The Path that will be the BinaryData data.
      Returns:
      A new BinaryData.
      Throws:
      NullPointerException - If file is null.

    • fromFile

      public static BinaryData fromFile(Path file, int chunkSize)
      Creates a BinaryData that uses the content of the file at file as its data. This method checks for the existence of the file at the time of creating an instance of BinaryData. The file, however, is not read until there is an attempt to read the contents of the returned BinaryData instance.

      Create an instance from a file

       BinaryData binaryData = BinaryData.fromFile(new File("path/to/file").toPath(), 8092);
 System.out.println(new String(binaryData.toBytes(), StandardCharsets.UTF_8));
      Parameters:
      file - The Path that will be the BinaryData data.
      chunkSize - The requested size for each read of the path.
      Returns:
      A new BinaryData.
      Throws:
      NullPointerException - If file is null.
      IllegalArgumentException - If offset or length are negative or offset plus length is greater than the file size or chunkSize is less than or equal to 0.
      UncheckedIOException - if the file does not exist.

    • fromFile

      public static BinaryData fromFile(Path file, Long position, Long length)
      Creates a BinaryData that uses the content of the file at file as its data. This method checks for the existence of the file at the time of creating an instance of BinaryData. The file, however, is not read until there is an attempt to read the contents of the returned BinaryData instance.

      Create an instance from a file

      The BinaryData returned from this method uses 8KB chunk size when reading file content.

       long position = 1024;
 long length = 100 * 1048;
 BinaryData binaryData = BinaryData.fromFile(
     new File("path/to/file").toPath(), position, length);
 System.out.println(new String(binaryData.toBytes(), StandardCharsets.UTF_8));
      Parameters:
      file - The Path that will be the BinaryData data.
      position - Position, or offset, within the path where reading begins.
      length - Maximum number of bytes to be read from the path.
      Returns:
      A new BinaryData.
      Throws:
      NullPointerException - If file is null.
      IllegalArgumentException - If offset or length are negative or offset plus length is greater than the file size or chunkSize is less than or equal to 0.
      UncheckedIOException - if the file does not exist.

    • fromFile

      public static BinaryData fromFile(Path file, Long position, Long length, int chunkSize)
      Creates a BinaryData that uses the content of the file at file as its data. This method checks for the existence of the file at the time of creating an instance of BinaryData. The file, however, is not read until there is an attempt to read the contents of the returned BinaryData instance.

      Create an instance from a file

       long position = 1024;
 long length = 100 * 1048;
 int chunkSize = 8092;
 BinaryData binaryData = BinaryData.fromFile(
     new File("path/to/file").toPath(), position, length, chunkSize);
 System.out.println(new String(binaryData.toBytes(), StandardCharsets.UTF_8));
      Parameters:
      file - The Path that will be the BinaryData data.
      position - Position, or offset, within the path where reading begins.
      length - Maximum number of bytes to be read from the path.
      chunkSize - The requested size for each read of the path.
      Returns:
      A new BinaryData.
      Throws:
      NullPointerException - If file is null.
      IllegalArgumentException - If offset or length are negative or offset plus length is greater than the file size or chunkSize is less than or equal to 0.
      UncheckedIOException - if the file does not exist.

    • toBytes

      public byte[] toBytes()
      Returns a byte array representation of this BinaryData.

      This method returns a reference to the underlying byte array. Modifying the contents of the returned byte array may change the content of this BinaryData instance. If the content source of this BinaryData instance is a file, an InputStream, or a Flux<ByteBuffer> the source is not modified. To safely update the byte array, it is recommended to make a copy of the contents first.

      If the BinaryData is larger than the maximum size allowed for a byte[] this will throw an IllegalStateException.

      Returns:
      A byte array representing this BinaryData.
      Throws:
      IllegalStateException - If the BinaryData is larger than the maximum size allowed for a byte[].

    • toString

      public String toString()
      Returns a String representation of this BinaryData by converting its data using the UTF-8 character set. A new instance of String is created each time this method is called.

      If the BinaryData is larger than the maximum size allowed for a String this will throw an IllegalStateException.

      Overrides:
      toString in class Object
      Returns:
      A String representing this BinaryData.
      Throws:
      IllegalStateException - If the BinaryData is larger than the maximum size allowed for a String.

    • toObject

      public <T> T toObject(Class<T> clazz)
      Returns an Object representation of this BinaryData by deserializing its data using the default JsonSerializer. Each time this method is called, the content is deserialized and a new instance of type T is returned. So, calling this method repeatedly to convert the underlying data source into the same type is not recommended.

      The type, represented by Class, should be a non-generic class, for generic classes use toObject(TypeReference).

      Note: This method first looks for a JsonSerializerProvider implementation on the classpath. If no implementation is found, a default Jackson-based implementation will be used to deserialize the object.

      Get a non-generic Object from the BinaryData

       final Person data = new Person().setName("John");

 // Ensure your classpath have the Serializer to serialize the object which implement implement
 // com.azure.core.util.serializer.JsonSerializer interface.
 // Or use Azure provided libraries for this.
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-gson

 BinaryData binaryData = BinaryData.fromObject(data);

 Person person = binaryData.toObject(Person.class);
 System.out.println(person.getName());
      Type Parameters:
      T - Type of the deserialized Object.
      Parameters:
      clazz - The Class representing the Object's type.
      Returns:
      An Object representing the JSON deserialized BinaryData.
      Throws:
      NullPointerException - If clazz is null.
      See Also:

    • toObject

      public <T> T toObject(TypeReference<T> typeReference)
      Returns an Object representation of this BinaryData by deserializing its data using the default JsonSerializer. Each time this method is called, the content is deserialized and a new instance of type T is returned. So, calling this method repeatedly to convert the underlying data source into the same type is not recommended.

      The type, represented by TypeReference, can either be a generic or non-generic type. If the type is generic create a sub-type of TypeReference, if the type is non-generic use TypeReference.createInstance(Class).

      Note: This method first looks for a JsonSerializerProvider implementation on the classpath. If no implementation is found, a default Jackson-based implementation will be used to deserialize the object.

      Get a non-generic Object from the BinaryData

       final Person data = new Person().setName("John");

 // Ensure your classpath have the Serializer to serialize the object which implement implement
 // com.azure.core.util.serializer.JsonSerializer interface.
 // Or use Azure provided libraries for this.
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-gson

 BinaryData binaryData = BinaryData.fromObject(data);

 Person person = binaryData.toObject(TypeReference.createInstance(Person.class));
 System.out.println(person.getName());

      Get a generic Object from the BinaryData

       final Person person1 = new Person().setName("John");
 final Person person2 = new Person().setName("Jack");

 List<Person> personList = new ArrayList<>();
 personList.add(person1);
 personList.add(person2);

 // Ensure your classpath have the Serializer to serialize the object which implement implement
 // com.azure.core.util.serializer.JsonSerializer interface.
 // Or use Azure provided libraries for this.
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-gson


 BinaryData binaryData = BinaryData.fromObject(personList);

 List<Person> persons = binaryData.toObject(new TypeReference<List<Person>>() { });
 persons.forEach(person -> System.out.println(person.getName()));
      Type Parameters:
      T - Type of the deserialized Object.
      Parameters:
      typeReference - The TypeReference representing the Object's type.
      Returns:
      An Object representing the JSON deserialized BinaryData.
      Throws:
      NullPointerException - If typeReference is null.
      See Also:

    • toObject

      public <T> T toObject(Class<T> clazz, ObjectSerializer serializer)
      Returns an Object representation of this BinaryData by deserializing its data using the passed ObjectSerializer. Each time this method is called, the content is deserialized and a new instance of type T is returned. So, calling this method repeatedly to convert the underlying data source into the same type is not recommended.

      The type, represented by Class, should be a non-generic class, for generic classes use toObject(TypeReference, ObjectSerializer).

      The passed ObjectSerializer can either be one of the implementations offered by the Azure SDKs or your own implementation.

      Azure SDK implementations

      Get a non-generic Object from the BinaryData

       final Person data = new Person().setName("John");

 // Provide your custom serializer or use Azure provided serializers.
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-gson

 final ObjectSerializer serializer = new MyJsonSerializer(); // Replace this with your Serializer
 BinaryData binaryData = BinaryData.fromObject(data, serializer);

 Person person = binaryData.toObject(Person.class, serializer);
 System.out.println("Name : " + person.getName());
      Type Parameters:
      T - Type of the deserialized Object.
      Parameters:
      clazz - The Class representing the Object's type.
      serializer - The ObjectSerializer used to deserialize object.
      Returns:
      An Object representing the deserialized BinaryData.
      Throws:
      NullPointerException - If clazz or serializer is null.
      See Also:

    • toObject

      public <T> T toObject(TypeReference<T> typeReference, ObjectSerializer serializer)
      Returns an Object representation of this BinaryData by deserializing its data using the passed ObjectSerializer. Each time this method is called, the content is deserialized and a new instance of type T is returned. So, calling this method repeatedly to convert the underlying data source into the same type is not recommended.

      The type, represented by TypeReference, can either be a generic or non-generic type. If the type is generic create a sub-type of TypeReference, if the type is non-generic use TypeReference.createInstance(Class).

      The passed ObjectSerializer can either be one of the implementations offered by the Azure SDKs or your own implementation.

      Azure SDK implementations

      Get a non-generic Object from the BinaryData

       final Person data = new Person().setName("John");

 // Provide your custom serializer or use Azure provided serializers.
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-gson

 final ObjectSerializer serializer = new MyJsonSerializer(); // Replace this with your Serializer
 BinaryData binaryData = BinaryData.fromObject(data, serializer);

 Person person = binaryData.toObject(TypeReference.createInstance(Person.class), serializer);
 System.out.println("Name : " + person.getName());

      Get a generic Object from the BinaryData

       final Person person1 = new Person().setName("John");
 final Person person2 = new Person().setName("Jack");

 List<Person> personList = new ArrayList<>();
 personList.add(person1);
 personList.add(person2);

 final ObjectSerializer serializer = new MyJsonSerializer(); // Replace this with your Serializer
 BinaryData binaryData = BinaryData.fromObject(personList, serializer);

 // Retains the type of the list when deserializing
 List<Person> persons = binaryData.toObject(new TypeReference<List<Person>>() { }, serializer);
 persons.forEach(person -> System.out.println("Name : " + person.getName()));
      Type Parameters:
      T - Type of the deserialized Object.
      Parameters:
      typeReference - The TypeReference representing the Object's type.
      serializer - The ObjectSerializer used to deserialize object.
      Returns:
      An Object representing the deserialized BinaryData.
      Throws:
      NullPointerException - If typeReference or serializer is null.
      See Also:

    • toObjectAsync

      public <T> Mono<T> toObjectAsync(Class<T> clazz)
      Returns an Object representation of this BinaryData by deserializing its data using the default JsonSerializer. Each time this method is called, the content is deserialized and a new instance of type T is returned. So, calling this method repeatedly to convert the underlying data source into the same type is not recommended.

      The type, represented by Class, should be a non-generic class, for generic classes use toObject(TypeReference).

      Note: This method first looks for a JsonSerializerProvider implementation on the classpath. If no implementation is found, a default Jackson-based implementation will be used to deserialize the object.

      Get a non-generic Object from the BinaryData

       final Person data = new Person().setName("John");

 // Ensure your classpath have the Serializer to serialize the object which implement implement
 // com.azure.core.util.serializer.JsonSerializer interface.
 // Or use Azure provided libraries for this.
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-gson

 BinaryData binaryData = BinaryData.fromObject(data);

 Disposable subscriber = binaryData.toObjectAsync(Person.class)
     .subscribe(person -> System.out.println(person.getName()));

 // So that your program wait for above subscribe to complete.
 TimeUnit.SECONDS.sleep(5);
 subscriber.dispose();
      Type Parameters:
      T - Type of the deserialized Object.
      Parameters:
      clazz - The Class representing the Object's type.
      Returns:
      A Mono of Object representing the JSON deserialized BinaryData.
      Throws:
      NullPointerException - If clazz is null.
      See Also:

    • toObjectAsync

      public <T> Mono<T> toObjectAsync(TypeReference<T> typeReference)
      Returns an Object representation of this BinaryData by deserializing its data using the default JsonSerializer. Each time this method is called, the content is deserialized and a new instance of type T is returned. So, calling this method repeatedly to convert the underlying data source into the same type is not recommended.

      The type, represented by TypeReference, can either be a generic or non-generic type. If the type is generic create a sub-type of TypeReference, if the type is non-generic use TypeReference.createInstance(Class).

      Note: This method first looks for a JsonSerializerProvider implementation on the classpath. If no implementation is found, a default Jackson-based implementation will be used to deserialize the object.

      Get a non-generic Object from the BinaryData

       final Person data = new Person().setName("John");

 // Ensure your classpath have the Serializer to serialize the object which implement implement
 // com.azure.core.util.serializer.JsonSerializer interface.
 // Or use Azure provided libraries for this.
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-gson

 BinaryData binaryData = BinaryData.fromObject(data);

 Disposable subscriber = binaryData.toObjectAsync(TypeReference.createInstance(Person.class))
     .subscribe(person -> System.out.println(person.getName()));

 // So that your program wait for above subscribe to complete.
 TimeUnit.SECONDS.sleep(5);
 subscriber.dispose();

      Get a generic Object from the BinaryData

       final Person person1 = new Person().setName("John");
 final Person person2 = new Person().setName("Jack");

 List<Person> personList = new ArrayList<>();
 personList.add(person1);
 personList.add(person2);

 BinaryData binaryData = BinaryData.fromObject(personList);

 Disposable subscriber = binaryData.toObjectAsync(new TypeReference<List<Person>>() { })
     .subscribe(persons -> persons.forEach(person -> System.out.println(person.getName())));

 // So that your program wait for above subscribe to complete.
 TimeUnit.SECONDS.sleep(5);
 subscriber.dispose();
      Type Parameters:
      T - Type of the deserialized Object.
      Parameters:
      typeReference - The TypeReference representing the Object's type.
      Returns:
      A Mono of Object representing the JSON deserialized BinaryData.
      Throws:
      NullPointerException - If typeReference is null.
      See Also:

    • toObjectAsync

      public <T> Mono<T> toObjectAsync(Class<T> clazz, ObjectSerializer serializer)
      Returns an Object representation of this BinaryData by deserializing its data using the passed ObjectSerializer. Each time this method is called, the content is deserialized and a new instance of type T is returned. So, calling this method repeatedly to convert the underlying data source into the same type is not recommended.

      The type, represented by Class, should be a non-generic class, for generic classes use toObject(TypeReference, ObjectSerializer).

      The passed ObjectSerializer can either be one of the implementations offered by the Azure SDKs or your own implementation.

      Azure SDK implementations

      Get a non-generic Object from the BinaryData

       final Person data = new Person().setName("John");

 // Provide your custom serializer or use Azure provided serializers.
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-gson

 final ObjectSerializer serializer = new MyJsonSerializer(); // Replace this with your Serializer
 BinaryData binaryData = BinaryData.fromObject(data, serializer);

 Disposable subscriber = binaryData.toObjectAsync(Person.class, serializer)
     .subscribe(person -> System.out.println(person.getName()));

 // So that your program wait for above subscribe to complete.
 TimeUnit.SECONDS.sleep(5);
 subscriber.dispose();
      Type Parameters:
      T - Type of the deserialized Object.
      Parameters:
      clazz - The Class representing the Object's type.
      serializer - The ObjectSerializer used to deserialize object.
      Returns:
      A Mono of Object representing the deserialized BinaryData.
      Throws:
      NullPointerException - If clazz or serializer is null.
      See Also:

    • toObjectAsync

      public <T> Mono<T> toObjectAsync(TypeReference<T> typeReference, ObjectSerializer serializer)
      Returns an Object representation of this BinaryData by deserializing its data using the passed ObjectSerializer. Each time this method is called, the content is deserialized and a new instance of type T is returned. So, calling this method repeatedly to convert the underlying data source into the same type is not recommended.

      The type, represented by TypeReference, can either be a generic or non-generic type. If the type is generic create a sub-type of TypeReference, if the type is non-generic use TypeReference.createInstance(Class).

      The passed ObjectSerializer can either be one of the implementations offered by the Azure SDKs or your own implementation.

      Azure SDK implementations

      Get a non-generic Object from the BinaryData

       final Person data = new Person().setName("John");

 // Provide your custom serializer or use Azure provided serializers.
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://central.sonatype.com/artifact/com.azure/azure-core-serializer-json-gson

 final ObjectSerializer serializer = new MyJsonSerializer(); // Replace this with your Serializer
 BinaryData binaryData = BinaryData.fromObject(data, serializer);

 Disposable subscriber = binaryData
     .toObjectAsync(TypeReference.createInstance(Person.class), serializer)
     .subscribe(person -> System.out.println(person.getName()));

 // So that your program wait for above subscribe to complete.
 TimeUnit.SECONDS.sleep(5);
 subscriber.dispose();

      Get a generic Object from the BinaryData

       final Person person1 = new Person().setName("John");
 final Person person2 = new Person().setName("Jack");

 List<Person> personList = new ArrayList<>();
 personList.add(person1);
 personList.add(person2);

 // Provide your custom serializer or use Azure provided serializers.
 // https://mvnrepository.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://mvnrepository.com/artifact/com.azure/azure-core-serializer-json-gson

 final ObjectSerializer serializer = new MyJsonSerializer(); // Replace this with your Serializer
 BinaryData binaryData = BinaryData.fromObject(personList, serializer);

 Disposable subscriber = binaryData
     .toObjectAsync(new TypeReference<List<Person>>() { }, serializer) // retains the generic type information
     .subscribe(persons -> persons.forEach(person -> System.out.println(person.getName())));

 // So that your program wait for above subscribe to complete.
 TimeUnit.SECONDS.sleep(5);
 subscriber.dispose();
      Type Parameters:
      T - Type of the deserialized Object.
      Parameters:
      typeReference - The TypeReference representing the Object's type.
      serializer - The ObjectSerializer used to deserialize object.
      Returns:
      A Mono of Object representing the deserialized BinaryData.
      Throws:
      NullPointerException - If typeReference or serializer is null.
      See Also:

    • toStream

      public InputStream toStream()
      Returns an InputStream representation of this BinaryData.

      Get an InputStream from the BinaryData

       final byte[] data = "Some Data".getBytes(StandardCharsets.UTF_8);
 BinaryData binaryData = BinaryData.fromStream(new ByteArrayInputStream(data), (long) data.length);
 final byte[] bytes = new byte[data.length];
 try (InputStream inputStream = binaryData.toStream()) {
     inputStream.read(bytes, 0, data.length);
     System.out.println(new String(bytes));
 }
      Returns:
      An InputStream representing the BinaryData.

    • toByteBuffer

      public ByteBuffer toByteBuffer()
      Returns a read-only ByteBuffer representation of this BinaryData.

      Attempting to mutate the returned ByteBuffer will throw a ReadOnlyBufferException.

      Get a read-only ByteBuffer from the BinaryData

       final byte[] data = "Some Data".getBytes(StandardCharsets.UTF_8);
 BinaryData binaryData = BinaryData.fromBytes(data);
 final byte[] bytes = new byte[data.length];
 binaryData.toByteBuffer().get(bytes, 0, data.length);
 System.out.println(new String(bytes));
      Returns:
      A read-only ByteBuffer representing the BinaryData.

    • toFluxByteBuffer

      public Flux<ByteBuffer> toFluxByteBuffer()
      Returns the content of this BinaryData instance as a flux of ByteBuffers. The content is not read from the underlying data source until the Flux is subscribed to.
      Returns:
      the content of this BinaryData instance as a flux of ByteBuffers.

    • writeTo

      public void writeTo(OutputStream outputStream) throws IOException
      Writes the contents of this BinaryData to the given OutputStream.

      This method does not close the OutputStream.

      The contents of this BinaryData will be written without buffering. If the underlying data source isn't isReplayable(), after this method is called the BinaryData will be consumed and can't be read again. If it needs to be read again, use toReplayableBinaryData() to create a replayable copy.

      Parameters:
      outputStream - The OutputStream to write the contents of this BinaryData to.
      Throws:
      NullPointerException - If outputStream is null.
      IOException - If an I/O error occurs.

    • writeTo

      public void writeTo(WritableByteChannel channel) throws IOException
      Writes the contents of this BinaryData to the given WritableByteChannel.

      This method does not close the WritableByteChannel.

      The contents of this BinaryData will be written without buffering. If the underlying data source isn't isReplayable(), after this method is called the BinaryData will be consumed and can't be read again. If it needs to be read again, use toReplayableBinaryData() to create a replayable copy.

      Parameters:
      channel - The WritableByteChannel to write the contents of this BinaryData to.
      Throws:
      NullPointerException - If channel is null.
      IOException - If an I/O error occurs.

    • writeTo

      public Mono<Void> writeTo(AsynchronousByteChannel channel)
      Writes the contents of this BinaryData to the given AsynchronousByteChannel.

      This method does not close the AsynchronousByteChannel.

      The contents of this BinaryData will be written without buffering. If the underlying data source isn't isReplayable(), after this method is called the BinaryData will be consumed and can't be read again. If it needs to be read again, use toReplayableBinaryDataAsync() to create a replayable copy.

      Parameters:
      channel - The AsynchronousByteChannel to write the contents of this BinaryData to.
      Returns:
      A Mono the completes once content has been written or had an error writing.
      Throws:
      NullPointerException - If channel is null.

    • writeTo

      public void writeTo(com.azure.json.JsonWriter jsonWriter) throws IOException
      Writes the contents of this BinaryData to the given JsonWriter.

      This method does not close or flush the JsonWriter.

      The contents of this BinaryData will be written without buffering. If the underlying data source isn't isReplayable(), after this method is called the BinaryData will be consumed and can't be read again. If it needs to be read again, use toReplayableBinaryData() to create a replayable copy.

      Parameters:
      jsonWriter - The JsonWriter to write the contents of this BinaryData to.
      Throws:
      NullPointerException - If jsonWriter is null.
      IOException - If an I/O error occurs during writing.

    • getLength

      public Long getLength()
      Returns the length of the content, if it is known. The length can be null if the source did not specify the length or the length cannot be determined without reading the whole content.
      Returns:
      the length of the content, if it is known.

    • isReplayable

      public boolean isReplayable()
      Returns a flag indicating whether the content can be repeatedly consumed using all accessors including toStream() and toFluxByteBuffer()

      Replayability does not imply thread-safety. The caller must not use data accessors simultaneously regardless of what this method returns. 

       BinaryData binaryData = binaryDataProducer();

 if (!binaryData.isReplayable()) {
     binaryData = binaryData.toReplayableBinaryData();
 }

 streamConsumer(binaryData.toStream());
 streamConsumer(binaryData.toStream());
 
       Mono.fromCallable(this::binaryDataProducer)
     .flatMap(binaryData -> {
         if (binaryData.isReplayable()) {
             return Mono.just(binaryData);
         } else  {
             return binaryData.toReplayableBinaryDataAsync();
         }
     })
     .flatMap(replayableBinaryData ->
         fluxConsumer(replayableBinaryData.toFluxByteBuffer())
             .then(fluxConsumer(replayableBinaryData.toFluxByteBuffer())))
     .subscribe();
      Returns:
      a flag indicating whether the content can be repeatedly consumed using all accessors.

    • toReplayableBinaryData

      public BinaryData toReplayableBinaryData()
      Converts the BinaryData into a BinaryData that is replayable, i.e. content can be consumed repeatedly using all accessors including toStream() and toFluxByteBuffer()

      A BinaryData that is already replayable is returned as is. Otherwise techniques like marking and resetting a stream or buffering in memory are employed to assure replayability.

      Replayability does not imply thread-safety. The caller must not use data accessors of returned BinaryData simultaneously. 

       BinaryData binaryData = binaryDataProducer();

 if (!binaryData.isReplayable()) {
     binaryData = binaryData.toReplayableBinaryData();
 }

 streamConsumer(binaryData.toStream());
 streamConsumer(binaryData.toStream());
      Returns:
      Replayable BinaryData.

    • toReplayableBinaryDataAsync

      public Mono<BinaryData> toReplayableBinaryDataAsync()
      Converts the BinaryData into a BinaryData that is replayable, i.e. content can be consumed repeatedly using all accessors including toStream() and toFluxByteBuffer()

      A BinaryData that is already replayable is returned as is. Otherwise techniques like marking and resetting a stream or buffering in memory are employed to assure replayability.

      Replayability does not imply thread-safety. The caller must not use data accessors of returned BinaryData simultaneously. 

       Mono.fromCallable(this::binaryDataProducer)
     .flatMap(binaryData -> {
         if (binaryData.isReplayable()) {
             return Mono.just(binaryData);
         } else  {
             return binaryData.toReplayableBinaryDataAsync();
         }
     })
     .flatMap(replayableBinaryData ->
         fluxConsumer(replayableBinaryData.toFluxByteBuffer())
             .then(fluxConsumer(replayableBinaryData.toFluxByteBuffer())))
     .subscribe();
      Returns:
      A Mono of BinaryData representing the replayable BinaryData.