com.unboundid.util.json
Class JSONArray

java.lang.Object
  com.unboundid.util.json.JSONValue
      com.unboundid.util.json.JSONArray

All Implemented Interfaces:

java.io.Serializable

@NotMutable
@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class JSONArray
extends JSONValue

This class provides an implementation of a JSON value that represents an ordered collection of zero or more values. An array can contain elements of any type, including a mix of types, and including nested arrays. The same value may appear multiple times in an array.

The string representation of a JSON array is an open square bracket (U+005B) followed by a comma-delimited list of the string representations of the values in that array and a closing square bracket (U+005D). There must not be a comma between the last item in the array and the closing square bracket. There may optionally be any amount of whitespace (where whitespace characters include the ASCII space, horizontal tab, line feed, and carriage return characters) after the open square bracket, on either or both sides of commas separating values, and before the close square bracket.

The string representation returned by the toString() method (or appended to the buffer provided to the toString(StringBuilder) method) will include one space before each value in the array and one space before the closing square bracket. There will not be any space between a value and the comma that follows it. The string representation of each value in the array will be obtained using that value's toString method.

The normalized string representation will not include any optional spaces, and the normalized string representation of each value in the array will be obtained using that value's toNormalizedString method.

See Also:

Serialized Form

Field Summary

static JSONArray

EMPTY_ARRAY A pre-allocated empty JSON array.

Constructor Summary

JSONArray(JSONValue... values)
Creates a new JSON array with the provided values.

JSONArray(java.util.List<? extends JSONValue> values)
Creates a new JSON array with the provided values.

Method Summary

void	appendToJSONBuffer(JSONBuffer buffer) Appends this value to the provided JSON buffer.
void	appendToJSONBuffer(java.lang.String fieldName, JSONBuffer buffer) Appends a field with the given name and this value to the provided JSON buffer.
boolean	contains(JSONValue value, boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder, boolean recursive) Indicates whether this JSON array contains an element with the specified value.
boolean	equals(JSONArray array, boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder) Indicates whether this JSON array is considered equivalent to the provided array, subject to the specified constraints.
boolean	equals(JSONValue v, boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder) Indicates whether this JSON value is considered equal to the provided JSON value, subject to the specified constraints.
boolean	equals(java.lang.Object o) Indicates whether the provided object is equal to this JSON value.
java.util.List<JSONValue>	getValues() Retrieves the set of values contained in this JSON array.
int	hashCode() Retrieves a hash code for this JSON value.
boolean	isEmpty() Indicates whether this array is empty.
int	size() Retrieves the number of values contained in this array.
java.lang.String	toNormalizedString() Retrieves a normalized string representation of this value.
void	toNormalizedString(java.lang.StringBuilder buffer) Appends a normalized string representation of this value to the provided buffer.
java.lang.String	toSingleLineString() Retrieves a single-line string representation of this value as it should appear in a JSON object, including any necessary quoting, escaping, etc.
void	toSingleLineString(java.lang.StringBuilder buffer) Appends a single-line string representation of this value (as it should appear in a JSON object, including any necessary quoting, escaping, etc.) to the provided buffer.
java.lang.String	toString() Retrieves a string representation of this value as it should appear in a JSON object, including any necessary quoting, escaping, etc.
void	toString(java.lang.StringBuilder buffer) Appends a string representation of this value (as it should appear in a JSON object, including any necessary quoting, escaping, etc.) to the provided buffer.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY_ARRAY

public static final JSONArray EMPTY_ARRAY

A pre-allocated empty JSON array.

Constructor Detail

JSONArray

public JSONArray(JSONValue... values)

Creates a new JSON array with the provided values.

Parameters:

values - The set of values to include in this JSON array. It may be null or empty to indicate that the array should be empty.

JSONArray

public JSONArray(java.util.List<? extends JSONValue> values)

Creates a new JSON array with the provided values.

Parameters:

values - The set of values to include in this JSON array. It may be null or empty to indicate that the array should be empty.

Method Detail

getValues

public java.util.List<JSONValue> getValues()

Retrieves the set of values contained in this JSON array.

Returns:

The set of values contained in this JSON array.

isEmpty

public boolean isEmpty()

Indicates whether this array is empty.

Returns:

true if this array does not contain any values, or false if this array contains at least one value.

size

public int size()

Retrieves the number of values contained in this array.

Returns:

The number of values contained in this array.

hashCode

public int hashCode()

Retrieves a hash code for this JSON value.

Specified by:

hashCode in class JSONValue

Returns:

The hash code for this JSON value.

equals

public boolean equals(java.lang.Object o)

Indicates whether the provided object is equal to this JSON value.

Specified by:

equals in class JSONValue

Parameters:

o - The object to compare against this JSON value.

Returns:

true if the provided object is considered equal to this JSON value, or false if not.

equals

