org.gridkit.jvmtool.util.json
Interface JsonStreamWriter

All Known Implementing Classes:

JsonWriter, SmartJsonWriter

public interface JsonStreamWriter

This is stripped down version of JsonGenerator.

Author:

Alexey Ragozin (alexey.ragozin@gmail.com)

Method Summary

void	writeArrayFieldStart(String fieldName) Convenience method for outputting a field entry ("member") (that will contain a JSON Array value), and the START_ARRAY marker.
void	writeBoolean(boolean state) Method for outputting literal Json boolean value (one of Strings 'true' and 'false').
void	writeBooleanField(String fieldName, boolean value) Convenience method for outputting a field entry ("member") that has a boolean value.
void	writeEndArray() Method for writing closing marker of a JSON Array value (character ']'; plus possible white space decoration if pretty-printing is enabled).
void	writeEndObject() Method for writing closing marker of a JSON Object value (character '}'; plus possible white space decoration if pretty-printing is enabled).
void	writeFieldName(String name) Method for writing a field name (JSON String surrounded by double quotes: syntactically identical to a JSON String value), possibly decorated by white space if pretty-printing is enabled.
void	writeNull() Method for outputting literal Json null value.
void	writeNullField(String fieldName) Convenience method for outputting a field entry ("member") that has JSON literal value null.
void	writeNumber(BigDecimal dec) Method for outputting indicate Json numeric value.
void	writeNumber(BigInteger v) Method for outputting given value as Json number.
void	writeNumber(double d) Method for outputting indicate Json numeric value.
void	writeNumber(float f) Method for outputting indicate Json numeric value.
void	writeNumber(int v) Method for outputting given value as Json number.
void	writeNumber(long v) Method for outputting given value as Json number.
void	writeNumber(String encodedValue) Write method that can be used for custom numeric types that can not be (easily?) converted to "standard" Java number types.
void	writeNumberField(String fieldName, BigDecimal value) Convenience method for outputting a field entry ("member") that has the specified numeric value.
void	writeNumberField(String fieldName, double value) Convenience method for outputting a field entry ("member") that has the specified numeric value.
void	writeNumberField(String fieldName, float value) Convenience method for outputting a field entry ("member") that has the specified numeric value.
void	writeNumberField(String fieldName, int value) Convenience method for outputting a field entry ("member") that has the specified numeric value.
void	writeNumberField(String fieldName, long value) Convenience method for outputting a field entry ("member") that has the specified numeric value.
void	writeObjectFieldStart(String fieldName) Convenience method for outputting a field entry ("member") (that will contain a JSON Object value), and the START_OBJECT marker.
void	writeRaw(char c) Method that will force generator to copy input text verbatim with no modifications (including that no escaping is done and no separators are added even if context [array, object] would otherwise require such).
void	writeRaw(char[] text, int offset, int len) Method that will force generator to copy input text verbatim with no modifications (including that no escaping is done and no separators are added even if context [array, object] would otherwise require such).
void	writeRaw(String text) Method that will force generator to copy input text verbatim with no modifications (including that no escaping is done and no separators are added even if context [array, object] would otherwise require such).
void	writeRaw(String text, int offset, int len) Method that will force generator to copy input text verbatim with no modifications (including that no escaping is done and no separators are added even if context [array, object] would otherwise require such).
void	writeRawUTF8String(byte[] text, int offset, int length) Method similar to writeString(String) but that takes as its input a UTF-8 encoded String that is to be output as-is, without additional escaping (type of which depends on data format; backslashes for JSON).
void	writeRawValue(char[] text, int offset, int len)
void	writeRawValue(String text) Method that will force generator to copy input text verbatim without any modifications, but assuming it must constitute a single legal JSON value (number, string, boolean, null, Array or List).
void	writeRawValue(String text, int offset, int len)
void	writeStartArray() Method for writing starting marker of a JSON Array value (character '['; plus possible white space decoration if pretty-printing is enabled).
void	writeStartObject() Method for writing starting marker of a JSON Object value (character '{'; plus possible white space decoration if pretty-printing is enabled).
void	writeString(char[] text, int offset, int len) Method for outputting a String value.
void	writeString(String text) Method for outputting a String value.
void	writeStringField(String fieldName, String value) Convenience method for outputting a field entry ("member") that has a String value.
void	writeUTF8String(byte[] text, int offset, int length) Method similar to writeString(String) but that takes as its input a UTF-8 encoded String which has not been escaped using whatever escaping scheme data format requires (for JSON that is backslash-escaping for control characters and double-quotes; for other formats something else).

