com.azure.core.util

Class BinaryData

java.lang.Object

com.azure.core.util.BinaryData

public final class BinaryData
extends Object

This class is an abstraction over many different ways that binary data can be represented. The BinaryData can be created from InputStream, Flux of ByteBuffer, String, Object, or byte array.

Immutable data

BinaryData is constructed by copying the given data. Once BinaryData is instantiated, it can not be changed. It provides various convenient APIs to get data out of BinaryData, they all start with the 'to' prefix, for example BinaryData.toBytes().

Code samples are presented below.

Create an instance from Bytes

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

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

Create an instance from Object

 class Person {
     {@literal @}JsonProperty
     private String name;
 
     {@literal @}JsonSetter
     public Person setName(String name) {
         this.name = name;
         return this;
     }
 
     {@literal @}JsonGetter
     public String getName() {
         return name;
     }
 }
 final Person data = new Person().setName("John");
 
 // 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
 BinaryData binaryData = BinaryData.fromObject(data);
 
 

See Also:

ObjectSerializer, JsonSerializer, More about serialization

Method Summary

Modifier and Type	Method and Description
static BinaryData	fromBytes(byte[] data) Creates a BinaryData instance with given byte array data.
static Mono<BinaryData>	fromFlux(Flux<ByteBuffer> data) Creates a BinaryData instance with given Flux of ByteBuffer as source of data.
static BinaryData	fromObject(Object data) Serialize the given Object into BinaryData using json serializer which is available on classpath.
static BinaryData	fromObject(Object data, ObjectSerializer serializer) Serialize the given Object into BinaryData using the provided ObjectSerializer.
static Mono<BinaryData>	fromObjectAsync(Object data) Serialize the given Object into BinaryData using json serializer which is available on classpath.
static Mono<BinaryData>	fromObjectAsync(Object data, ObjectSerializer serializer) Serialize the given Object into Mono BinaryData using the provided ObjectSerializer.
static BinaryData	fromStream(InputStream inputStream) Creates a BinaryData instance with given InputStream as source of data.
static Mono<BinaryData>	fromStreamAsync(InputStream inputStream) Asynchronously creates a BinaryData instance with the given InputStream as source of data.
static BinaryData	fromString(String data) Creates a BinaryData instance with given data.
byte[]	toBytes() Provides byte array representation of this BinaryData object.
<T> T	toObject(TypeReference<T> typeReference) Deserialize the bytes into the Object of given type by using json serializer which is available in classpath.
<T> T	toObject(TypeReference<T> typeReference, ObjectSerializer serializer) Deserialize the bytes into the Object of given type by applying the provided ObjectSerializer on the data.
<T> Mono<T>	toObjectAsync(TypeReference<T> typeReference) Return a Mono by deserializing the bytes into the Object of given type after applying the Json serializer found on classpath.
<T> Mono<T>	toObjectAsync(TypeReference<T> typeReference, ObjectSerializer serializer) Return a Mono by deserializing the bytes into the Object of given type after applying the provided ObjectSerializer on the BinaryData.
InputStream	toStream() Provides InputStream for the data represented by this BinaryData object.
String	toString() Provides String representation of this BinaryData object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

fromStream

public static BinaryData fromStream(InputStream inputStream)

Creates a BinaryData instance with given InputStream as source of data. The InputStream is not closed by this function.

Create an instance from InputStream

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

Parameters:

inputStream - The InputStream to use as data backing the instance of BinaryData.

Returns:

BinaryData representing the binary data.

Throws:

UncheckedIOException - If any error in reading from InputStream.

NullPointerException - If inputStream is null.

fromStreamAsync

public static Mono<BinaryData> fromStreamAsync(InputStream inputStream)

Asynchronously creates a BinaryData instance with the given InputStream as source of data. The InputStream is not closed by this function. If the InputStream is null, an empty BinaryData will be returned.

Parameters:

inputStream - The InputStream to use as data backing the instance of BinaryData.

Returns:

Mono of BinaryData representing the binary data.

fromFlux

public static Mono<BinaryData> fromFlux(Flux<ByteBuffer> data)

Creates a BinaryData instance with given Flux of ByteBuffer as source of data. It will collect all the bytes from ByteBuffer into BinaryData. If the Flux is null, an empty BinaryData will be returned.

Create an instance from String

 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 byte buffer stream to use as data backing the instance of BinaryData.

Returns:

Mono of BinaryData representing binary data.

fromString

public static BinaryData fromString(String data)

Creates a BinaryData instance with given data. The String is converted into bytes using UTF_8 character set. If the String is null, an empty BinaryData will be returned.

Parameters:

data - The string to use as data backing the instance of BinaryData.

Returns:

BinaryData representing binary data.

fromBytes

public static BinaryData fromBytes(byte[] data)

Creates a BinaryData instance with given byte array data. If the byte array is null, an empty BinaryData will be returned.

