Package com.unboundid.util.json

Class JSONBuffer

java.lang.Object
com.unboundid.util.json.JSONBuffer
All Implemented Interfaces:
Serializable
@Mutable @ThreadSafety(level=NOT_THREADSAFE) public final class JSONBuffer extends Object implements Serializable
This class provides a mechanism for constructing the string representation of one or more JSON objects by appending elements of those objects into a byte string buffer. JSONBuffer instances may be cleared and reused any number of times. They are not threadsafe and should not be accessed concurrently by multiple threads.

Note that the caller is responsible for proper usage to ensure that the buffer results in a valid JSON encoding. This includes ensuring that the object begins with the appropriate opening curly brace, that all objects and arrays are properly closed, that raw values are not used outside of arrays, that named fields are not added into arrays, etc.
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_MAX_BUFFER_SIZE
    The default maximum buffer size.

  • Constructor Summary

    Constructors
    Constructor
    Description
    JSONBuffer()
    Creates a new instance of this JSON buffer with the default maximum buffer size.
    JSONBuffer(int maxBufferSize)
    Creates a new instance of this JSON buffer with an optional maximum retained size.
    JSONBuffer(ByteStringBuffer buffer, int maxBufferSize, boolean multiLine)
    Creates a new instance of this JSON buffer that wraps the provided byte string buffer (if provided) and that has an optional maximum retained size.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    appendBoolean(boolean value)
    Appends the provided Boolean value.
    void
    appendBoolean(String fieldName, boolean value)
    Appends a JSON field with the specified name and the provided Boolean value.
    void
    appendField(JSONField field)
    Appends the provided JSON field.
    void
    appendNull()
    Appends the provided JSON null value.
    void
    appendNull(String fieldName)
    Appends a JSON field with the specified name and a null value.
    void
    appendNumber(int value)
    Appends the provided JSON number value.
    void
    appendNumber(long value)
    Appends the provided JSON number value.
    void
    appendNumber(String value)
    Appends the provided JSON number value.
    void
    appendNumber(String fieldName, int value)
    Appends a JSON field with the specified name and a number value.
    void
    appendNumber(String fieldName, long value)
    Appends a JSON field with the specified name and a number value.
    void
    appendNumber(String fieldName, String value)
    Appends a JSON field with the specified name and a number value.
    void
    appendNumber(String fieldName, BigDecimal value)
    Appends a JSON field with the specified name and a number value.
    void
    appendNumber(BigDecimal value)
    Appends the provided JSON number value.
    void
    appendString(String value)
    Appends the provided JSON string value.
    void
    appendString(String fieldName, String value)
    Appends a JSON field with the specified name and a null value.
    void
    appendValue(JSONValue value)
    Appends the provided JSON value.
    void
    appendValue(String fieldName, JSONValue value)
    Appends a field with the given name and value.
    void
    beginArray()
    Appends the open curly brace needed to signify the beginning of a JSON array.
    void
    beginArray(String fieldName)
    Begins a new JSON array that will be used as the value of the specified field.
    void
    beginObject()
    Appends the open curly brace needed to signify the beginning of a JSON object.
    void
    beginObject(String fieldName)
    Begins a new JSON object that will be used as the value of the specified field.
    void
    clear()
    Clears the contents of this buffer.
    void
    endArray()
    Appends the close square bracket needed to signify the end of a JSON array.
    void
    endObject()
    Appends the close curly brace needed to signify the end of a JSON object.
    ByteStringBuffer
    getBuffer()
    Retrieves the byte string buffer that backs this JSON buffer.
    int
    length()
    Retrieves the current length of this buffer in bytes.
    void
    setBuffer(ByteStringBuffer buffer)
    Replaces the underlying buffer to which the JSON object data will be written.
    JSONObject
    toJSONObject()
    Retrieves the current contents of this JSON buffer as a JSON object.
    String
    toString()
    Retrieves a string representation of the current contents of this JSON buffer.
    void
    writeTo(OutputStream outputStream)
    Writes the current contents of this JSON buffer to the provided output stream.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

  • Constructor Details

    • JSONBuffer

      public JSONBuffer()
      Creates a new instance of this JSON buffer with the default maximum buffer size.

    • JSONBuffer

      public JSONBuffer(int maxBufferSize)
      Creates a new instance of this JSON buffer with an optional maximum retained size. If a maximum size is defined, then this buffer may be used to hold elements larger than that, but when the buffer is cleared it will be shrunk to the maximum size.
      Parameters:
      maxBufferSize - The maximum buffer size that will be retained by this JSON buffer. A value less than or equal to zero indicates that no maximum size should be enforced.

    • JSONBuffer

      public JSONBuffer(@Nullable ByteStringBuffer buffer, int maxBufferSize, boolean multiLine)
      Creates a new instance of this JSON buffer that wraps the provided byte string buffer (if provided) and that has an optional maximum retained size. If a maximum size is defined, then this buffer may be used to hold elements larger than that, but when the buffer is cleared it will be shrunk to the maximum size.
      Parameters:
      buffer - The buffer to wrap. It may be null if a new buffer should be created.
      maxBufferSize - The maximum buffer size that will be retained by this JSON buffer. A value less than or equal to zero indicates that no maximum size should be enforced.
      multiLine - Indicates whether to format JSON objects using a user-friendly, formatted, multi-line representation rather than constructing the entire element without any line breaks. Note that regardless of the value of this argument, there will not be an end-of-line marker at the very end of the object.

  • Method Details

    • clear

      public void clear()
      Clears the contents of this buffer.

    • setBuffer

      public void setBuffer(@Nullable ByteStringBuffer buffer)
      Replaces the underlying buffer to which the JSON object data will be written.
      Parameters:
      buffer - The underlying buffer to which the JSON object data will be written.

    • length

      public int length()
      Retrieves the current length of this buffer in bytes.
      Returns:
      The current length of this buffer in bytes.

    • beginObject

      public void beginObject()
      Appends the open curly brace needed to signify the beginning of a JSON object. This will not include a field name, so it should only be used to start the outermost JSON object, or to start a JSON object contained in an array.

    • beginObject

      public void beginObject(@NotNull String fieldName)
      Begins a new JSON object that will be used as the value of the specified field.
      Parameters:
      fieldName - The name of the field

    • endObject

      public void endObject()
      Appends the close curly brace needed to signify the end of a JSON object.

    • beginArray

      public void beginArray()
      Appends the open curly brace needed to signify the beginning of a JSON array. This will not include a field name, so it should only be used to start a JSON array contained in an array.

    • beginArray

      public void beginArray(@NotNull String fieldName)
      Begins a new JSON array that will be used as the value of the specified field.
      Parameters:
      fieldName - The name of the field

    • endArray

      public void endArray()
      Appends the close square bracket needed to signify the end of a JSON array.

    • appendBoolean

      public void appendBoolean(boolean value)
      Appends the provided Boolean value. This will not include a field name, so it should only be used for Boolean value elements in an array.
      Parameters:
      value - The Boolean value to append.

    • appendBoolean

      public void appendBoolean(@NotNull String fieldName, boolean value)
      Appends a JSON field with the specified name and the provided Boolean value.
      Parameters:
      fieldName - The name of the field.
      value - The Boolean value.

    • appendNull

      public void appendNull()
      Appends the provided JSON null value. This will not include a field name, so it should only be used for null value elements in an array.

    • appendNull

      public void appendNull(@NotNull String fieldName)
      Appends a JSON field with the specified name and a null value.
      Parameters:
      fieldName - The name of the field.

    • appendNumber

      public void appendNumber(@NotNull BigDecimal value)
      Appends the provided JSON number value. This will not include a field name, so it should only be used for number elements in an array.
      Parameters:
      value - The number to add.

    • appendNumber

      public void appendNumber(int value)
      Appends the provided JSON number value. This will not include a field name, so it should only be used for number elements in an array.
      Parameters:
      value - The number to add.

    • appendNumber

      public void appendNumber(long value)
      Appends the provided JSON number value. This will not include a field name, so it should only be used for number elements in an array.
      Parameters:
      value - The number to add.

    • appendNumber

      public void appendNumber(@NotNull String value)
      Appends the provided JSON number value. This will not include a field name, so it should only be used for number elements in an array.
      Parameters:
      value - The string representation of the number to add. It must be properly formed.

    • appendNumber

      public void appendNumber(@NotNull String fieldName, @NotNull BigDecimal value)
      Appends a JSON field with the specified name and a number value.
      Parameters:
      fieldName - The name of the field.
      value - The number value.

    • appendNumber

      public void appendNumber(@NotNull String fieldName, int value)
      Appends a JSON field with the specified name and a number value.
      Parameters:
      fieldName - The name of the field.
      value - The number value.

    • appendNumber

      public void appendNumber(@NotNull String fieldName, long value)
      Appends a JSON field with the specified name and a number value.
      Parameters:
      fieldName - The name of the field.
      value - The number value.

    • appendNumber

      public void appendNumber(@NotNull String fieldName, @NotNull String value)
      Appends a JSON field with the specified name and a number value.
      Parameters:
      fieldName - The name of the field.
      value - The string representation of the number ot add. It must be properly formed.

    • appendString

      public void appendString(@NotNull String value)
      Appends the provided JSON string value. This will not include a field name, so it should only be used for string elements in an array.
      Parameters:
      value - The value to add.

    • appendString

      public void appendString(@NotNull String fieldName, @NotNull String value)
      Appends a JSON field with the specified name and a null value.
      Parameters:
      fieldName - The name of the field.
      value - The value to add.

    • appendValue

      public void appendValue(@NotNull JSONValue value)
      Appends the provided JSON value. This will not include a field name, so it should only be used for elements in an array.
      Parameters:
      value - The value to append.

    • appendValue

      public void appendValue(@NotNull String fieldName, @NotNull JSONValue value)
      Appends a field with the given name and value.
      Parameters:
      fieldName - The name of the field.
      value - The value to append.

    • appendField

      public void appendField(@NotNull JSONField field)
      Appends the provided JSON field.
      Parameters:
      field - The JSON field to be appended.

    • getBuffer

      @NotNull public ByteStringBuffer getBuffer()
      Retrieves the byte string buffer that backs this JSON buffer.
      Returns:
      The byte string buffer that backs this JSON buffer.

    • writeTo

      public void writeTo(@NotNull OutputStream outputStream) throws IOException
      Writes the current contents of this JSON buffer to the provided output stream. Note that based on the current contents of this buffer and the way it has been used so far, it may not represent a valid JSON object.
      Parameters:
      outputStream - The output stream to which the current contents of this JSON buffer should be written.
      Throws:
      IOException - If a problem is encountered while writing to the provided output stream.

    • toString

      @NotNull public String toString()
      Retrieves a string representation of the current contents of this JSON buffer. Note that based on the current contents of this buffer and the way it has been used so far, it may not represent a valid JSON object.
      Overrides:
      toString in class Object
      Returns:
      A string representation of the current contents of this JSON buffer.

    • toJSONObject

      @NotNull public JSONObject toJSONObject() throws JSONException
      Retrieves the current contents of this JSON buffer as a JSON object.
      Returns:
      The JSON object decoded from the contents of this JSON buffer.
      Throws:
      JSONException - If the buffer does not currently contain exactly one valid JSON object.