JSONObject (UnboundID LDAP SDK for Java 7.0.0)

java.lang.Object
- com.unboundid.util.json.JSONValue
- - com.unboundid.util.json.JSONObject

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<JSONValue>
```
@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

Fields
Modifier and Type Field and Description

static JSONObject EMPTY_OBJECT
A pre-allocated empty JSON object.

Fields
Modifier and Type	Field and Description
`static JSONObject`	`EMPTY_OBJECT` A pre-allocated empty JSON object.

Constructor Summary

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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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`	`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.List<JSONValue>`	`getFieldAsArray(java.lang.String name)` Retrieves a list of the elements in the specified array field.
`java.math.BigDecimal`	`getFieldAsBigDecimal(java.lang.String name)` Retrieves the value of the specified field as a BigDecimal.
`java.lang.Boolean`	`getFieldAsBoolean(java.lang.String name)` Retrieves the value of the specified field as a Boolean.
`java.lang.Integer`	`getFieldAsInteger(java.lang.String name)` Retrieves the value of the specified field as an integer.
`java.lang.Long`	`getFieldAsLong(java.lang.String name)` Retrieves the value of the specified field as a long.
`JSONObject`	`getFieldAsObject(java.lang.String name)` Retrieves the value of the specified field as a JSON object.
`java.lang.String`	`getFieldAsString(java.lang.String name)` Retrieves the value of the specified field as a string.
`JSONValue`	`getFieldIgnoreCaseIgnoreConflict(java.lang.String name)` Retrieves the value for the specified field, treating the field name as case-insensitive.
`JSONValue`	`getFieldIgnoreCaseThrowOnConflict(java.lang.String name)` Retrieves the value for the specified field, treating the field name as case-insensitive.
`java.util.Map<java.lang.String,JSONValue>`	`getFields()` Retrieves a map of the fields contained in this JSON object.
`java.util.Map<java.lang.String,JSONValue>`	`getFieldsIgnoreCase(java.lang.String name)` Retrieves a map of all fields with the specified name, treating the name as case-insensitive.
`boolean`	`hasField(java.lang.String fieldName)` Indicates whether this JSON object has a field with the specified name.
`int`	`hashCode()` Retrieves a hash code for this JSON value.
`boolean`	`hasNullField(java.lang.String name)` Indicates whether this JSON object has a null field with the specified name.
`java.lang.String`	`toMultiLineString()` Retrieves a user-friendly string representation of this JSON object that may be formatted across multiple lines for better readability.
`java.lang.String`	`toNormalizedString()` Retrieves a normalized string representation of this JSON object.
`java.lang.String`	`toNormalizedString(boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)` Retrieves a normalized string representation of this JSON object.
`void`	`toNormalizedString(java.lang.StringBuilder buffer)` Appends a normalized string representation of this JSON object to the provided buffer.
`void`	`toNormalizedString(java.lang.StringBuilder buffer, boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)` Appends a normalized string representation of this JSON object to the provided buffer.
`JSONObject`	`toNormalizedValue(boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)` Retrieves a normalized representation of this value using the provided settings.
`java.lang.String`	`toSingleLineString()` Retrieves a single-line string representation of this JSON object.
`void`	`toSingleLineString(java.lang.StringBuilder buffer)` Appends a single-line string representation of this JSON object to the provided buffer.
`java.lang.String`	`toString()` Retrieves a string representation of this JSON object.
`void`	`toString(java.lang.StringBuilder buffer)` Appends a string representation of this JSON object to the provided buffer.

Methods inherited from class com.unboundid.util.json.JSONValue
compareTo

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - EMPTY_OBJECT
```
@NotNull
public static final JSONObject EMPTY_OBJECT
```
    A pre-allocated empty JSON object.
- Constructor Detail
  - JSONObject
```
public JSONObject(@Nullable
                  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(@Nullable
                  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(@NotNull
                  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
```
@NotNull
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
```
@Nullable
public JSONValue getField(@NotNull
                                    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.
  - getFieldIgnoreCaseIgnoreConflict
```
@Nullable
public JSONValue getFieldIgnoreCaseIgnoreConflict(@NotNull
                                                            java.lang.String name)