Parameters:

data - The byte array to use as data backing the instance of BinaryData.

Returns:

BinaryData representing the binary data.

fromObject

public static BinaryData fromObject(Object data)

Serialize the given Object into BinaryData using json serializer which is available on classpath. The serializer on classpath must implement JsonSerializer interface. If the given Object is null, an empty BinaryData will be returned.

Code sample

 class Person {
     {@literal @}JsonProperty
     private String name;
 
     {@literal @}JsonSetter
     public Person setName(String name) {
         this.name = name;
         return this;
     }
 
     {@literal @}JsonGetter
     public String getName() {
         return name;
     }
 }
 final Person data = new Person().setName("John");
 
 // 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
 BinaryData binaryData = BinaryData.fromObject(data);
 
 

Parameters:

data - The object to use as data backing the instance of BinaryData.

Returns:

BinaryData representing the JSON serialized object.

Throws:

IllegalStateException - If a JsonSerializer cannot be found on the classpath.

See Also:

JsonSerializer, More about serialization

fromObjectAsync

public static Mono<BinaryData> fromObjectAsync(Object data)

Serialize the given Object into BinaryData using json serializer which is available on classpath. The serializer on classpath must implement JsonSerializer interface. If the given Object is null, an empty BinaryData will be returned.

Code sample

 class Person {
     {@literal @}JsonProperty
     private String name;
 
     {@literal @}JsonSetter
     public Person setName(String name) {
         this.name = name;
         return this;
     }
 
     {@literal @}JsonGetter
     public String getName() {
         return name;
     }
 }
 final Person data = new Person().setName("John");
 
 // 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
 BinaryData.fromObjectAsync(data)
     .subscribe(binaryData -> sendToService(binaryData));
 
 

Parameters:

data - The object to use as data backing the instance of BinaryData.

Returns:

BinaryData representing the JSON serialized object.

Throws:

IllegalStateException - If a JsonSerializer cannot be found on the classpath.

See Also:

JsonSerializer, More about serialization

fromObject

public static BinaryData fromObject(Object data,
                                    ObjectSerializer serializer)

Serialize the given Object into BinaryData using the provided ObjectSerializer. If the Object is null, an empty BinaryData will be returned.

You can provide your custom implementation of ObjectSerializer interface or use one provided in Azure SDK by adding them as dependency.

• Jackson serializer
• Gson serializer.

Create an instance from Object

 class Person {
     {@literal @}JsonProperty
     private String name;
 
     {@literal @}JsonSetter
     public Person setName(String name) {
         this.name = name;
         return this;
     }
 
     {@literal @}JsonGetter
     public String getName() {
         return name;
     }
 }
 final Person data = new Person().setName("John");
 
 // 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(data, serializer);
 
 

Parameters:

data - The object to use as data backing the instance of BinaryData.

serializer - to use for serializing the object.

Returns:

BinaryData representing binary data.

Throws:

NullPointerException - If serializer is null.

See Also:

ObjectSerializer, JsonSerializer, More about serialization

fromObjectAsync

public static Mono<BinaryData> fromObjectAsync(Object data,
                                               ObjectSerializer serializer)

Serialize the given Object into Mono BinaryData using the provided ObjectSerializer. If the Object is null, an empty BinaryData will be returned.

You can provide your custom implementation of ObjectSerializer interface or use one provided in zure SDK by adding them as dependency.

• Jackson serializer
• Gson serializer.

Parameters:

data - The object to use as data backing the instance of BinaryData.

serializer - to use for serializing the object.

Returns:

Mono of BinaryData representing the binary data.

Throws:

NullPointerException - If serializer is null.

See Also:

ObjectSerializer, More about serialization

toBytes

public byte[] toBytes()

Provides byte array representation of this BinaryData object.

Returns:

byte array representation of the the data.

toString

public String toString()

Provides String representation of this BinaryData object. The bytes are converted into String using the UTF-8 character set.

Overrides:

toString in class Object

Returns:

String representation of the data.

toObject

public <T> T toObject(TypeReference<T> typeReference,
                      ObjectSerializer serializer)

Deserialize the bytes into the Object of given type by applying the provided ObjectSerializer on the data. The type, represented by TypeReference, can either be a regular class or a generic class that retains the type information.

You can provide your custom implementation of ObjectSerializer interface or use one provided in zure SDK by adding them as dependency.

• Jackson serializer
• Gson serializer.

Code sample to demonstrate serializing and deserializing a regular class

 class Person {
     {@literal @}JsonProperty
     private String name;
 
     {@literal @}JsonSetter
     public Person setName(String name) {
         this.name = name;
         return this;
     }
 
     {@literal @}JsonGetter
     public String getName() {
         return name;
     }
 }
 final Person data = new Person().setName("John");
 
 // 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(data, serializer);
 
 Person person = binaryData.toObject(TypeReference.createInstance(Person.class), serializer);
 System.out.println("Name : " + person.getName());
 
 

