Class BinaryData
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.toString());
Create an instance from an Object
class Person { @JsonProperty private String name; @JsonSetter public Person setName(String name) { this.name = name; return this; } @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); System.out.println(binaryData.toString());
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));
-
Method Summary
Modifier and TypeMethodDescriptionstatic BinaryData
fromByteBuffer
(ByteBuffer data) Creates an instance ofBinaryData
from the givenByteBuffer
.static BinaryData
fromBytes
(byte[] data) Creates an instance ofBinaryData
from the given byte array.static BinaryData
Creates aBinaryData
that uses the content of the file atPath
as its data.static BinaryData
Creates aBinaryData
that uses the content of the file atfile
as its data.static BinaryData
Creates aBinaryData
that uses the content of the file atfile
as its data.static BinaryData
Creates aBinaryData
that uses the content of the file atfile
as its data.static Mono<BinaryData>
fromFlux
(Flux<ByteBuffer> data) static Mono<BinaryData>
fromFlux
(Flux<ByteBuffer> data, Long length) static Mono<BinaryData>
fromFlux
(Flux<ByteBuffer> data, Long length, boolean bufferContent) static BinaryData
fromListByteBuffer
(List<ByteBuffer> data) static BinaryData
fromObject
(Object data) static BinaryData
fromObject
(Object data, ObjectSerializer serializer) static Mono<BinaryData>
fromObjectAsync
(Object data) static Mono<BinaryData>
fromObjectAsync
(Object data, ObjectSerializer serializer) static BinaryData
fromStream
(InputStream inputStream) Creates an instance ofBinaryData
from the givenInputStream
.static BinaryData
fromStream
(InputStream inputStream, Long length) Creates an instance ofBinaryData
from the givenInputStream
.static Mono<BinaryData>
fromStreamAsync
(InputStream inputStream) Creates an instance ofBinaryData
from the givenInputStream
.static Mono<BinaryData>
fromStreamAsync
(InputStream inputStream, Long length) Creates an instance ofBinaryData
from the givenInputStream
.static BinaryData
fromString
(String data) Creates an instance ofBinaryData
from the givenString
.Returns the length of the content, if it is known.boolean
Returns a flag indicating whether the content can be repeatedly consumed using all accessors includingtoStream()
andtoFluxByteBuffer()
Returns a read-onlyByteBuffer
representation of thisBinaryData
.byte[]
toBytes()
Returns a byte array representation of thisBinaryData
.Returns the content of thisBinaryData
instance as a flux ofByteBuffers
.<T> T
toObject
(TypeReference<T> typeReference) Returns anObject
representation of thisBinaryData
by deserializing its data using the defaultJsonSerializer
.<T> T
toObject
(TypeReference<T> typeReference, ObjectSerializer serializer) Returns anObject
representation of thisBinaryData
by deserializing its data using the passedObjectSerializer
.<T> T
Returns anObject
representation of thisBinaryData
by deserializing its data using the defaultJsonSerializer
.<T> T
toObject
(Class<T> clazz, ObjectSerializer serializer) Returns anObject
representation of thisBinaryData
by deserializing its data using the passedObjectSerializer
.<T> Mono<T>
toObjectAsync
(TypeReference<T> typeReference) Returns anObject
representation of thisBinaryData
by deserializing its data using the defaultJsonSerializer
.<T> Mono<T>
toObjectAsync
(TypeReference<T> typeReference, ObjectSerializer serializer) Returns anObject
representation of thisBinaryData
by deserializing its data using the passedObjectSerializer
.<T> Mono<T>
toObjectAsync
(Class<T> clazz) Returns anObject
representation of thisBinaryData
by deserializing its data using the defaultJsonSerializer
.<T> Mono<T>
toObjectAsync
(Class<T> clazz, ObjectSerializer serializer) Returns anObject
representation of thisBinaryData
by deserializing its data using the passedObjectSerializer
.Converts theBinaryData
into aBinaryData
that is replayable, i.e.Converts theBinaryData
into aBinaryData
that is replayable, i.e.toStream()
Returns anInputStream
representation of thisBinaryData
.toString()
Returns aString
representation of thisBinaryData
by converting its data using the UTF-8 character set.
-
Method Details
-
fromStream
Creates an instance ofBinaryData
from the givenInputStream
. 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.toString());
- Parameters:
inputStream
- TheInputStream
thatBinaryData
will represent.- Returns:
- A
BinaryData
representing theInputStream
. - Throws:
UncheckedIOException
- If any error happens while reading theInputStream
.NullPointerException
- IfinputStream
is null.
-
fromStream
Creates an instance ofBinaryData
from the givenInputStream
. 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.toString());
- Parameters:
inputStream
- TheInputStream
thatBinaryData
will represent.length
- The length ofdata
in bytes.- Returns:
- A
BinaryData
representing theInputStream
. - Throws:
UncheckedIOException
- If any error happens while reading theInputStream
.NullPointerException
- IfinputStream
is null.
-
fromStreamAsync
Creates an instance ofBinaryData
from the givenInputStream
. NOTE: TheInputStream
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
- TheInputStream
thatBinaryData
will represent.- Returns:
- A
Mono
ofBinaryData
representing theInputStream
. - Throws:
UncheckedIOException
- If any error happens while reading theInputStream
.NullPointerException
- IfinputStream
is null.
-
fromStreamAsync
Creates an instance ofBinaryData
from the givenInputStream
. NOTE: TheInputStream
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
- TheInputStream
thatBinaryData
will represent.length
- The length ofdata
in bytes.- Returns:
- A
Mono
ofBinaryData
representing theInputStream
. - Throws:
UncheckedIOException
- If any error happens while reading theInputStream
.NullPointerException
- IfinputStream
is null.
-
fromFlux
Creates an instance ofBinaryData
from the givenFlux
ofByteBuffer
.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
- TheFlux
ofByteBuffer
thatBinaryData
will represent.- Returns:
- A
Mono
ofBinaryData
representing theFlux
ofByteBuffer
. - Throws:
NullPointerException
- Ifdata
is null.
-
fromFlux
Creates an instance ofBinaryData
from the givenFlux
ofByteBuffer
.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
- TheFlux
ofByteBuffer
thatBinaryData
will represent.length
- The length ofdata
in bytes.- Returns:
- A
Mono
ofBinaryData
representing theFlux
ofByteBuffer
. - Throws:
IllegalArgumentException
- if the length is less than zero.NullPointerException
- ifdata
is null.
-
fromFlux
Creates an instance ofBinaryData
from the givenFlux
ofByteBuffer
.If
bufferContent
is true andlength
is null the length of the returnedBinaryData
will be based on the length calculated by buffering. Iflength
is non-null it will always be used as theBinaryData
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
- TheFlux
ofByteBuffer
thatBinaryData
will represent.length
- The length ofdata
in bytes.bufferContent
- A flag indicating whetherFlux
should be buffered eagerly or consumption deferred.- Returns:
- A
Mono
ofBinaryData
representing theFlux
ofByteBuffer
. - Throws:
IllegalArgumentException
- if the length is less than zero.NullPointerException
- ifdata
is null.
-
fromString
Creates an instance ofBinaryData
from the givenString
.The
String
is converted into bytes usingString.getBytes(Charset)
passingStandardCharsets.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
- TheString
thatBinaryData
will represent.- Returns:
- A
BinaryData
representing theString
. - Throws:
NullPointerException
- Ifdata
is null.
-
fromBytes
Creates an instance ofBinaryData
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 ofBinaryData
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 thatBinaryData
will represent.- Returns:
- A
BinaryData
representing the byte array. - Throws:
NullPointerException
- Ifdata
is null.
-
fromByteBuffer
Creates an instance ofBinaryData
from the givenByteBuffer
.If the
ByteBuffer
is zero length an emptyBinaryData
will be returned. Note that the inputByteBuffer
is used as a reference by this instance ofBinaryData
and any changes to theByteBuffer
outside of this instance will result in the contents of this BinaryData instance being updated as well. To safely update theByteBuffer
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
- TheByteBuffer
thatBinaryData
will represent.- Returns:
- A
BinaryData
representing theByteBuffer
. - Throws:
NullPointerException
- Ifdata
is null.
-
fromListByteBuffer
Creates an instance ofBinaryData
from the givenList
ofByteBuffer
.The input
ByteBuffer
instances are used as a reference by this instance ofBinaryData
and any changes to aByteBuffer
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
- TheList
ofByteBuffer
thatBinaryData
will represent.- Returns:
- A
BinaryData
representing theList
ofByteBuffer
.
-
fromObject
Creates an instance ofBinaryData
by serializing theObject
using the defaultJsonSerializer
.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
class Person { @JsonProperty private String name; @JsonSetter public Person setName(String name) { this.name = name; return this; } @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); System.out.println(binaryData.toString());
- Parameters:
data
- The object that will be JSON serialized thatBinaryData
will represent.- Returns:
- A
BinaryData
representing the JSON serialized object. - Throws:
NullPointerException
- Ifdata
is null.- See Also:
-
fromObjectAsync
Creates an instance ofBinaryData
by serializing theObject
using the defaultJsonSerializer
.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
class Person { @JsonProperty private String name; @JsonSetter public Person setName(String name) { this.name = name; return this; } @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 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 thatBinaryData
will represent.- Returns:
- A
Mono
ofBinaryData
representing the JSON serialized object. - See Also:
-
fromObject
Creates an instance ofBinaryData
by serializing theObject
using the passedObjectSerializer
.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
class Person { @JsonProperty private String name; @JsonSetter public Person setName(String name) { this.name = name; return this; } @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); System.out.println(binaryData.toString());
- Parameters:
data
- The object that will be serialized thatBinaryData
will represent. Theserializer
determines hownull
data is serialized.serializer
- TheObjectSerializer
used to serialize object.- Returns:
- A
BinaryData
representing the serialized object. - Throws:
NullPointerException
- Ifserializer
is null.- See Also:
-
fromObjectAsync
Creates an instance ofBinaryData
by serializing theObject
using the passedObjectSerializer
.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
class Person { @JsonProperty private String name; @JsonSetter public Person setName(String name) { this.name = name; return this; } @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 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 thatBinaryData
will represent. Theserializer
determines hownull
data is serialized.serializer
- TheObjectSerializer
used to serialize object.- Returns:
- A
Mono
ofBinaryData
representing the serialized object. - Throws:
NullPointerException
- Ifserializer
is null.- See Also:
-
fromFile
Creates aBinaryData
that uses the content of the file atPath
as its data. This method checks for the existence of the file at the time of creating an instance ofBinaryData
. 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
- ThePath
that will be theBinaryData
data.- Returns:
- A new
BinaryData
. - Throws:
NullPointerException
- Iffile
is null.
-
fromFile
Creates aBinaryData
that uses the content of the file atfile
as its data. This method checks for the existence of the file at the time of creating an instance ofBinaryData
. 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
- ThePath
that will be theBinaryData
data.chunkSize
- The requested size for each read of the path.- Returns:
- A new
BinaryData
. - Throws:
NullPointerException
- Iffile
is null.IllegalArgumentException
- Ifoffset
orlength
are negative oroffset
pluslength
is greater than the file size orchunkSize
is less than or equal to 0.UncheckedIOException
- if the file does not exist.
-
fromFile
Creates aBinaryData
that uses the content of the file atfile
as its data. This method checks for the existence of the file at the time of creating an instance ofBinaryData
. 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
- ThePath
that will be theBinaryData
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
- Iffile
is null.IllegalArgumentException
- Ifoffset
orlength
are negative oroffset
pluslength
is greater than the file size orchunkSize
is less than or equal to 0.UncheckedIOException
- if the file does not exist.
-
fromFile
Creates aBinaryData
that uses the content of the file atfile
as its data. This method checks for the existence of the file at the time of creating an instance ofBinaryData
. 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
- ThePath
that will be theBinaryData
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
- Iffile
is null.IllegalArgumentException
- Ifoffset
orlength
are negative oroffset
pluslength
is greater than the file size orchunkSize
is less than or equal to 0.UncheckedIOException
- if the file does not exist.
-
toBytes
public byte[] toBytes()Returns a byte array representation of thisBinaryData
.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 aFlux<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 abyte[]
this will throw anIllegalStateException
.- Returns:
- A byte array representing this
BinaryData
. - Throws:
IllegalStateException
- If theBinaryData
is larger than the maximum size allowed for abyte[]
.
-
toString
Returns aString
representation of thisBinaryData
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 aString
this will throw anIllegalStateException
.- Overrides:
toString
in classObject
- Returns:
- A
String
representing thisBinaryData
. - Throws:
IllegalStateException
- If theBinaryData
is larger than the maximum size allowed for aString
.
-
toObject
Returns anObject
representation of thisBinaryData
by deserializing its data using the defaultJsonSerializer
. Each time this method is called, the content is deserialized and a new instance of typeT
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 usetoObject(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
class Person { @JsonProperty private String name; @JsonSetter public Person setName(String name) { this.name = name; return this; } @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(Person.class); System.out.println(person.getName());
- Type Parameters:
T
- Type of the deserialized Object.- Parameters:
clazz
- TheClass
representing the Object's type.- Returns:
- An
Object
representing the JSON deserializedBinaryData
. - Throws:
NullPointerException
- Ifclazz
is null.- See Also:
-
toObject
Returns anObject
representation of thisBinaryData
by deserializing its data using the defaultJsonSerializer
. Each time this method is called, the content is deserialized and a new instance of typeT
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 ofTypeReference
, if the type is non-generic useTypeReference.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
class Person { @JsonProperty private String name; @JsonSetter public Person setName(String name) { this.name = name; return this; } @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());
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://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(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
- TheTypeReference
representing the Object's type.- Returns:
- An
Object
representing the JSON deserializedBinaryData
. - Throws:
NullPointerException
- IftypeReference
is null.- See Also:
-
toObject
Returns anObject
representation of thisBinaryData
by deserializing its data using the passedObjectSerializer
. Each time this method is called, the content is deserialized and a new instance of typeT
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 usetoObject(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
class Person { @JsonProperty private String name; @JsonSetter public Person setName(String name) { this.name = name; return this; } @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(Person.class, serializer); System.out.println("Name : " + person.getName());
- Type Parameters:
T
- Type of the deserialized Object.- Parameters:
clazz
- TheClass
representing the Object's type.serializer
- TheObjectSerializer
used to deserialize object.- Returns:
- An
Object
representing the deserializedBinaryData
. - Throws:
NullPointerException
- Ifclazz
orserializer
is null.- See Also:
-
toObject
Returns anObject
representation of thisBinaryData
by deserializing its data using the passedObjectSerializer
. Each time this method is called, the content is deserialized and a new instance of typeT
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 ofTypeReference
, if the type is non-generic useTypeReference.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
class Person { @JsonProperty private String name; @JsonSetter public Person setName(String name) { this.name = name; return this; } @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());
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
- TheTypeReference
representing the Object's type.serializer
- TheObjectSerializer
used to deserialize object.- Returns:
- An
Object
representing the deserializedBinaryData
. - Throws:
NullPointerException
- IftypeReference
orserializer
is null.- See Also:
-
toObjectAsync
Returns anObject
representation of thisBinaryData
by deserializing its data using the defaultJsonSerializer
. Each time this method is called, the content is deserialized and a new instance of typeT
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 usetoObject(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
class Person { @JsonProperty private String name; @JsonSetter public Person setName(String name) { this.name = name; return this; } @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); 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
- TheClass
representing the Object's type.- Returns:
- A
Mono
ofObject
representing the JSON deserializedBinaryData
. - Throws:
NullPointerException
- Ifclazz
is null.- See Also:
-
toObjectAsync
Returns anObject
representation of thisBinaryData
by deserializing its data using the defaultJsonSerializer
. Each time this method is called, the content is deserialized and a new instance of typeT
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 ofTypeReference
, if the type is non-generic useTypeReference.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
class Person { @JsonProperty private String name; @JsonSetter public Person setName(String name) { this.name = name; return this; } @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); 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
- TheTypeReference
representing the Object's type.- Returns:
- A
Mono
ofObject
representing the JSON deserializedBinaryData
. - Throws:
NullPointerException
- IftypeReference
is null.- See Also:
-
toObjectAsync
Returns anObject
representation of thisBinaryData
by deserializing its data using the passedObjectSerializer
. Each time this method is called, the content is deserialized and a new instance of typeT
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 usetoObject(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
class Person { @JsonProperty private String name; @JsonSetter public Person setName(String name) { this.name = name; return this; } @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(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
- TheClass
representing the Object's type.serializer
- TheObjectSerializer
used to deserialize object.- Returns:
- A
Mono
ofObject
representing the deserializedBinaryData
. - Throws:
NullPointerException
- Ifclazz
orserializer
is null.- See Also:
-
toObjectAsync
Returns anObject
representation of thisBinaryData
by deserializing its data using the passedObjectSerializer
. Each time this method is called, the content is deserialized and a new instance of typeT
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 ofTypeReference
, if the type is non-generic useTypeReference.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
class Person { @JsonProperty private String name; @JsonSetter public Person setName(String name) { this.name = name; return this; } @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();
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); 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
- TheTypeReference
representing the Object's type.serializer
- TheObjectSerializer
used to deserialize object.- Returns:
- A
Mono
ofObject
representing the deserializedBinaryData
. - Throws:
NullPointerException
- IftypeReference
orserializer
is null.- See Also:
-
toStream
Returns anInputStream
representation of thisBinaryData
.Get an InputStream from the 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:
- An
InputStream
representing theBinaryData
.
-
toByteBuffer
Returns a read-onlyByteBuffer
representation of thisBinaryData
.Attempting to mutate the returned
ByteBuffer
will throw aReadOnlyBufferException
.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 theBinaryData
.
-
toFluxByteBuffer
Returns the content of thisBinaryData
instance as a flux ofByteBuffers
. The content is not read from the underlying data source until theFlux
is subscribed to.- Returns:
- the content of this
BinaryData
instance as a flux ofByteBuffers
.
-
getLength
Returns the length of the content, if it is known. The length can benull
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 includingtoStream()
andtoFluxByteBuffer()
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(() -> 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
Converts theBinaryData
into aBinaryData
that is replayable, i.e. content can be consumed repeatedly using all accessors includingtoStream()
andtoFluxByteBuffer()
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
Converts theBinaryData
into aBinaryData
that is replayable, i.e. content can be consumed repeatedly using all accessors includingtoStream()
andtoFluxByteBuffer()
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(() -> 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
ofBinaryData
representing the replayableBinaryData
.
-