Package org.apache.tapestry5.json
Class JSONObject
java.lang.Object
org.apache.tapestry5.json.JSONCollection
org.apache.tapestry5.json.JSONObject
- All Implemented Interfaces:
Serializable
,Map<String,
Object>
A modifiable set of name/value mappings. Names are unique, non-null strings.
Values may be any mix of
JSONObjects
, JSONArrays
, Strings, Booleans, Integers, Longs, Doubles or NULL
.
Values may not be null
, NaNs
, infinities
, or of any type not listed here.
This class can coerce values to another type when requested.
- When the requested type is a boolean, strings will be coerced using a case-insensitive comparison to "true" and "false".
- When the requested type is a double, other
Number
types will be coerced usingdoubleValue
. Strings that can be coerced usingDouble.valueOf(String)
will be. - When the requested type is an int, other
Number
types will be coerced usingintValue
. Strings that can be coerced usingDouble.valueOf(String)
will be, and then cast to int. - When the requested type is a long, other
Number
types will be coerced usinglongValue
. Strings that can be coerced usingDouble.valueOf(String)
will be, and then cast to long. This two-step conversion is lossy for very large values. For example, the string "9223372036854775806" yields the long 9223372036854775807. - When the requested type is a String, other non-null values will be
coerced using
String.valueOf(Object)
. Although null cannot be coerced, the sentinel valueNULL
is coerced to the string "null".
This class can look up both mandatory and optional values:
- Use
getType()
to retrieve a mandatory value. This fails with aRuntimeException
if the requested name has no value or if the value cannot be coerced to the requested type. - Use
opt()
to retrieve an optional value.
Warning: this class represents null in two incompatible
ways: the standard Java null
reference, and the sentinel value NULL
. In particular, calling put(name, null)
removes the
named entry from the object but put(name, JSONObject.NULL)
stores an
entry whose value is JSONObject.NULL
.
Instances of this class are not thread safe.
- See Also:
-
Nested Class Summary
-
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionCreates aJSONObject
with no name/value mappings.JSONObject
(Object... keysAndValues) Constructs a new JSONObject using a series of String keys and object values.JSONObject
(String json) Creates a newJSONObject
with name/value mappings from the JSON string.JSONObject
(JSONObject copyFrom, String... names) Creates a newJSONObject
by copying mappings for the listed names from the given object. -
Method Summary
Modifier and TypeMethodDescriptionaccumulate
(String name, Object value) Appendsvalue
to the array already mapped toname
.Appends values to the array mapped toname
.void
clear()
Removes all of the mappings from this JSONObject.boolean
containsKey
(Object key) Returnstrue
if this JSONObject contains a mapping for the specified key.boolean
containsValue
(Object value) Returnstrue
if this JSONObject maps one or more keys to the specified value.copy()
Returns a new JSONObject that is a shallow copy of this JSONObject.entrySet()
Returns aSet
view of the mappings contained in this JSONObject.boolean
Returns the value mapped byname
, or throws if no such mapping exists.boolean
getBoolean
(String name) Returns the value mapped byname
if it exists and is a boolean or can be coerced to a boolean, or throws otherwise.boolean
getBooleanOrDefault
(String name, boolean defaultValue) Returns the value to which the specified key is mapped and a boolean, ordefaultValue
if this JSONObject contains no mapping for the key.double
Returns the value mapped byname
if it exists and is a double or can be coerced to a double, or throws otherwise.int
Returns the value mapped byname
if it exists and is an int or can be coerced to an int, or throws otherwise.int
getIntOrDefault
(String name, int defaultValue) Returns the value to which the specified key is mapped and an int, ordefaultValue
if this JSONObject contains no mapping for the key.getJSONArray
(String name) Returns the value mapped byname
if it exists and is aJSONArray
, or throws otherwise.getJSONArrayOrDefault
(String name, JSONArray defaultValue) Returns the value to which the specified key is mapped and a JSONArray, ordefaultValue
if this JSONObject contains no mapping for the key.getJSONObject
(String name) Returns the value mapped byname
if it exists and is aJSONObject
, or throws otherwise.getJSONObjectOrDefault
(String name, JSONObject defaultValue) Returns the value to which the specified key is mapped and a JSONObject, ordefaultValue
if this map contains no mapping for the key.long
Returns the value mapped byname
if it exists and is a long or can be coerced to a long, or throws otherwise.long
getLongOrDefault
(String name, long defaultValue) Returns the value to which the specified key is mapped and a long, ordefaultValue
if this JSONObject contains no mapping for the key.getOrDefault
(Object key, Object defaultValue) Returns the value to which the specified key is mapped, ordefaultValue
if this JSONObject contains no mapping for the key.Returns the value mapped byname
if it exists, coercing it if necessary, or throws if no such mapping exists.getStringOrDefault
(String name, String defaultValue) Returns the value to which the specified key is mapped and a string, ordefaultValue
if this JSONObject contains no mapping for the key.boolean
Deprecated.int
hashCode()
Navigates into a nested JSONObject, creating the JSONObject if necessary.boolean
isEmpty()
Returnstrue
if this JSONObject contains no key-value mappings.boolean
Returns true if this object has no mapping forname
or if it has a mapping whose value isNULL
.keys()
Returns the set ofString
names in this object.keySet()
Returns aSet
view of the keys contained in this JSONObject.int
length()
Deprecated.Usesize()
instead.merge
(String key, Object value, BiFunction<? super Object, ? super Object, ? extends Object> remappingFunction) If the specified key is not already associated with a value or is associated with null, associates it with the given non-null value.names()
Returns an array containing the string names in this object.static String
numberToString
(Number number) Encodes the number as a JSON string.Returns the value mapped byname
, or null if no such mapping exists.Mapsname
tovalue
, clobbering any existing name/value mapping with the same name.void
Invokesput(String, Object)
for each value from the map.static String
Encodesdata
as a JSON string.Removes the named mapping if it exists; does nothing otherwise.int
size()
Returns the number of key-value mappings in this JSONObject.toMap()
Returns a Map of the keys and values of the JSONObject.values()
Returns aCollection
view of the values contained in this JSONObject.Methods inherited from class org.apache.tapestry5.json.JSONCollection
prettyPrint, print, print, toCompactString, toString, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.util.Map
compute, computeIfAbsent, computeIfPresent, forEach, putIfAbsent, remove, replace, replace, replaceAll
-
Field Details
-
NULL
A sentinel value used to explicitly define a name with no value. Unlikenull
, names with this value:- show up in the
names()
array - show up in the
keys()
iterator - return
true
forhas(String)
- do not throw on
get(java.lang.Object)
- are included in the encoded JSON string.
This value violates the general contract of
Object.equals(java.lang.Object)
by returning true when compared tonull
. ItsJSONCollection.toString()
method returns "null". - show up in the
-
-
Constructor Details
-
JSONObject
public JSONObject()Creates aJSONObject
with no name/value mappings. -
JSONObject
Creates a newJSONObject
with name/value mappings from the JSON string.- Parameters:
json
- a JSON-encoded string containing an object.- Throws:
RuntimeException
- if the parse fails or doesn't yield aJSONObject
.
-
JSONObject
Creates a newJSONObject
by copying mappings for the listed names from the given object. Names that aren't present incopyFrom
will be skipped.- Parameters:
copyFrom
- The source object.names
- The names of the fields to copy.- Throws:
RuntimeException
- On internal errors. Shouldn't happen.
-
JSONObject
Constructs a new JSONObject using a series of String keys and object values. Object values should be compatible withput(String, Object)
. Keys must be strings (toString() will be invoked on each key). Prior to release 5.4, keysAndValues was type String...; changing it to Object... makes it much easier to initialize a JSONObject in a single statement, which is more readable.- Since:
- 5.2.0
-
-
Method Details
-
copy
Returns a new JSONObject that is a shallow copy of this JSONObject.- Since:
- 5.4
-
length
Deprecated.Usesize()
instead.Returns the number of name/value mappings in this object.- Returns:
- the length of this.
-
put
Mapsname
tovalue
, clobbering any existing name/value mapping with the same name. If the value isnull
, any existing mapping forname
is removed.- Specified by:
put
in interfaceMap<String,
Object> - Parameters:
name
- The name of the new value.value
- aJSONObject
,JSONArray
, String, Boolean, Integer, Long, Double,NULL
, ornull
. May not beNaNs
orinfinities
.- Returns:
- this object.
- Throws:
IllegalArgumentException
- if the value is an invalid double (infinite or NaN).
-
accumulate
Appendsvalue
to the array already mapped toname
. If this object has no mapping forname
, this inserts a new mapping. If the mapping exists but its value is not an array, the existing and new values are inserted in order into a new array which is itself mapped toname
. In aggregate, this allows values to be added to a mapping one at a time. Note thatappend(String, Object)
provides better semantics. In particular, the mapping forname
will always be aJSONArray
. Usingaccumulate
will result in either aJSONArray
or a mapping whose type is the type ofvalue
depending on the number of calls to it.- Parameters:
name
- The name of the field to change.value
- aJSONObject
,JSONArray
, String, Boolean, Integer, Long, Double,NULL
or null. May not beNaNs
orinfinities
.- Returns:
- this object after mutation.
- Throws:
RuntimeException
- If the object being added is an invalid number.
-
append
Appends values to the array mapped toname
. A newJSONArray
mapping forname
will be inserted if no mapping exists. If the existing mapping forname
is not aJSONArray
, aRuntimeException
will be thrown.- Parameters:
name
- The name of the array to which the value should be appended.value
- The value to append.- Returns:
- this object.
- Throws:
JSONTypeMismatchException
- ifname
isnull
or if the mapping forname
is non-null and is not aJSONArray
.
-
isNull
Returns true if this object has no mapping forname
or if it has a mapping whose value isNULL
.- Parameters:
name
- The name of the value to check on.- Returns:
- true if the field doesn't exist or is null.
-
has
Deprecated.usecontainsKey(Object)
insteadReturns true if this object has a mapping forname
. The mapping may beNULL
.- Parameters:
name
- The name of the value to check on.- Returns:
- true if this object has a field named
name
-
opt
Returns the value mapped byname
, or null if no such mapping exists.- Parameters:
name
- The name of the value to get.- Returns:
- The value.
-
getBoolean
Returns the value mapped byname
if it exists and is a boolean or can be coerced to a boolean, or throws otherwise.- Parameters:
name
- The name of the field we want.- Returns:
- The selected value if it exists.
- Throws:
JSONValueNotFoundException
- if the mapping doesn't existJSONTypeMismatchException
- if the mapping cannot be coerced to a boolean.
-
getBooleanOrDefault
Returns the value to which the specified key is mapped and a boolean, ordefaultValue
if this JSONObject contains no mapping for the key.- Parameters:
name
- the key whose associated value is to be returneddefaultValue
- the default mapping of the key- Returns:
- the value to which the specified key is mapped, or
defaultValue
if this JSONObject contains no mapping for the key - Throws:
JSONTypeMismatchException
- if the mapping cannot be coerced to a boolean.- Since:
- 5.7
-
getDouble
Returns the value mapped byname
if it exists and is a double or can be coerced to a double, or throws otherwise.- Parameters:
name
- The name of the field we want.- Returns:
- The selected value if it exists.
- Throws:
JSONValueNotFoundException
- if the mapping doesn't existJSONTypeMismatchException
- if the mapping cannot be coerced to a double.
-
getInt
Returns the value mapped byname
if it exists and is an int or can be coerced to an int, or throws otherwise.- Parameters:
name
- The name of the field we want.- Returns:
- The selected value if it exists.
- Throws:
JSONValueNotFoundException
- if the mapping doesn't existJSONTypeMismatchException
- if the mapping cannot be coerced to an int.
-
getIntOrDefault
Returns the value to which the specified key is mapped and an int, ordefaultValue
if this JSONObject contains no mapping for the key.- Parameters:
name
- the key whose associated value is to be returneddefaultValue
- the default mapping of the key- Returns:
- the value to which the specified key is mapped, or
defaultValue
if this JSONObject contains no mapping for the key - Throws:
JSONTypeMismatchException
- if the mapping cannot be coerced to an int.- Since:
- 5.7
-
getLong
Returns the value mapped byname
if it exists and is a long or can be coerced to a long, or throws otherwise. Note that JSON represents numbers as doubles, so this is lossy; use strings to transfer numbers via JSON without loss.- Parameters:
name
- The name of the field that we want.- Returns:
- The value of the field.
- Throws:
JSONValueNotFoundException
- if the mapping doesn't existJSONTypeMismatchException
- if the mapping cannot be coerced to a long.
-
getLongOrDefault
Returns the value to which the specified key is mapped and a long, ordefaultValue
if this JSONObject contains no mapping for the key.- Parameters:
name
- the key whose associated value is to be returneddefaultValue
- the default mapping of the key- Returns:
- the value to which the specified key is mapped, or
defaultValue
if this JSONObject contains no mapping for the key - Throws:
JSONTypeMismatchException
- if the mapping cannot be coerced to a long.- Since:
- 5.7
-
getString
Returns the value mapped byname
if it exists, coercing it if necessary, or throws if no such mapping exists.- Parameters:
name
- The name of the field we want.- Returns:
- The value of the field.
- Throws:
JSONValueNotFoundException
- if the mapping doesn't existJSONTypeMismatchException
- if the mapping cannot be coerced to String
-
getStringOrDefault
Returns the value to which the specified key is mapped and a string, ordefaultValue
if this JSONObject contains no mapping for the key.- Parameters:
name
- the key whose associated value is to be returneddefaultValue
- the default mapping of the key- Returns:
- the value to which the specified key is mapped, or
defaultValue
if this JSONObject contains no mapping for the key - Throws:
JSONTypeMismatchException
- if the mapping cannot be coerced to a string.- Since:
- 5.7
-
getJSONArray
Returns the value mapped byname
if it exists and is aJSONArray
, or throws otherwise.- Parameters:
name
- The field we want to get.- Returns:
- The value of the field (if it is a JSONArray.
- Throws:
JSONValueNotFoundException
- if the mapping doesn't existJSONTypeMismatchException
- if the mapping is not aJSONArray
.
-
getJSONArrayOrDefault
Returns the value to which the specified key is mapped and a JSONArray, ordefaultValue
if this JSONObject contains no mapping for the key.- Parameters:
name
- the key whose associated value is to be returneddefaultValue
- the default mapping of the key- Returns:
- the value to which the specified key is mapped, or
defaultValue
if this JSONObject contains no mapping for the key - Throws:
JSONTypeMismatchException
- if the mapping cannot be coerced to a JSONArray.- Since:
- 5.7
-
getJSONObject
Returns the value mapped byname
if it exists and is aJSONObject
, or throws otherwise.- Parameters:
name
- The name of the field that we want.- Returns:
- a specified field value (if it is a JSONObject)
- Throws:
JSONValueNotFoundException
- if the mapping doesn't existJSONTypeMismatchException
- if the mapping is not aJSONObject
.
-
getJSONObjectOrDefault
Returns the value to which the specified key is mapped and a JSONObject, ordefaultValue
if this map contains no mapping for the key.- Parameters:
name
- the key whose associated value is to be returneddefaultValue
- the default mapping of the key- Returns:
- the value to which the specified key is mapped, or
defaultValue
if this map contains no mapping for the key - Throws:
JSONTypeMismatchException
- if the mapping cannot be coerced to a JSONObject.- Since:
- 5.7
-
keys
Returns the set ofString
names in this object. The returned set is a view of the keys in this object.Set.remove(Object)
will remove the corresponding mapping from this object and set iterator behaviour is undefined if this object is modified after it is returned. Seekeys()
.- Returns:
- The names in this object.
-
names
Returns an array containing the string names in this object. This method returns null if this object contains no mappings.- Returns:
- the names.
-
numberToString
Encodes the number as a JSON string.- Parameters:
number
- a finite value. May not beNaNs
orinfinities
.- Returns:
- The encoded number in string form.
- Throws:
RuntimeException
- On internal errors. Shouldn't happen.
-
quote
Encodesdata
as a JSON string. This applies quotes and any necessary character escaping.- Parameters:
data
- the string to encode. Null will be interpreted as an empty string.- Returns:
- the quoted string.
-
equals
-
hashCode
-
toMap
Returns a Map of the keys and values of the JSONObject. The returned map is unmodifiable. Note that changes to the JSONObject will be reflected in the map. In addition, null values in the JSONObject are represented asNULL
in the map.- Returns:
- unmodifiable map of properties and values
- Since:
- 5.4
-
in
Navigates into a nested JSONObject, creating the JSONObject if necessary. They key must not exist, or must be a JSONObject.- Parameters:
key
-- Returns:
- the nested JSONObject
- Throws:
IllegalStateException
- if the current value for the key is not null and not JSONObject
-
size
Returns the number of key-value mappings in this JSONObject. If it contains more thanInteger.MAX_VALUE
elements, returnsInteger.MAX_VALUE
. -
isEmpty
Returnstrue
if this JSONObject contains no key-value mappings. -
containsKey
Returnstrue
if this JSONObject contains a mapping for the specified key.- Specified by:
containsKey
in interfaceMap<String,
Object> - Parameters:
key
- key whose presence in this map is to be tested- Returns:
true
if this map contains a mapping for the specified key- Since:
- 5.7
-
containsValue
Returnstrue
if this JSONObject maps one or more keys to the specified value.- Specified by:
containsValue
in interfaceMap<String,
Object> - Parameters:
value
- value whose presence in this map is to be tested- Returns:
true
if this JSONObject maps one or more keys to the specified value- Since:
- 5.7
-
get
Returns the value mapped byname
, or throws if no such mapping exists.- Specified by:
get
in interfaceMap<String,
Object> - Parameters:
name
- The name of the value to get.- Returns:
- The value.
- Throws:
JSONValueNotFoundException
- if no such mapping exists.
-
getOrDefault
Returns the value to which the specified key is mapped, ordefaultValue
if this JSONObject contains no mapping for the key.- Specified by:
getOrDefault
in interfaceMap<String,
Object> - Parameters:
key
- the key whose associated value is to be returneddefaultValue
- the default mapping of the key- Returns:
- the value to which the specified key is mapped, or
defaultValue
if this JSONObject contains no mapping for the key - Since:
- 5.7
-
remove
Removes the named mapping if it exists; does nothing otherwise. -
putAll
Invokesput(String, Object)
for each value from the map. -
clear
Removes all of the mappings from this JSONObject. -
keySet
Returns aSet
view of the keys contained in this JSONObject. The set is backed by the JSONObject, so changes to the map are reflected in the set, and vice-versa. -
values
Returns aCollection
view of the values contained in this JSONObject. The collection is backed by the JSONObject, so changes to the map are reflected in the collection, and vice-versa. -
entrySet
Returns aSet
view of the mappings contained in this JSONObject. The set is backed by the JSONObject, so changes to the map are reflected in the set, and vice-versa. -
merge
public Object merge(String key, Object value, BiFunction<? super Object, ? super Object, ? extends Object> remappingFunction) If the specified key is not already associated with a value or is associated with null, associates it with the given non-null value. Otherwise, replaces the associated value with the results of the given remapping function, or removes if the result isnull
.- Specified by:
merge
in interfaceMap<String,
Object> - Parameters:
key
- key with which the resulting value is to be associatedvalue
- the non-null value to be merged with the existing value associated with the key or, if no existing value or a null value is associated with the key, to be associated with the keyremappingFunction
- the function to recompute a value if present- Returns:
- the new value associated with the specified key, or null if no value is associated with the key
- Throws:
NullPointerException
- if the specified key is null or the value or remappingFunction is null- Since:
- 5.7
-
containsKey(Object)
instead