Package com.azure.json

Interface JsonSerializable<T extends JsonSerializable<T>>

Type Parameters:
T - The type of the object that is JSON serializable.
All Known Implementing Classes:
JsonArray, JsonBoolean, JsonElement, JsonNull, JsonNumber, JsonObject, JsonString
public interface JsonSerializable<T extends JsonSerializable<T>>
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 JsonToken.FIELD_NAME for the object. So, for objects calling out to other JsonSerializable objects for deserialization, they'll pass the reader pointing to the token after the JsonToken.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.

See Also:

  • Method Details

    • toJson

      JsonWriter toJson(JsonWriter jsonWriter) throws IOException
      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 objects for serialization, they'll write the field name only then pass the JsonWriter to the other JsonSerializable 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

      default void toJson(OutputStream outputStream) throws IOException
      Convenience method for writing the JsonSerializable 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

      default void toJson(Writer writer) throws IOException
      Convenience method for writing the JsonSerializable 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.

    • toJsonString

      default String toJsonString() throws IOException
      Convenience method for writing the JsonSerializable to a JSON string.
      Returns:
      The JSON string representing the object.
      Throws:
      IOException - If the object fails to be written as a JSON string.

    • toJsonBytes

      default byte[] toJsonBytes() throws IOException
      Convenience method for writing the JsonSerializable to a byte array.
      Returns:
      The byte array representing the object.
      Throws:
      IOException - If the object fails to be written as a byte array.

    • fromJson

      static <T extends JsonSerializable<T>> T fromJson(JsonReader jsonReader) throws IOException
      Reads a JSON stream into an object.

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

      Type Parameters:
      T - The type of the object.
      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

      static <T extends JsonSerializable<T>> T fromJson(String string) throws IOException
      Convenience method for reading a JSON string into an object.
      Type Parameters:
      T - The type of the 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.

    • fromJson

      static <T extends JsonSerializable<T>> T fromJson(byte[] bytes) throws IOException
      Convenience method for reading a JSON byte array into an object.
      Type Parameters:
      T - The type of the 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

      static <T extends JsonSerializable<T>> T fromJson(InputStream inputStream) throws IOException
      Convenience method for reading a JSON InputStream into an object.
      Type Parameters:
      T - The type of the 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

      static <T extends JsonSerializable<T>> T fromJson(Reader reader) throws IOException
      Convenience method for reading a JSON Reader into an object.
      Type Parameters:
      T - The type of the 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.