Share via

BinaryData Class

  • Reference
Package:
com.azure.core.util
Maven Artifact:
com.azure:azure-core:1.53.0
  • java.lang.Object
    • com.azure.core.util.BinaryData

public final class BinaryData

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[] data).

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

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

Method Summary

Modifier and Type Method and Description
T toObject(TypeReference<T> typeReference)

Returns an Object representation of this BinaryData by deserializing its data using the default JsonSerializer.
T toObject(TypeReference<T> typeReference, ObjectSerializer serializer)

Returns an Object representation of this BinaryData by deserializing its data using the passed ObjectSerializer.
T toObject(Class<T> clazz)

Returns an Object representation of this BinaryData by deserializing its data using the default JsonSerializer.
T toObject(Class<T> clazz, ObjectSerializer serializer)

Returns an Object representation of this BinaryData by deserializing its data using the passed ObjectSerializer.
Mono<T> toObjectAsync(TypeReference<T> typeReference)

Returns an Object representation of this BinaryData by deserializing its data using the default JsonSerializer.
Mono<T> toObjectAsync(TypeReference<T> typeReference, ObjectSerializer serializer)

Returns an Object representation of this BinaryData by deserializing its data using the passed ObjectSerializer.
Mono<T> toObjectAsync(Class<T> clazz)

Returns an Object representation of this BinaryData by deserializing its data using the default JsonSerializer.
Mono<T> toObjectAsync(Class<T> clazz, ObjectSerializer serializer)

Returns an Object representation of this BinaryData by deserializing its data using the passed ObjectSerializer.
static BinaryData fromByteBuffer(ByteBuffer data)

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

Creates an instance of BinaryData from the given byte array.
static BinaryData fromFile(Path file)

Creates a BinaryData that uses the content of the file at Path as its data.
static BinaryData fromFile(Path file, int chunkSize)

Creates a BinaryData that uses the content of the file at file as its data.
static BinaryData fromFile(Path file, Long position, Long length)

Creates a BinaryData that uses the content of the file at file as its data.
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.
static Mono<BinaryData> fromFlux(Flux<ByteBuffer> data)

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

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

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

Creates an instance of BinaryData from the given List of ByteBuffer.
static BinaryData fromObject(Object data)

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

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

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

Creates an instance of BinaryData by serializing the Object using the passed ObjectSerializer.
static BinaryData fromStream(InputStream inputStream)

Creates an instance of BinaryData from the given InputStream.
static BinaryData fromStream(InputStream inputStream, Long length)

Creates an instance of BinaryData from the given InputStream.
static Mono<BinaryData> fromStreamAsync(InputStream inputStream)

Creates an instance of BinaryData from the given InputStream.
static Mono<BinaryData> fromStreamAsync(InputStream inputStream, Long length)

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

Creates an instance of BinaryData from the given String.
Long getLength()

Returns the length of the content, if it is known.
boolean isReplayable()

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

Returns a read-only ByteBuffer representation of this BinaryData.
byte[] toBytes()

Returns a byte array representation of this BinaryData.
Flux<ByteBuffer> toFluxByteBuffer()

Returns the content of this BinaryData instance as a flux of ByteBuffers.
BinaryData toReplayableBinaryData()

Converts the BinaryData into a BinaryData that is replayable, i.e.
Mono<BinaryData> toReplayableBinaryDataAsync()

Converts the BinaryData into a BinaryData that is replayable, i.e.
InputStream toStream()

Returns an InputStream representation of this BinaryData.
String toString()

Returns a String representation of this BinaryData by converting its data using the UTF-8 character set.
void writeTo(JsonWriter jsonWriter)

Writes the contents of this BinaryData to the given JsonWriter.
void writeTo(OutputStream outputStream)

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

Writes the contents of this BinaryData to the given AsynchronousByteChannel.
void writeTo(WritableByteChannel channel)

Writes the contents of this BinaryData to the given WritableByteChannel.

Methods inherited from java.lang.Object

clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Method Details

toObject

public T toObject(TypeReference 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<T>, can either be a generic or non-generic type. If the type is generic create a sub-type of TypeReference<T>, if the type is non-generic use createInstance(Class<T> clazz).

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()));

Parameters:

typeReference - The TypeReference<T> representing the Object's type.

Returns:

An Object representing the JSON deserialized BinaryData.

toObject

public T toObject(TypeReference 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<T>, can either be a generic or non-generic type. If the type is generic create a sub-type of TypeReference<T>, if the type is non-generic use createInstance(Class<T> clazz).

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()));

Parameters:

typeReference - The TypeReference<T> representing the Object's type.
serializer - The ObjectSerializer used to deserialize object.

Returns:

An Object representing the deserialized BinaryData.

toObject

public T toObject(Class 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<T> 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());

Parameters:

clazz - The Class representing the Object's type.

Returns:

An Object representing the JSON deserialized BinaryData.

toObject

public T toObject(Class 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<T> typeReference, ObjectSerializer serializer).

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());

Parameters:

clazz - The Class representing the Object's type.
serializer - The ObjectSerializer used to deserialize object.

Returns:

An Object representing the deserialized BinaryData.

toObjectAsync

public Mono toObjectAsync(TypeReference 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<T>, can either be a generic or non-generic type. If the type is generic create a sub-type of TypeReference<T>, if the type is non-generic use createInstance(Class<T> clazz).

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();

Parameters:

typeReference - The TypeReference<T> representing the Object's type.

Returns:

A Mono of Object representing the JSON deserialized BinaryData.

toObjectAsync

public Mono toObjectAsync(TypeReference 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<T>, can either be a generic or non-generic type. If the type is generic create a sub-type of TypeReference<T>, if the type is non-generic use createInstance(Class<T> clazz).

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();

Parameters:

typeReference - The TypeReference<T> representing the Object's type.
serializer - The ObjectSerializer used to deserialize object.

Returns:

A Mono of Object representing the deserialized BinaryData.

toObjectAsync

public Mono toObjectAsync(Class 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<T> 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();

Parameters:

clazz - The Class representing the Object's type.

Returns:

A Mono of Object representing the JSON deserialized BinaryData.

toObjectAsync

public Mono toObjectAsync(Class 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<T> typeReference, ObjectSerializer serializer).

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();

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.

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.

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.

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.

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.

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.

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.

fromFlux

public static Mono fromFlux(Flux 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.

fromFlux

public static Mono fromFlux(Flux 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.

fromFlux

public static Mono fromFlux(Flux 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.

fromListByteBuffer

public static BinaryData fromListByteBuffer(List 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

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.

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.

fromObjectAsync

public static Mono 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.

fromObjectAsync

public static Mono 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.

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.

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.

fromStreamAsync

public static Mono 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.

fromStreamAsync

public static Mono 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.

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.

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.

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.

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 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.

toFluxByteBuffer

public Flux 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.

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 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.

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.

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:

BinaryData.toString()

Returns:

A String representing this BinaryData.

writeTo

public void writeTo(JsonWriter jsonWriter)

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:

IOException

 - If jsonWriter is null.

writeTo

public void writeTo(OutputStream outputStream)

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:

IOException

 - If outputStream is null.

writeTo

public Mono 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.

writeTo

public void writeTo(WritableByteChannel channel)

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:

IOException

 - If channel is null.

Applies to