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

JSONBuffer()
Creates a new instance of this JSON buffer with the default maximum buffer 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.

JSONBuffer(int maxBufferSize)
Creates a new instance of this JSON buffer with an optional maximum retained size.

Method Summary

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(java.math.BigDecimal value) Appends the provided JSON number 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, java.math.BigDecimal value) Appends a JSON field with the specified name and a 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	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.