Package com.unboundid.util.json

Class JSONBuffer

  • All Implemented Interfaces:
    java.io.Serializable
    @Mutable
@ThreadSafety(level=NOT_THREADSAFE)
public final class JSONBuffer
extends java.lang.Object
implements java.io.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:
    Serialized Form

    • 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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void appendBoolean​(boolean value)
      Appends the provided Boolean value.
      void appendBoolean​(java.lang.String fieldName, boolean value)
      Appends a JSON field with the specified name and the provided Boolean value.
      void appendNull()
      Appends the provided JSON null value.
      void appendNull​(java.lang.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​(java.lang.String value)
      Appends the provided JSON number value.
      void appendNumber​(java.lang.String fieldName, int value)
      Appends a JSON field with the specified name and a number value.
      void appendNumber​(java.lang.String fieldName, long value)
      Appends a JSON field with the specified name and a number value.
      void appendNumber​(java.lang.String fieldName, java.lang.String value)
      Appends a JSON field with the specified name and a number value.
      void appendNumber​(java.lang.String fieldName, java.math.BigDecimal value)
      Appends a JSON field with the specified name and a number value.
      void appendNumber​(java.math.BigDecimal value)
      Appends the provided JSON number value.
      void appendString​(java.lang.String value)
      Appends the provided JSON string value.
      void appendString​(java.lang.String fieldName, java.lang.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​(java.lang.String fieldName, JSONValue value)
      Appends the provided JSON value.
      void beginArray()
      Appends the open curly brace needed to signify the beginning of a JSON array.
      void beginArray​(java.lang.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​(java.lang.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.
      java.lang.String toString()
      Retrieves a string representation of the current contents of this JSON buffer.
      void writeTo​(java.io.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

    • Constructor Detail

      • 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​(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 Detail

      • clear

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

      • setBuffer

        public void setBuffer​(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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.math.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​(java.lang.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​(java.lang.String fieldName,
                         java.math.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​(java.lang.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​(java.lang.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​(java.lang.String fieldName,
                         java.lang.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​(java.lang.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​(java.lang.String fieldName,
                         java.lang.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​(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​(java.lang.String fieldName,
                        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:
        fieldName - The name of the field.
        value - The value to append.

      • getBuffer

        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​(java.io.OutputStream outputStream)
             throws java.io.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:
        java.io.IOException - If a problem is encountered while writing to the provided output stream.

      • toString

        public java.lang.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 java.lang.Object
        Returns:
        A string representation of the current contents of this JSON buffer.

      • toJSONObject

        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.