Package com.unboundid.util.json
Class JSONBuffer
- java.lang.Object
-
- com.unboundid.util.json.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.
-
-
-
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 benull
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 classjava.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.
-
-