```
    Retrieves the value for the specified field, treating the field name as case-insensitive. If the object has multiple fields with different capitalizations of the specified name, then only the first one found will be returned and any subsequent fields will be ignored.
    
    Parameters:
    
    name - The name of the field for which to retrieve the value. It will be treated in a case-insensitive manner.
    
    Returns:
    
    The value for the specified field, or null if the requested field is not present in the JSON object.
  - getFieldIgnoreCaseThrowOnConflict
```
@Nullable
public JSONValue getFieldIgnoreCaseThrowOnConflict(@NotNull
                                                             java.lang.String name)
                                                      throws JSONException
```
    Retrieves the value for the specified field, treating the field name as case-insensitive. If the object has multiple fields with different capitalizations of the first name, then an exception will be thrown.
    
    Parameters:
    
    name - The name of the field for which to retrieve the value. It will be treated in a case-insensitive manner.
    
    Returns:
    
    The value for the specified field, or null if the requested field is not present in the JSON object.
    
    Throws:
    
    JSONException - If the object has multiple fields with different capitalizations of the provided name.
  - getFieldsIgnoreCase
```
@NotNull
public java.util.Map<java.lang.String,JSONValue> getFieldsIgnoreCase(@NotNull
                                                                              java.lang.String name)
```
    Retrieves a map of all fields with the specified name, treating the name as case-insensitive.
    
    Parameters:
    
    name - The name of the field for which to retrieve the values. It will be treated in a case-insensitive manner.
    
    Returns:
    
    A map of all fields with the specified name, or an empty map if there are no fields with the specified name.
  - getFieldAsString
```
@Nullable
public java.lang.String getFieldAsString(@NotNull
                                                   java.lang.String name)
```
    Retrieves the value of the specified field as a string.
    
    Parameters:
    
    name - The name of the field for which to retrieve the string value. It will be treated in a case-sensitive manner.
    
    Returns:
    
    The value of the specified field as a string, or null if this JSON object does not have a field with the specified name, or if the value of that field is not a string.
  - getFieldAsBoolean
```
@Nullable
public java.lang.Boolean getFieldAsBoolean(@NotNull
                                                     java.lang.String name)
```
    Retrieves the value of the specified field as a Boolean.
    
    Parameters:
    
    name - The name of the field for which to retrieve the Boolean value. It will be treated in a case-sensitive manner.
    
    Returns:
    
    The value of the specified field as a Boolean, or null if this JSON object does not have a field with the specified name, or if the value of that field is not a Boolean.
  - getFieldAsInteger
```
@Nullable
public java.lang.Integer getFieldAsInteger(@NotNull
                                                     java.lang.String name)
```
    Retrieves the value of the specified field as an integer.
    
    Parameters:
    
    name - The name of the field for which to retrieve the integer value. It will be treated in a case-sensitive manner.
    
    Returns:
    
    The value of the specified field as an integer, or null if this JSON object does not have a field with the specified name, or if the value of that field is not a number that can be exactly represented as an integer.
  - getFieldAsLong
```
@Nullable
public java.lang.Long getFieldAsLong(@NotNull
                                               java.lang.String name)
```
    Retrieves the value of the specified field as a long.
    
    Parameters:
    
    name - The name of the field for which to retrieve the long value. It will be treated in a case-sensitive manner.
    
    Returns:
    
    The value of the specified field as a long, or null if this JSON object does not have a field with the specified name, or if the value of that field is not a number that can be exactly represented as a long.
  - getFieldAsBigDecimal
```
@Nullable
public java.math.BigDecimal getFieldAsBigDecimal(@NotNull
                                                           java.lang.String name)
```
    Retrieves the value of the specified field as a BigDecimal.
    
    Parameters:
    
    name - The name of the field for which to retrieve the BigDecimal value. It will be treated in a case-sensitive manner.
    
    Returns:
    
    The value of the specified field as a BigDecimal, or null if this JSON object does not have a field with the specified name, or if the value of that field is not a number.
  - getFieldAsObject
```
@Nullable
public JSONObject getFieldAsObject(@NotNull
                                             java.lang.String name)
```
    Retrieves the value of the specified field as a JSON object.
    
    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 of the specified field as a JSON object, or null if this JSON object does not have a field with the specified name, or if the value of that field is not an object.
  - getFieldAsArray
```
@Nullable
public java.util.List<JSONValue> getFieldAsArray(@NotNull
                                                           java.lang.String name)
