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

Field Summary

Fields

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

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and 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	appendField(JSONField field) Appends the provided JSON field.
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 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(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

Field Detail

DEFAULT_MAX_BUFFER_SIZE

public static final int DEFAULT_MAX_BUFFER_SIZE

The default maximum buffer size.

See Also:

Constant Field Values

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(@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 Detail

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
                        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(@NotNull
                       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(@NotNull
                          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(@NotNull
                       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(@NotNull
                         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(@NotNull
                         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(@NotNull
                         java.lang.String fieldName,
                         @NotNull
                         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(@NotNull
                         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(@NotNull
                         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(@NotNull
                         java.lang.String fieldName,
                         @NotNull
                         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(@NotNull
                         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(@NotNull
                         java.lang.String fieldName,
                         @NotNull
                         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(@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
                        java.lang.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
                    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

@NotNull
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

@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.