Method Detail

writeStartArray

void writeStartArray()
                     throws IOException

Method for writing starting marker of a JSON Array value (character '['; plus possible white space decoration if pretty-printing is enabled).

Array values can be written in any context where values are allowed: meaning everywhere except for when a field name is expected.

Throws:

IOException

writeEndArray

void writeEndArray()
                   throws IOException

Method for writing closing marker of a JSON Array value (character ']'; plus possible white space decoration if pretty-printing is enabled).

Marker can be written if the innermost structured type is Array.

Throws:

IOException

writeStartObject

void writeStartObject()
                      throws IOException

Method for writing starting marker of a JSON Object value (character '{'; plus possible white space decoration if pretty-printing is enabled).

Object values can be written in any context where values are allowed: meaning everywhere except for when a field name is expected.

Throws:

IOException

writeEndObject

void writeEndObject()
                    throws IOException

Method for writing closing marker of a JSON Object value (character '}'; plus possible white space decoration if pretty-printing is enabled).

Marker can be written if the innermost structured type is Object, and the last written event was either a complete value, or START-OBJECT marker (see JSON specification for more details).

Throws:

IOException

writeFieldName

void writeFieldName(String name)
                    throws IOException

Method for writing a field name (JSON String surrounded by double quotes: syntactically identical to a JSON String value), possibly decorated by white space if pretty-printing is enabled.

Field names can only be written in Object context (check out JSON specification for details), when field name is expected (field names alternate with values).

Throws:

IOException

writeString

void writeString(String text)
                 throws IOException

Method for outputting a String value. Depending on context this means either array element, (object) field value or a stand alone String; but in all cases, String will be surrounded in double quotes, and contents will be properly escaped as required by JSON specification.

Throws:

IOException

writeString

void writeString(char[] text,
                 int offset,
                 int len)
                 throws IOException

Method for outputting a String value. Depending on context this means either array element, (object) field value or a stand alone String; but in all cases, String will be surrounded in double quotes, and contents will be properly escaped as required by JSON specification.

Throws:

IOException

writeRawUTF8String

void writeRawUTF8String(byte[] text,
                        int offset,
                        int length)
                        throws IOException

Method similar to writeString(String) but that takes as its input a UTF-8 encoded String that is to be output as-is, without additional escaping (type of which depends on data format; backslashes for JSON). However, quoting that data format requires (like double-quotes for JSON) will be added around the value if and as necessary.

Note that some backends may choose not to support this method: for example, if underlying destination is a Writer using this method would require UTF-8 decoding. If so, implementation may instead choose to throw a UnsupportedOperationException due to ineffectiveness of having to decode input.

Throws:

IOException

Since:

1.7

writeUTF8String

void writeUTF8String(byte[] text,
                     int offset,
                     int length)
                     throws IOException

Method similar to writeString(String) but that takes as its input a UTF-8 encoded String which has not been escaped using whatever escaping scheme data format requires (for JSON that is backslash-escaping for control characters and double-quotes; for other formats something else). This means that textual JSON backends need to check if value needs JSON escaping, but otherwise can just be copied as is to output. Also, quoting that data format requires (like double-quotes for JSON) will be added around the value if and as necessary.

Note that some backends may choose not to support this method: for example, if underlying destination is a Writer using this method would require UTF-8 decoding. In this case generator implementation may instead choose to throw a UnsupportedOperationException due to ineffectiveness of having to decode input.