```
    Retrieves a list of the elements in the specified array field.
    
    Parameters:
    
    name - The name of the field for which to retrieve the array values. It will be treated in a case-sensitive manner.
    
    Returns:
    
    A list of the elements in the specified array field, or null if this JSON object does not have a field with the specified name, or if the value of that field is not an array.
  - hasNullField
```
public boolean hasNullField(@NotNull
                            java.lang.String name)
```
    Indicates whether this JSON object has a null field with the specified name.
    
    Parameters:
    
    name - The name of the field for which to make the determination. It will be treated in a case-sensitive manner.
    
    Returns:
    
    true if this JSON object has a null field with the specified name, or false if this JSON object does not have a field with the specified name, or if the value of that field is not a null.
  - hasField
```
public boolean hasField(@NotNull
                        java.lang.String fieldName)
```
    Indicates whether this JSON object has a field with the specified name.
    
    Parameters:
    
    fieldName - The name of the field for which to make the determination. It will be treated in a case-sensitive manner.
    
    Returns:
    
    true if this JSON object has a field with the specified name, or false if not.
  - 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(@Nullable
                      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(@NotNull
                      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(@NotNull
                      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
```
@NotNull
public java.lang.String toString()
```
    Retrieves a string representation of this JSON object. If this object was decoded from a string, then the original string representation will be used. Otherwise, a single-line string representation will be constructed.
    
    Specified by:
    
    toString in class JSONValue
    
    Returns:
    
    A string representation of this JSON object.
  - toString
```
public void toString(@NotNull
                     java.lang.StringBuilder buffer)
```
    Appends a string representation of this JSON object to the provided buffer. If this object was decoded from a string, then the original string representation will be used. Otherwise, a single-line string representation will be constructed.
    
    Specified by:
    
    toString in class JSONValue
    
    Parameters:
    
    buffer - The buffer to which the information should be appended.
  - toMultiLineString
```
@NotNull
public java.lang.String toMultiLineString()
```
    Retrieves a user-friendly string representation of this JSON object that may be formatted across multiple lines for better readability. The last line will not include a trailing line break.
    
    Returns:
    
    A user-friendly string representation of this JSON object that may be formatted across multiple lines for better readability.
  - toSingleLineString
```
@NotNull
public java.lang.String toSingleLineString()
```
    Retrieves a single-line string representation of this JSON object.
    
    Specified by:
    
    toSingleLineString in class JSONValue
    
    Returns:
    
    A single-line string representation of this JSON object.
  - toSingleLineString
```
public void toSingleLineString(@NotNull
                               java.lang.StringBuilder buffer)
```
    Appends a single-line string representation of this JSON object to the provided buffer.
    
    Specified by:
    
    toSingleLineString in class JSONValue
    
    Parameters:
    
    buffer - The buffer to which the information should be appended.
  - toNormalizedString
```
@NotNull
public java.lang.String toNormalizedString()
```
    Retrieves a normalized string representation of this JSON object. The normalized representation of the JSON object will have the following characteristics:
    - It will not include any line breaks.
    - It will not include any spaces around the enclosing braces.
    - It will not include any spaces around the commas used to separate fields.
    - Field names will be treated in a case-sensitive manner and will not be altered.
    - Field values will be normalized.
    - Fields will be listed in lexicographic order by field name.
    Specified by:
    
    toNormalizedString in class JSONValue
    
    Returns:
    
    A normalized string representation of this JSON object.
  - toNormalizedString
```
public void toNormalizedString(@NotNull
                               java.lang.StringBuilder buffer)
```
    Appends a normalized string representation of this JSON object to the provided buffer. The normalized representation of the JSON object will have the following characteristics:
    - It will not include any line breaks.
    - It will not include any spaces around the enclosing braces.
    - It will not include any spaces around the commas used to separate fields.
    - Field names will be treated in a case-sensitive manner and will not be altered.
    - Field values will be normalized.
    - Fields will be listed in lexicographic order by field name.
    Specified by:
    
    toNormalizedString in class JSONValue
    
    Parameters:
    
    buffer - The buffer to which the information should be appended.
  - toNormalizedString
```
@NotNull
public java.lang.String toNormalizedString(boolean ignoreFieldNameCase,
                                                    boolean ignoreValueCase,
                                                    boolean ignoreArrayOrder)