Code sample to demonstrate serializing and deserializing generic types

 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 - Generic type that the data is deserialized into.

Parameters:

typeReference - representing the type of the Object.

serializer - to use deserialize data into type.

Returns:

The Object of given type after deserializing the bytes.

Throws:

NullPointerException - If serializer or typeReference is null.

toObjectAsync

public <T> Mono<T> toObjectAsync(TypeReference<T> typeReference,
                                 ObjectSerializer serializer)

Return a Mono by deserializing the bytes into the Object of given type after applying the provided ObjectSerializer on the BinaryData. The type, represented by TypeReference, can either be a regular class or a generic class that retains the type information.

You can provide your custom implementation of ObjectSerializer interface or use one provided in zure SDK by adding them as dependency.

• Jackson serializer
• Gson serializer.

Code sample to demonstrate serializing and deserializing a regular class

 class Person {
     {@literal @}JsonProperty
     private String name;
 
     {@literal @}JsonSetter
     public Person setName(String name) {
         this.name = name;
         return this;
     }
 
     {@literal @}JsonGetter
     public String getName() {
         return name;
     }
 }
 final Person data = new Person().setName("John");
 
 // 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(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();
 

Code sample to demonstrate serializing and deserializing generic types

 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);
 
 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 - Generic type that the data is deserialized into.

Parameters:

typeReference - representing the type of the Object.

serializer - to use deserialize data into type.

Returns:

The Object of given type after deserializing the bytes.

Throws:

NullPointerException - If typeReference or serializer is null.

toObject

public <T> T toObject(TypeReference<T> typeReference)

Deserialize the bytes into the Object of given type by using json serializer which is available in classpath. The type, represented by TypeReference, can either be a regular class or a generic class that retains the type information. This method assumes the data to be in JSON format and will use a default implementation of JsonSerializer.

Code sample to demonstrate serializing and deserializing a regular class

 class Person {
     {@literal @}JsonProperty
     private String name;
 
     {@literal @}JsonSetter
     public Person setName(String name) {
         this.name = name;
         return this;
     }
 
     {@literal @}JsonGetter
     public String getName() {
         return name;
     }
 }
 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://mvnrepository.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://mvnrepository.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());
 

Code sample to demonstrate serializing and deserializing generic types

 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);
 
 List<Person> persons = binaryData.toObject(new TypeReference<List<Person>>() { });
 persons.forEach(person -> System.out.println(person.getName()));
 

Type Parameters:

T - Generic type that the data is deserialized into.

Parameters:

typeReference - representing the type of the Object.

Returns:

The Object of given type after deserializing the bytes.

Throws:

NullPointerException - If typeReference is null.

toObjectAsync

public <T> Mono<T> toObjectAsync(TypeReference<T> typeReference)

Return a Mono by deserializing the bytes into the Object of given type after applying the Json serializer found on classpath. The type, represented by TypeReference, can either be a regular class or a generic class that retains the type information. This method assumes the data to be in JSON format and will use a default implementation of JsonSerializer.

Code sample to demonstrate serializing and deserializing a regular class

 class Person {
     {@literal @}JsonProperty
     private String name;
 
     {@literal @}JsonSetter
     public Person setName(String name) {
         this.name = name;
         return this;
     }
 
     {@literal @}JsonGetter
     public String getName() {
         return name;
     }
 }
 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://mvnrepository.com/artifact/com.azure/azure-core-serializer-json-jackson or
 // https://mvnrepository.com/artifact/com.azure/azure-core-serializer-json-gson
 
 BinaryData binaryData = BinaryData.fromObject(data);
 
 binaryData.toObjectAsync(TypeReference.createInstance(Person.class))
     .subscribe(person -> System.out.println(person.getName()));
 

Code sample to demonstrate serializing and deserializing generic types

 
 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);
 
 binaryData.toObjectAsync(new TypeReference<List<Person>>() { })
     .subscribe(persons -> persons.forEach(person -> System.out.println(person.getName())));
 

Type Parameters:

T - Generic type that the data is deserialized into.

Parameters:

typeReference - representing the type of the Object.

Returns:

The Object of given type after deserializing the bytes.

Throws:

NullPointerException - If typeReference is null.

toStream

public InputStream toStream()

Provides InputStream for the data represented by this BinaryData object.

Get InputStream from BinaryData

 final byte[] data = "Some Data".getBytes(StandardCharsets.UTF_8);
 BinaryData binaryData = BinaryData.fromStream(new ByteArrayInputStream(data));
 final byte[] bytes = new byte[data.length];
 (binaryData.toStream()).read(bytes, 0, data.length);
 System.out.println(new String(bytes));
 

Returns:

InputStream representing the binary data.