Throws:

IOException

Since:

1.7

writeRaw

void writeRaw(String text)
              throws IOException

Method that will force generator to copy input text verbatim with no modifications (including that no escaping is done and no separators are added even if context [array, object] would otherwise require such). If such separators are desired, use writeRawValue(String) instead.

Note that not all generator implementations necessarily support such by-pass methods: those that do not will throw UnsupportedOperationException.

Throws:

IOException

writeRaw

void writeRaw(String text,
              int offset,
              int len)
              throws IOException

Method that will force generator to copy input text verbatim with no modifications (including that no escaping is done and no separators are added even if context [array, object] would otherwise require such). If such separators are desired, use writeRawValue(String) instead.

Note that not all generator implementations necessarily support such by-pass methods: those that do not will throw UnsupportedOperationException.

Throws:

IOException

writeRaw

void writeRaw(char[] text,
              int offset,
              int len)
              throws IOException

Method that will force generator to copy input text verbatim with no modifications (including that no escaping is done and no separators are added even if context [array, object] would otherwise require such). If such separators are desired, use writeRawValue(String) instead.

Note that not all generator implementations necessarily support such by-pass methods: those that do not will throw UnsupportedOperationException.

Throws:

IOException

writeRaw

void writeRaw(char c)
              throws IOException

Method that will force generator to copy input text verbatim with no modifications (including that no escaping is done and no separators are added even if context [array, object] would otherwise require such). If such separators are desired, use writeRawValue(String) instead.

Note that not all generator implementations necessarily support such by-pass methods: those that do not will throw UnsupportedOperationException.

Throws:

IOException

writeRawValue

void writeRawValue(String text)
                   throws IOException

Method that will force generator to copy input text verbatim without any modifications, but assuming it must constitute a single legal JSON value (number, string, boolean, null, Array or List). Assuming this, proper separators are added if and as needed (comma or colon), and generator state updated to reflect this.

Throws:

IOException

writeRawValue

void writeRawValue(String text,
                   int offset,
                   int len)
                   throws IOException

Throws:

IOException

writeRawValue

void writeRawValue(char[] text,
                   int offset,
                   int len)
                   throws IOException

Throws:

IOException

writeNumber

void writeNumber(int v)
                 throws IOException

Method for outputting given value as Json number. Can be called in any context where a value is expected (Array value, Object field value, root-level value). Additional white space may be added around the value if pretty-printing is enabled.

Throws:

IOException

writeNumber

void writeNumber(long v)
                 throws IOException

Method for outputting given value as Json number. Can be called in any context where a value is expected (Array value, Object field value, root-level value). Additional white space may be added around the value if pretty-printing is enabled.

Throws:

IOException

writeNumber

void writeNumber(BigInteger v)
                 throws IOException

Method for outputting given value as Json number. Can be called in any context where a value is expected (Array value, Object field value, root-level value). Additional white space may be added around the value if pretty-printing is enabled.

Throws:

IOException

writeNumber

void writeNumber(double d)
                 throws IOException

Method for outputting indicate Json numeric value. Can be called in any context where a value is expected (Array value, Object field value, root-level value). Additional white space may be added around the value if pretty-printing is enabled.

Throws:

IOException

writeNumber

void writeNumber(float f)
                 throws IOException

Method for outputting indicate Json numeric value. Can be called in any context where a value is expected (Array value, Object field value, root-level value). Additional white space may be added around the value if pretty-printing is enabled.

Throws:

IOException

writeNumber

void writeNumber(BigDecimal dec)
                 throws IOException

Method for outputting indicate Json numeric value. Can be called in any context where a value is expected (Array value, Object field value, root-level value). Additional white space may be added around the value if pretty-printing is enabled.

Throws:

IOException

writeNumber

void writeNumber(String encodedValue)
                 throws IOException,
                        UnsupportedOperationException