public boolean equals(JSONArray array,
                      boolean ignoreFieldNameCase,
                      boolean ignoreValueCase,
                      boolean ignoreArrayOrder)

Indicates whether this JSON array is considered equivalent to the provided array, subject to the specified constraints.

Parameters:

array - The array for which to make the determination.

ignoreFieldNameCase - Indicates whether to ignore differences in capitalization in field names for any JSON objects contained in the array.

ignoreValueCase - Indicates whether to ignore differences in capitalization for array elements that are JSON strings, as well as for the string values of any JSON objects and arrays contained in the array.

ignoreArrayOrder - Indicates whether to ignore differences in the order of elements contained in the array.

Returns:

true if this JSON array is considered equivalent to the provided array (subject to the specified constraints), or false if not.

equals

public boolean equals(JSONValue v,
                      boolean ignoreFieldNameCase,
                      boolean ignoreValueCase,
                      boolean ignoreArrayOrder)

Indicates whether this JSON value is considered equal to the provided JSON value, subject to the specified constraints. Note that not all constraints will apply to all data types.

Specified by:

equals in class JSONValue

Parameters:

v - The JSON value for which to make the determination. It must not be null.

ignoreFieldNameCase - Indicates whether to ignore differences in the capitalization of JSON field names.

ignoreValueCase - Indicates whether to ignore differences in the capitalization of JSON values that represent strings.

ignoreArrayOrder - Indicates whether to ignore differences in the order of elements in JSON arrays.

Returns:

true if this JSON value is considered equal to the provided JSON value (subject to the specified constraints), or false if not.

contains

public boolean contains(JSONValue value,
                        boolean ignoreFieldNameCase,
                        boolean ignoreValueCase,
                        boolean ignoreArrayOrder,
                        boolean recursive)

Indicates whether this JSON array contains an element with the specified value.

Parameters:

value - The value for which to make the determination.

ignoreFieldNameCase - Indicates whether to ignore differences in capitalization in field names for any JSON objects contained in the array.

ignoreValueCase - Indicates whether to ignore differences in capitalization for array elements that are JSON strings, as well as for the string values of any JSON objects and arrays contained in the array.

ignoreArrayOrder - Indicates whether to ignore differences in the order of elements contained in arrays. This is only applicable if the provided value is itself an array or is a JSON object that contains values that are arrays.

recursive - Indicates whether to recursively look into any arrays contained inside this array.

Returns:

true if this JSON array contains an element with the specified value, or false if not.

toString

public java.lang.String toString()

Retrieves a string representation of this value as it should appear in a JSON object, including any necessary quoting, escaping, etc.

Specified by:

toString in class JSONValue

Returns:

A string representation of this value as it should appear in a JSON object.

toString

public void toString(java.lang.StringBuilder buffer)

Appends a string representation of this value (as it should appear in a JSON object, including any necessary quoting, escaping, etc.) to the provided buffer.

Specified by:

toString in class JSONValue

Parameters:

buffer - The buffer to which the information should be appended.

toSingleLineString

public java.lang.String toSingleLineString()

Retrieves a single-line string representation of this value as it should appear in a JSON object, including any necessary quoting, escaping, etc.

Specified by:

toSingleLineString in class JSONValue

Returns:

A string representation of this value as it should appear in a JSON object.

toSingleLineString

public void toSingleLineString(java.lang.StringBuilder buffer)

Appends a single-line string representation of this value (as it should appear in a JSON object, including any necessary quoting, escaping, etc.) to the provided buffer.

Specified by:

toSingleLineString in class JSONValue

Parameters:

buffer - The buffer to which the information should be appended.

toNormalizedString

public java.lang.String toNormalizedString()

Retrieves a normalized string representation of this value. All equivalent JSON values must have equivalent normalized representations, even if there are other legal representations for the value.

Specified by:

toNormalizedString in class JSONValue

Returns:

A normalized string representation of this value.

toNormalizedString

public void toNormalizedString(java.lang.StringBuilder buffer)

Appends a normalized string representation of this value to the provided buffer. All equivalent JSON values must have equivalent normalized representations, even if there are other legal representations for the value.

Specified by:

toNormalizedString in class JSONValue

Parameters:

buffer - The buffer to which the information should be appended.

appendToJSONBuffer

public void appendToJSONBuffer(JSONBuffer buffer)

Appends this value to the provided JSON buffer. This will not include a field name, so it should only be used for Boolean value elements in an array.

Specified by:

appendToJSONBuffer in class JSONValue

Parameters:

buffer - The JSON buffer to which this value should be appended.

appendToJSONBuffer

public void appendToJSONBuffer(java.lang.String fieldName,
                               JSONBuffer buffer)

Appends a field with the given name and this value to the provided JSON buffer.

Specified by:

appendToJSONBuffer in class JSONValue

Parameters:

fieldName - The name to use for the field.

buffer - The JSON buffer to which this value should be appended.