JsonSerializable<T> Interface

Package:

com.azure.json

Maven Artifact:

com.azure:azure-json:1.3.0

Type Parameters

T

The type of the object that is JSON serializable.

public interface JsonSerializable

Indicates that the implementing class can be serialized to and deserialized from JSON.

Since deserialization needs to work without an instance of the class, implementing this interface it's assumed the class has a static method fromJson(JsonReader) that deserializes an instance of that class. The contract for reading JSON from JsonReader is that the initial state of the reader on call will either be a null JsonToken or be the JsonToken after the FIELD_NAME for the object. So, for objects calling out to other JsonSerializable<T> objects for deserialization, they'll pass the reader pointing to the token after the FIELD_NAME. This way objects reading JSON will be self-encapsulated for reading properly formatted JSON. And, if an error occurs during deserialization an IllegalStateException should be thrown.

Method Summary

Modifier and Type	Method and Description
static T	fromJson(byte[] bytes) Convenience method for reading a JSON byte array into an object.
static T	fromJson(JsonReader jsonReader) Reads a JSON stream into an object.
static T	fromJson(InputStream inputStream) Convenience method for reading a JSON InputStream into an object.
static T	fromJson(Reader reader) Convenience method for reading a JSON Reader into an object.
static T	fromJson(String string) Convenience method for reading a JSON string into an object.
abstract JsonWriter	toJson(JsonWriter jsonWriter) Writes the object to the passed JsonWriter.
default void	toJson(OutputStream outputStream) Convenience method for writing the JsonSerializable<T> to the passed OutputStream.
default void	toJson(Writer writer) Convenience method for writing the JsonSerializable<T> to the passed Writer.
default byte[]	toJsonBytes() Convenience method for writing the JsonSerializable<T> to a byte array.
default String	toJsonString() Convenience method for writing the JsonSerializable<T> to a JSON string.

Method Details

fromJson

public static T fromJson(byte[] bytes)

Convenience method for reading a JSON byte array into an object.

Parameters:

bytes - The JSON byte array to read.

Returns:

The object that the JSON byte array represented, may return null.

Throws:

IOException

- If an object fails to be read from the bytes.

fromJson

public static T fromJson(JsonReader jsonReader)

Reads a JSON stream into an object.

Implementations of JsonSerializable<T> must define this method, otherwise an UnsupportedOperationException will be thrown.

Parameters:

jsonReader - The JsonReader being read.

Returns:

The object that the JSON stream represented, may return null.

Throws:

IOException

- If an object fails to be read from the jsonReader.

fromJson

public static T fromJson(InputStream inputStream)

Convenience method for reading a JSON InputStream into an object.

Parameters:

inputStream - The JSON InputStream to read.

Returns:

The object that the JSON InputStream represented, may return null.

Throws:

IOException

- If an object fails to be read from the inputStream.

fromJson

public static T fromJson(Reader reader)

Convenience method for reading a JSON Reader into an object.

Parameters:

reader - The JSON Reader to read.

Returns:

The object that the JSON Reader represented, may return null.

Throws:

IOException

- If an object fails to be read from the reader.

fromJson

public static T fromJson(String string)

Convenience method for reading a JSON string into an object.

Parameters:

string - The JSON string to read.

Returns:

The object that the JSON string represented, may return null.

Throws:

IOException

- If an object fails to be read from the string.

toJson

public abstract JsonWriter toJson(JsonWriter jsonWriter)

Writes the object to the passed JsonWriter.

The contract for writing JSON to JsonWriter is that the object being written will handle opening and closing its own JSON object. So, for objects calling out to other JsonSerializable<T> objects for serialization, they'll write the field name only then pass the JsonWriter to the other JsonSerializable<T> object. This way objects writing JSON will be self-encapsulated for writing properly formatted JSON.

Parameters:

jsonWriter - Where the object's JSON will be written.

Returns:

The JsonWriter where the JSON was written.

Throws:

IOException

- If the object fails to be written to the jsonWriter.

toJson

public default void toJson(OutputStream outputStream)

Convenience method for writing the JsonSerializable<T> to the passed OutputStream.

Parameters:

outputStream - The OutputStream to write the JSON to.

Throws:

IOException

- If the object fails to be written to the outputStream.

toJson

public default void toJson(Writer writer)

Convenience method for writing the JsonSerializable<T> to the passed Writer.

Parameters:

writer - The Writer to write the JSON to.

Throws:

IOException

- If the object fails to be written to the writer.

toJsonBytes

public default byte[] toJsonBytes()

Convenience method for writing the JsonSerializable<T> to a byte array.

Returns:

The byte array representing the object.

Throws:

IOException

- If the object fails to be written as a byte array.

toJsonString

public default String toJsonString()

Convenience method for writing the JsonSerializable<T> to a JSON string.

Returns:

The JSON string representing the object.

Throws:

IOException

- If the object fails to be written as a JSON string.