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