```
    Retrieves a normalized string representation of this JSON object. The normalized representation of the JSON object will have the following characteristics:
    - It will not include any line breaks.
    - It will not include any spaces around the enclosing braces.
    - It will not include any spaces around the commas used to separate fields.
    - Case sensitivity of field names and values will be controlled by argument values.
    - Fields will be listed in lexicographic order by field name.
    Specified by:
    
    toNormalizedString in class JSONValue
    
    Parameters:
    
    ignoreFieldNameCase - Indicates whether field names should be treated in a case-sensitive (if false) or case-insensitive (if true) manner.
    
    ignoreValueCase - Indicates whether string field values should be treated in a case-sensitive (if false) or case-insensitive (if true) manner.
    
    ignoreArrayOrder - Indicates whether the order of elements in an array should be considered significant (if false) or insignificant (if true).
    
    Returns:
    
    A normalized string representation of this JSON object.
  - toNormalizedString
```
public void toNormalizedString(@NotNull
                               java.lang.StringBuilder buffer,
                               boolean ignoreFieldNameCase,
                               boolean ignoreValueCase,
                               boolean ignoreArrayOrder)
```
    Appends a normalized string representation of this JSON object to the provided buffer. The normalized representation of the JSON object will have the following characteristics:
    - It will not include any line breaks.
    - It will not include any spaces around the enclosing braces.
    - It will not include any spaces around the commas used to separate fields.
    - Field names will be treated in a case-sensitive manner and will not be altered.
    - Field values will be normalized.
    - Fields will be listed in lexicographic order by field name.
    Specified by:
    
    toNormalizedString in class JSONValue
    
    Parameters:
    
    buffer - The buffer to which the information should be appended.
    
    ignoreFieldNameCase - Indicates whether field names should be treated in a case-sensitive (if false) or case-insensitive (if true) manner.
    
    ignoreValueCase - Indicates whether string field values should be treated in a case-sensitive (if false) or case-insensitive (if true) manner.
    
    ignoreArrayOrder - Indicates whether the order of elements in an array should be considered significant (if false) or insignificant (if true).
  - toNormalizedValue
```
@NotNull
public JSONObject toNormalizedValue(boolean ignoreFieldNameCase,
                                             boolean ignoreValueCase,
                                             boolean ignoreArrayOrder)
```
    Retrieves a normalized representation of this value using the provided settings.
    
    Specified by:
    
    toNormalizedValue in class JSONValue
    
    Parameters:
    
    ignoreFieldNameCase - Indicates whether field names should be treated in a case-sensitive (if false) or case-insensitive (if true) manner.
    
    ignoreValueCase - Indicates whether string field values should be treated in a case-sensitive (if false) or case-insensitive (if true) manner.
    
    ignoreArrayOrder - Indicates whether the order of elements in an array should be considered significant (if false) or insignificant (if true).
    
    Returns:
    
    A normalized representation of this value using the provided settings.
  - appendToJSONBuffer
```
public void appendToJSONBuffer(@NotNull
                               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(@NotNull
                               java.lang.String fieldName,
                               @NotNull
                               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.

Class JSONObject

Field Summary

Constructor Summary

Method Summary

Methods inherited from class com.unboundid.util.json.JSONValue

Methods inherited from class java.lang.Object

Field Detail

EMPTY_OBJECT

Constructor Detail

JSONObject

JSONObject

JSONObject

Method Detail

getFields

getField

getFieldIgnoreCaseIgnoreConflict

getFieldIgnoreCaseThrowOnConflict

getFieldsIgnoreCase

getFieldAsString

getFieldAsBoolean

getFieldAsInteger

getFieldAsLong

getFieldAsBigDecimal

getFieldAsObject

getFieldAsArray

hasNullField

hasField

hashCode

equals

equals

equals

toString

toString

toMultiLineString

toSingleLineString

toSingleLineString

toNormalizedString

toNormalizedString

toNormalizedString

toNormalizedString

toNormalizedValue

appendToJSONBuffer

appendToJSONBuffer