com.unboundid.util.json
Class JSONObject

java.lang.Object
  extended by com.unboundid.util.json.JSONValue
      extended by com.unboundid.util.json.JSONObject
All Implemented Interfaces:
java.io.Serializable

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

This class provides an implementation of a JSON value that represents an object with zero or more name-value pairs. In each pair, the name is a JSON string and the value is any type of JSON value (null, true, false, number, string, array, or object). Although the ECMA-404 specification does not explicitly forbid a JSON object from having multiple fields with the same name, RFC 7159 section 4 states that field names should be unique, and this implementation does not support objects in which multiple fields have the same name. Note that this uniqueness constraint only applies to the fields directly contained within an object, and does not prevent an object from having a field value that is an object (or that is an array containing one or more objects) that use a field name that is also in use in the outer object. Similarly, if an array contains multiple JSON objects, then there is no restriction preventing the same field names from being used in separate objects within that array.

The string representation of a JSON object is an open curly brace (U+007B) followed by a comma-delimited list of the name-value pairs that comprise the fields in that object and a closing curly brace (U+007D). Each name-value pair is represented as a JSON string followed by a colon and the appropriate string representation of the value. There must not be a comma between the last field and the closing curly brace. 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 curly brace, on either or both sides of the colon separating a field name from its value, on either or both sides of commas separating fields, and before the closing curly brace. The order in which fields appear in the string representation is not considered significant.

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 field name and one space before the closing curly brace. There will not be any space on either side of the colon separating the field name from its value, and there will not be any space between a field value and the comma that follows it. The string representation of each field name will use the same logic as the JSONString.toString() method, and the string representation of each field value 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 field value will be obtained using that value's toNormalizedString method. Field names will be treated in a case-sensitive manner, but all characters outside the LDAP printable character set will be escaped using the \u-style Unicode encoding. The normalized string representation will have fields listed in lexicographic order.

See Also:
Serialized Form

Field Summary
static JSONObject EMPTY_OBJECT
          A pre-allocated empty JSON object.
 
Constructor Summary
JSONObject(JSONField... fields)
          Creates a new JSON object with the provided fields.
JSONObject(java.util.Map<java.lang.String,JSONValue> fields)
          Creates a new JSON object with the provided fields.
JSONObject(java.lang.String stringRepresentation)
          Creates a new JSON object parsed from the provided string.
 
Method Summary
 boolean equals(JSONObject o, boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)
          Indicates whether this JSON object is considered equal to the provided object, 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.
 JSONValue getField(java.lang.String name)
          Retrieves the value for the specified field.
 java.util.Map<java.lang.String,JSONValue> getFields()
          Retrieves a map of the fields contained in this JSON object.
 int hashCode()
          Retrieves a hash code for this JSON value.
 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 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_OBJECT

public static final JSONObject EMPTY_OBJECT
A pre-allocated empty JSON object.

Constructor Detail

JSONObject

public JSONObject(JSONField... fields)
Creates a new JSON object with the provided fields.

Parameters:
fields - The fields to include in this JSON object. It may be null or empty if this object should not have any fields.

JSONObject

public JSONObject(java.util.Map<java.lang.String,JSONValue> fields)
Creates a new JSON object with the provided fields.

Parameters:
fields - The set of fields for this JSON object. It may be null or empty if there should not be any fields.

JSONObject

public JSONObject(java.lang.String stringRepresentation)
           throws JSONException
Creates a new JSON object parsed from the provided string.

Parameters:
stringRepresentation - The string to parse as a JSON object. It must represent exactly one JSON object.
Throws:
JSONException - If the provided string cannot be parsed as a valid JSON object.
Method Detail

getFields

public java.util.Map<java.lang.String,JSONValue> getFields()
Retrieves a map of the fields contained in this JSON object.

Returns:
A map of the fields contained in this JSON object.

getField

public JSONValue getField(java.lang.String name)
Retrieves the value for the specified field.

Parameters:
name - The name of the field for which to retrieve the value. It will be treated in a case-sensitive manner.
Returns:
The value for the specified field, or null if the requested field is not present in the JSON object.

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(JSONObject o,
                      boolean ignoreFieldNameCase,
                      boolean ignoreValueCase,
                      boolean ignoreArrayOrder)
Indicates whether this JSON object is considered equal to the provided object, subject to the specified constraints.

Parameters:
o - The object to compare against this JSON object. It must not be null.
ignoreFieldNameCase - Indicates whether to ignore differences in capitalization in field names.
ignoreValueCase - Indicates whether to ignore differences in capitalization in values that are JSON strings.
ignoreArrayOrder - Indicates whether to ignore differences in the order of elements within an array.
Returns:
true if this JSON object is considered equal to the provided object (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.

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.

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.