Write method that can be used for custom numeric types that can not be (easily?) converted to "standard" Java number types. Because numbers are not surrounded by double quotes, regular writeString(java.lang.String) method can not be used; nor writeRaw(java.lang.String) because that does not properly handle value separators needed in Array or Object contexts.

Note: because of lack of type safety, some generator implementations may not be able to implement this method. For example, if a binary json format is used, it may require type information for encoding; similarly for generator-wrappers around Java objects or Json nodes. If implementation does not implement this method, it needs to throw UnsupportedOperationException.

Throws:

IOException

UnsupportedOperationException

writeBoolean

void writeBoolean(boolean state)
                  throws IOException

Method for outputting literal Json boolean value (one of Strings 'true' and 'false'). Can be called in any context where a value is expected (Array value, Object field value, root-level value). Additional white space may be added around the value if pretty-printing is enabled.

Throws:

IOException

writeNull

void writeNull()
               throws IOException

Method for outputting literal Json null value. Can be called in any context where a value is expected (Array value, Object field value, root-level value). Additional white space may be added around the value if pretty-printing is enabled.

Throws:

IOException

writeStringField

void writeStringField(String fieldName,
                      String value)
                      throws IOException

Convenience method for outputting a field entry ("member") that has a String value. Equivalent to:

  writeFieldName(fieldName);
  writeString(value);

Note: many performance-sensitive implementations override this method

Throws:

IOException

writeBooleanField

void writeBooleanField(String fieldName,
                       boolean value)
                       throws IOException

Convenience method for outputting a field entry ("member") that has a boolean value. Equivalent to:

  writeFieldName(fieldName);
  writeBoolean(value);

Throws:

IOException

writeNullField

void writeNullField(String fieldName)
                    throws IOException

Convenience method for outputting a field entry ("member") that has JSON literal value null. Equivalent to:

  writeFieldName(fieldName);
  writeNull();

Throws:

IOException

writeNumberField

void writeNumberField(String fieldName,
                      int value)
                      throws IOException

Convenience method for outputting a field entry ("member") that has the specified numeric value. Equivalent to:

  writeFieldName(fieldName);
  writeNumber(value);

Throws:

IOException

writeNumberField

void writeNumberField(String fieldName,
                      long value)
                      throws IOException

Convenience method for outputting a field entry ("member") that has the specified numeric value. Equivalent to:

  writeFieldName(fieldName);
  writeNumber(value);

Throws:

IOException

writeNumberField

void writeNumberField(String fieldName,
                      double value)
                      throws IOException

Convenience method for outputting a field entry ("member") that has the specified numeric value. Equivalent to:

  writeFieldName(fieldName);
  writeNumber(value);

Throws:

IOException

writeNumberField

void writeNumberField(String fieldName,
                      float value)
                      throws IOException

Convenience method for outputting a field entry ("member") that has the specified numeric value. Equivalent to:

  writeFieldName(fieldName);
  writeNumber(value);

Throws:

IOException

writeNumberField

void writeNumberField(String fieldName,
                      BigDecimal value)
                      throws IOException

Convenience method for outputting a field entry ("member") that has the specified numeric value. Equivalent to:

  writeFieldName(fieldName);
  writeNumber(value);

Throws:

IOException

writeArrayFieldStart

void writeArrayFieldStart(String fieldName)
                          throws IOException

Convenience method for outputting a field entry ("member") (that will contain a JSON Array value), and the START_ARRAY marker. Equivalent to:

  writeFieldName(fieldName);
  writeStartArray();

Note: caller still has to take care to close the array (by calling {#link #writeEndArray}) after writing all values of the value Array.

Throws:

IOException

writeObjectFieldStart

void writeObjectFieldStart(String fieldName)
                           throws IOException

Convenience method for outputting a field entry ("member") (that will contain a JSON Object value), and the START_OBJECT marker. Equivalent to:

  writeFieldName(fieldName);
  writeStartObject();

Note: caller still has to take care to close the Object (by calling {#link #writeEndObject}) after writing all entries of the value Object.

Throws:

IOException