@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class JSONObject extends JSONValue
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.
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.
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.Modifier and Type | Field and Description |
---|---|
static JSONObject |
EMPTY_OBJECT
A pre-allocated empty JSON object.
|
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.
|
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.
|
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.
|
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.
|
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.
|
public static final JSONObject EMPTY_OBJECT
public JSONObject(JSONField... fields)
fields
- The fields to include in this JSON object. It may be
null
or empty if this object should not have any
fields.public JSONObject(java.util.Map<java.lang.String,JSONValue> fields)
fields
- The set of fields for this JSON object. It may be
null
or empty if there should not be any fields.public JSONObject(java.lang.String stringRepresentation) throws JSONException
stringRepresentation
- The string to parse as a JSON object. It
must represent exactly one JSON object.JSONException
- If the provided string cannot be parsed as a valid
JSON object.public java.util.Map<java.lang.String,JSONValue> getFields()
public JSONValue getField(java.lang.String name)
name
- The name of the field for which to retrieve the value. It
will be treated in a case-sensitive manner.null
if the
requested field is not present in the JSON object.public java.lang.String getFieldAsString(java.lang.String name)
name
- The name of the field for which to retrieve the string value.
It will be treated in a case-sensitive manner.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.public java.lang.Boolean getFieldAsBoolean(java.lang.String name)
name
- The name of the field for which to retrieve the Boolean
value. It will be treated in a case-sensitive manner.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.public java.lang.Integer getFieldAsInteger(java.lang.String name)
name
- The name of the field for which to retrieve the integer
value. It will be treated in a case-sensitive manner.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.public java.lang.Long getFieldAsLong(java.lang.String name)
name
- The name of the field for which to retrieve the long value.
It will be treated in a case-sensitive manner.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.public java.math.BigDecimal getFieldAsBigDecimal(java.lang.String name)
name
- The name of the field for which to retrieve the BigDecimal
value. It will be treated in a case-sensitive manner.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.public JSONObject getFieldAsObject(java.lang.String name)
name
- The name of the field for which to retrieve the value. It
will be treated in a case-sensitive manner.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.public java.util.List<JSONValue> getFieldAsArray(java.lang.String name)
name
- The name of the field for which to retrieve the array values.
It will be treated in a case-sensitive manner.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.public boolean hasNullField(java.lang.String name)
name
- The name of the field for which to make the determination.
It will be treated in a case-sensitive manner.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.public int hashCode()
public boolean equals(java.lang.Object o)
public boolean equals(JSONObject o, boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)
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.true
if this JSON object is considered equal to the
provided object (subject to the specified constraints), or
false
if not.public boolean equals(JSONValue v, boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)
equals
in class JSONValue
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.true
if this JSON value is considered equal to the
provided JSON value (subject to the specified constraints), or
false
if not.public java.lang.String toString()
public void toString(java.lang.StringBuilder buffer)
public java.lang.String toMultiLineString()
public java.lang.String toSingleLineString()
toSingleLineString
in class JSONValue
public void toSingleLineString(java.lang.StringBuilder buffer)
toSingleLineString
in class JSONValue
buffer
- The buffer to which the information should be appended.public java.lang.String toNormalizedString()
toNormalizedString
in class JSONValue
public void toNormalizedString(java.lang.StringBuilder buffer)
toNormalizedString
in class JSONValue
buffer
- The buffer to which the information should be appended.public java.lang.String toNormalizedString(boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)
toNormalizedString
in class JSONValue
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
).public void toNormalizedString(java.lang.StringBuilder buffer, boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)
toNormalizedString
in class JSONValue
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
).public void appendToJSONBuffer(JSONBuffer buffer)
appendToJSONBuffer
in class JSONValue
buffer
- The JSON buffer to which this value should be appended.public void appendToJSONBuffer(java.lang.String fieldName, JSONBuffer buffer)
appendToJSONBuffer
in class JSONValue
fieldName
- The name to use for the field.buffer
- The JSON buffer to which this value should be appended.