Interface JsonWriter

  • All Implemented Interfaces:

    @DoNotImplement() 
    public interface JsonWriter
    
                        

    An interface to a creator of Json. Part of the support to add custom serializer support to the JsonMarshallingService. Custom serializers are passed a JsonWriter in order they can translate their object types to Json.

    When writing arrays and objects, methods which denote the start and end are provided, which should enclose calls to write any content within those arrays or objects. The root of the Json being serialized should always start with a call to writeStartObject and end with a call to writeEndObject. Arrays of course can only contain values, not fields. Objects must contain fields and values. Separators between objects, arrays, and array items are automatically added.

    When fields and values are written with either two method calls or the single methods which take a field name and value parameter, the separators and enclosing double quotation marks are added automatically. The JsonWriter will throw if you attempt to write values without field names, the exception being the writeRaw methods which dump whatever you pass directly into the Json output unchanged. To write raw content with validation instead call one of the writeRawValue methods, which will assume whatever is passed is a valid Json value.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
    • Field Summary

      Fields 
      Modifier and Type Field Description
    • Constructor Summary

      Constructors 
      Constructor Description
    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description
    • Method Summary

      Modifier and Type Method Description
      abstract void writeStartObject() Writes the marker denoting the start of an object.
      abstract void writeEndObject() Writes the marker denoting the end of an object.
      abstract void writeFieldName(@NotNull() String fieldName) Writes a field name surrounded by double quotes.
      abstract void writeString(@NotNull() Array<char> c, int offset, int len) Writes a string value.
      abstract void writeString(@NotNull() String text) Writes a string value.
      abstract void writeStringField(@NotNull() String fieldName, @NotNull() String text) Writes a field name and a string value.
      abstract void writeNumber(@NotNull() BigDecimal v) Writes a number value.
      abstract void writeNumber(@NotNull() BigInteger v) Writes a number value.
      abstract void writeNumber(double v) Writes a number value.
      abstract void writeNumber(float v) Writes a number value.
      abstract void writeNumber(int v) Writes a number value.
      abstract void writeNumber(long v) Writes a number value.
      abstract void writeNumber(short v) Writes a number value.
      abstract void writeNumberField(@NotNull() String fieldName, @NotNull() BigDecimal v) Writes a field name and a number value.
      abstract void writeNumberField(@NotNull() String fieldName, double v) Writes a field name and a number value.
      abstract void writeNumberField(@NotNull() String fieldName, float v) Writes a field name and a number value.
      abstract void writeNumberField(@NotNull() String fieldName, int v) Writes a field name and a number value.
      abstract void writeNumberField(@NotNull() String fieldName, long v) Writes a field name and a number value.
      abstract void writeObject(@NotNull() Object pojo) Writes a Java Object (POJO) as a Json (object) value via the usual means that object type would be serialized.
      abstract void writeObjectField(@NotNull() String fieldName, @NotNull() Object pojo) Writes a field name and Java Object (POJO) as a Json (object) value via the usual means that object type would be serialized.
      abstract void writeObjectFieldStart(@NotNull() String fieldName) Writes a field that will contain a Json object value, including the marker denoting the beginning of an object.
      abstract void writeBoolean(boolean state) Writes a boolean value, denoted in Json as either 'true' or 'false' strings.
      abstract void writeBooleanField(@NotNull() String fieldName, boolean state) Writes a field name and boolean value, denoted in Json as either 'true' or 'false' strings.
      abstract void writeArrayFieldStart(@NotNull() String fieldName) Writes a field that will contain a Json Array value, including the marker denoting the beginning of an array.
      abstract void writeStartArray() Writes a marker denoting the beginning of an array.
      abstract void writeEndArray() Writes the marker denoting the end of an array.
      abstract void writeArray(@NotNull() Array<int> array, int offset, int len) Writes an entire array including the start and end marker, so do not try to start or end an array around this method call.
      abstract void writeArray(@NotNull() Array<long> array, int offset, int len) Writes an entire array including the start and end marker, so do not try to start or end an array around this method call.
      abstract void writeArray(@NotNull() Array<double> array, int offset, int len) Writes an entire array including the start and end marker, so do not try to start or end an array around this method call.
      abstract void writeArray(@NotNull() Array<String> array, int offset, int len) Writes an entire array including the start and end marker, so do not try to start or end an array around this method call.
      abstract void writeBinary(@NotNull() JsonSerializedBase64Config config, @NotNull() Array<byte> data, int offset, int len) Writes a base64 encoded binary chunk value (surrounded by double quotes).
      abstract void writeBinary(@NotNull() JsonSerializedBase64Config config, @NotNull() InputStream data, int len) Writes a base64 encoded binary chunk value (surrounded by double quotes).
      abstract void writeBinary(@NotNull() Array<byte> data) Writes a base64 encoded binary chunk value (surrounded by double quotes).
      abstract void writeBinary(@NotNull() Array<byte> data, int offset, int len) Writes a base64 encoded binary chunk value (surrounded by double quotes).
      abstract void writeBinary(@NotNull() InputStream data, int len) Writes a base64 encoded binary chunk value (surrounded by double quotes).
      abstract void writeBinaryField(@NotNull() String fieldName, @NotNull() Array<byte> data) Writes a field name and base64 encoded binary chunk value (surrounded by double quotes).
      abstract void writeNull() Writes a Json null value.
      abstract void writeNullField(@NotNull() String fieldName) Writes a field name and Json null value.
      abstract void writeRaw(char c) Writes raw data directly to the Json output unchanged.
      abstract void writeRaw(@NotNull() Array<char> c, int offset, int len) Writes raw data directly to the Json output unchanged.
      abstract void writeRaw(@NotNull() String text) Writes raw data directly to the Json output unchanged.
      abstract void writeRaw(@NotNull() String text, int offset, int len) Writes raw data directly to the Json output unchanged.
      abstract void writeRawValue(@NotNull() Array<char> c, int offset, int len) Writes raw data directly to the Json output unchanged.
      abstract void writeRawValue(@NotNull() String text) Writes raw data directly to the Json output unchanged.
      abstract void writeRawValue(@NotNull() String text, int offset, int len) Writes raw data directly to the Json output unchanged.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

    • Method Detail

      • writeStartObject

         abstract void writeStartObject()

        Writes the marker denoting the start of an object.

      • writeEndObject

         abstract void writeEndObject()

        Writes the marker denoting the end of an object.

      • writeFieldName

         abstract void writeFieldName(@NotNull() String fieldName)

        Writes a field name surrounded by double quotes.

        Parameters:
        fieldName - The name of the field.
      • writeString

         abstract void writeString(@NotNull() Array<char> c, int offset, int len)

        Writes a string value.

        Parameters:
        c - The char array to write.
        offset - The offset into the char array to begin writing from.
        len - The length of data to write.
      • writeString

         abstract void writeString(@NotNull() String text)

        Writes a string value.

        Parameters:
        text - The string to write.
      • writeStringField

         abstract void writeStringField(@NotNull() String fieldName, @NotNull() String text)

        Writes a field name and a string value.

        Parameters:
        fieldName - The name of the field.
        text - The string to write.
      • writeNumber

         abstract void writeNumber(@NotNull() BigDecimal v)

        Writes a number value.

        Parameters:
        v - The number.
      • writeNumber

         abstract void writeNumber(@NotNull() BigInteger v)

        Writes a number value.

        Parameters:
        v - The number.
      • writeNumber

         abstract void writeNumber(double v)

        Writes a number value.

        Parameters:
        v - The number.
      • writeNumber

         abstract void writeNumber(float v)

        Writes a number value.

        Parameters:
        v - The number.
      • writeNumber

         abstract void writeNumber(int v)

        Writes a number value.

        Parameters:
        v - The number.
      • writeNumber

         abstract void writeNumber(long v)

        Writes a number value.

        Parameters:
        v - The number.
      • writeNumber

         abstract void writeNumber(short v)

        Writes a number value.

        Parameters:
        v - The number.
      • writeNumberField

         abstract void writeNumberField(@NotNull() String fieldName, @NotNull() BigDecimal v)

        Writes a field name and a number value.

        Parameters:
        fieldName - The name of the field.
        v - The number.
      • writeNumberField

         abstract void writeNumberField(@NotNull() String fieldName, double v)

        Writes a field name and a number value.

        Parameters:
        fieldName - The name of the field.
        v - The number.
      • writeNumberField

         abstract void writeNumberField(@NotNull() String fieldName, float v)

        Writes a field name and a number value.

        Parameters:
        fieldName - The name of the field.
        v - The number.
      • writeNumberField

         abstract void writeNumberField(@NotNull() String fieldName, int v)

        Writes a field name and a number value.

        Parameters:
        fieldName - The name of the field.
        v - The number.
      • writeNumberField

         abstract void writeNumberField(@NotNull() String fieldName, long v)

        Writes a field name and a number value.

        Parameters:
        fieldName - The name of the field.
        v - The number.
      • writeObject

         abstract void writeObject(@NotNull() Object pojo)

        Writes a Java Object (POJO) as a Json (object) value via the usual means that object type would be serialized. This means it will call any custom serializer registered for that type, otherwise it will write the object as-is into Json format.

        Parameters:
        pojo - The Java object.
      • writeObjectField

         abstract void writeObjectField(@NotNull() String fieldName, @NotNull() Object pojo)

        Writes a field name and Java Object (POJO) as a Json (object) value via the usual means that object type would be serialized.

        Parameters:
        fieldName - The name of the field.
        pojo - The Java object.
      • writeObjectFieldStart

         abstract void writeObjectFieldStart(@NotNull() String fieldName)

        Writes a field that will contain a Json object value, including the marker denoting the beginning of an object.

        Parameters:
        fieldName - The name of the field.
      • writeBoolean

         abstract void writeBoolean(boolean state)

        Writes a boolean value, denoted in Json as either 'true' or 'false' strings.

        Parameters:
        state - The boolean state.
      • writeBooleanField

         abstract void writeBooleanField(@NotNull() String fieldName, boolean state)

        Writes a field name and boolean value, denoted in Json as either 'true' or 'false' strings.

        Parameters:
        fieldName - The name of the field.
        state - The boolean state.
      • writeArrayFieldStart

         abstract void writeArrayFieldStart(@NotNull() String fieldName)

        Writes a field that will contain a Json Array value, including the marker denoting the beginning of an array.

        Parameters:
        fieldName - The name of the field.
      • writeStartArray

         abstract void writeStartArray()

        Writes a marker denoting the beginning of an array.

      • writeEndArray

         abstract void writeEndArray()

        Writes the marker denoting the end of an array.

      • writeArray

         abstract void writeArray(@NotNull() Array<int> array, int offset, int len)

        Writes an entire array including the start and end marker, so do not try to start or end an array around this method call.

        Parameters:
        array - The array to write.
        offset - The offset into the array to begin writing from.
        len - The number of items to write.
      • writeArray

         abstract void writeArray(@NotNull() Array<long> array, int offset, int len)

        Writes an entire array including the start and end marker, so do not try to start or end an array around this method call.

        Parameters:
        array - The array to write.
        offset - The offset into the array to begin writing from.
        len - The number of items to write.
      • writeArray

         abstract void writeArray(@NotNull() Array<double> array, int offset, int len)

        Writes an entire array including the start and end marker, so do not try to start or end an array around this method call.

        Parameters:
        array - The array to write.
        offset - The offset into the array to begin writing from.
        len - The number of items to write.
      • writeArray

         abstract void writeArray(@NotNull() Array<String> array, int offset, int len)

        Writes an entire array including the start and end marker, so do not try to start or end an array around this method call.

        Parameters:
        array - The array to write.
        offset - The offset into the array to begin writing from.
        len - The number of items to write.
      • writeBinary

         abstract void writeBinary(@NotNull() JsonSerializedBase64Config config, @NotNull() Array<byte> data, int offset, int len)

        Writes a base64 encoded binary chunk value (surrounded by double quotes).

        Parameters:
        config - A configuration option which determines how the base64 string is written into the Json.
        data - The data to base64 encode and write into Json.
        offset - The offset into the data to begin encoding from.
        len - The length of data to encode.
      • writeBinary

         abstract void writeBinary(@NotNull() JsonSerializedBase64Config config, @NotNull() InputStream data, int len)

        Writes a base64 encoded binary chunk value (surrounded by double quotes).

        Parameters:
        config - A configuration option which determines how the base64 string is written into the Json.
        data - The data to base64 encode and write into Json.
        len - The length of data to encode.
      • writeBinary

         abstract void writeBinary(@NotNull() Array<byte> data)

        Writes a base64 encoded binary chunk value (surrounded by double quotes). Uses configuration {@lonk JsonSerializedBase64Config#MIME_NO_LINEFEEDS}.

        Parameters:
        data - The data to base64 encode and write into Json.
      • writeBinary

         abstract void writeBinary(@NotNull() Array<byte> data, int offset, int len)

        Writes a base64 encoded binary chunk value (surrounded by double quotes). Uses configuration MIME_NO_LINEFEEDS.

        Parameters:
        data - The data to base64 encode and write into Json.
        offset - The offset into the data to begin encoding at.
        len - The length of data to encode.
      • writeBinary

         abstract void writeBinary(@NotNull() InputStream data, int len)

        Writes a base64 encoded binary chunk value (surrounded by double quotes). Uses configuration MIME_NO_LINEFEEDS.

        Parameters:
        data - The data to base64 encode and write into Json.
        len - The length of data to encode.
      • writeBinaryField

         abstract void writeBinaryField(@NotNull() String fieldName, @NotNull() Array<byte> data)

        Writes a field name and base64 encoded binary chunk value (surrounded by double quotes).

        Parameters:
        fieldName - The name of the field.
        data - The data to base64 encode and write into Json.
      • writeNull

         abstract void writeNull()

        Writes a Json null value.

      • writeNullField

         abstract void writeNullField(@NotNull() String fieldName)

        Writes a field name and Json null value.

        Parameters:
        fieldName - The name of the field.
      • writeRaw

         abstract void writeRaw(char c)

        Writes raw data directly to the Json output unchanged. This method does not make assumptions about whether the data is intended to be a field or value, it does not add any separators or escaping, nor does it require that the Json output that results is valid Json.

        Note that writeRaw methods do not change the context of the jsonWriter, so the field and value including the opening field separator (a common if a field has come before it) must all be written explicitly to create valid Json. A closing separator (a common before the next field if there is one) need not be written as that is written by the next call to write a field name against the JsonWriter. To write only a raw value consider using the writeRawValue methods instead as they do change context and handle the separators and enclosing double quotes like any other value writing methods.

        Parameters:
        c - The char to write.
      • writeRaw

         abstract void writeRaw(@NotNull() Array<char> c, int offset, int len)

        Writes raw data directly to the Json output unchanged. This method does not make assumptions about whether the data is intended to be a field or value, it does not add any separators or escaping, nor does it require that the Json output that results is valid Json.

        Note that writeRaw methods do not change the context of the jsonWriter, so the field and value including the opening field separator (a common if a field has come before it) must all be written explicitly to create valid Json. A closing separator (a common before the next field if there is one) need not be written as that is written by the next call to write a field name against the JsonWriter. To write only a raw value consider using the writeRawValue methods instead as they do change context and handle the separators and enclosing double quotes like any other value writing methods.

        Parameters:
        c - The char array to write.
        offset - The offset into the char array to begin writing from.
        len - The length of data to write.
      • writeRaw

         abstract void writeRaw(@NotNull() String text)

        Writes raw data directly to the Json output unchanged. This method does not make assumptions about whether the data is intended to be a field or value, it does not add any separators or escaping, nor does it require that the Json output that results is valid Json.

        Note that writeRaw methods do not change the context of the jsonWriter, so the field and value including the opening field separator (a common if a field has come before it) must all be written explicitly to create valid Json. A closing separator (a common before the next field if there is one) need not be written as that is written by the next call to write a field name against the JsonWriter. To write only a raw value consider using the writeRawValue methods instead as they do change context and handle the separators and enclosing double quotes like any other value writing methods.

        Parameters:
        text - The string to write.
      • writeRaw

         abstract void writeRaw(@NotNull() String text, int offset, int len)

        Writes raw data directly to the Json output unchanged. This method does not make assumptions about whether the data is intended to be a field or value, it does not add any separators or escaping, nor does it require that the Json output that results is valid Json.

        Note that writeRaw methods do not change the context of the jsonWriter, so the field and value including the opening field separator (a common if a field has come before it) must all be written explicitly to create valid Json. A closing separator (a common before the next field if there is one) need not be written as that is written by the next call to write a field name against the JsonWriter. To write only a raw value consider using the writeRawValue methods instead as they do change context and handle the separators and enclosing double quotes like any other value writing methods.

        Parameters:
        text - The string to write.
        offset - The offset into the text to begin writing from.
        len - The length of data to write.
      • writeRawValue

         abstract void writeRawValue(@NotNull() Array<char> c, int offset, int len)

        Writes raw data directly to the Json output unchanged. This method requires the data to be a valid Json value. That can be a simple Json value, or a complete array or object. Like any other 'value' method on the JsonWriter (but unlike the non-value raw methods) the required separators are added around the value in the Json output and the context (field followed by value repeated) in this JsonWriter is preserved correctly by this method. As such the JsonWriter is ready to have the next field written after a call to this method. Enclosing double quotation marks are not added unless part of the raw data passed by the caller.

        Parameters:
        c - The char array to write.
        offset - The offset into the char array to begin writing from.
        len - The length of data to write.
      • writeRawValue

         abstract void writeRawValue(@NotNull() String text)

        Writes raw data directly to the Json output unchanged. This method requires the data to be a valid Json value. That can be a simple Json value, or a complete array or object. Like any other 'value' method on the JsonWriter (but unlike the non-value raw methods) the required separators are added around the value in the Json output and the context (field followed by value repeated) in this JsonWriter is preserved correctly by this method. As such the JsonWriter is ready to have the next field written after a call to this method. Enclosing double quotation marks are not added unless part of the raw data passed by the caller.

        Parameters:
        text - The string to write.
      • writeRawValue

         abstract void writeRawValue(@NotNull() String text, int offset, int len)

        Writes raw data directly to the Json output unchanged. This method requires the data to be a valid Json value. That can be a simple Json value, or a complete array or object. Like any other 'value' method on the JsonWriter (but unlike the non-value raw methods) the required separators are added around the value in the Json output and the context (field followed by value repeated) in this JsonWriter is preserved correctly by this method. As such the JsonWriter is ready to have the next field written after a call to this method. Enclosing double quotation marks are not added unless part of the raw data passed by the caller.

        Parameters:
        text - The string to write.
        offset - The offset into the text to begin writing from.
        len - The length of data to write.