Interface JsonArray
-
- All Superinterfaces:
Collection<JsonValue>
,Iterable<JsonValue>
,JsonStructure
,JsonValue
,List<JsonValue>
public interface JsonArray extends JsonStructure, List<JsonValue>
JsonArray
represents an immutable JSON array (an ordered sequence of zero or more values). It also provides an unmodifiable list view of the values in the array.A
JsonArray
object can be created by reading JSON data from an input source or it can be built from scratch using an array builder object.The following example demonstrates how to create a
JsonArray
object from an input source using the methodJsonReader.readArray()
:JsonReader jsonReader = Json.createReader(...); JsonArray array = jsonReader.readArray(); jsonReader.close();
The following example demonstrates how to build an empty JSON array using the class
JsonArrayBuilder
:JsonArray array = Json.createArrayBuilder().build();
The example code below demonstrates how to create the following JSON array:
[ { "type": "home", "number": "212 555-1234" }, { "type": "fax", "number": "646 555-4567" } ]
JsonArray value = Json.createArrayBuilder() .add(Json.createObjectBuilder() .add("type", "home") .add("number", "212 555-1234")) .add(Json.createObjectBuilder() .add("type", "fax") .add("number", "646 555-4567")) .build();
The following example demonstrates how to write a
JsonArray
object as JSON data:JsonArray arr = ...; JsonWriter writer = Json.createWriter(...) writer.writeArray(arr); writer.close();
The values in a
JsonArray
can be of the following types:JsonObject
,JsonArray
,JsonString
,JsonNumber
,JsonValue.TRUE
,JsonValue.FALSE
, andJsonValue.NULL
.JsonArray
provides various accessor methods to access the values in an array.The following example shows how to obtain the home phone number "212 555-1234" from the array built in the previous example:
JsonObject home = array.getJsonObject(0); String number = home.getString("number");
JsonArray
instances are list objects that provide read-only access to the values in the JSON array. Any attempt to modify the list, whether directly or using its collection views, results in anUnsupportedOperationException
.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface jakarta.json.JsonValue
JsonValue.ValueType
-
-
Field Summary
-
Fields inherited from interface jakarta.json.JsonValue
EMPTY_JSON_ARRAY, EMPTY_JSON_OBJECT, FALSE, NULL, TRUE
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description boolean
getBoolean(int index)
Returns the boolean value at the specified position.boolean
getBoolean(int index, boolean defaultValue)
Returns the boolean value at the specified position.int
getInt(int index)
A convenience method forgetJsonNumber(index).intValue()
.int
getInt(int index, int defaultValue)
Returns the int value of theJsonNumber
at the specified position.JsonArray
getJsonArray(int index)
Returns the array value at the specified position in this array.JsonNumber
getJsonNumber(int index)
Returns the number value at the specified position in this array.JsonObject
getJsonObject(int index)
Returns the object value at the specified position in this array.JsonString
getJsonString(int index)
Returns the string value at ths specified position in this array.String
getString(int index)
A convenience method forgetJsonString(index).getString()
.String
getString(int index, String defaultValue)
Returns theString
value ofJsonString
at the specified position in this JSON array values.<T extends JsonValue>
List<T>getValuesAs(Class<T> clazz)
Returns a list view of the specified type for the array.default <T,K extends JsonValue>
List<T>getValuesAs(Function<K,T> func)
Returns a list view for the array.boolean
isNull(int index)
Returnstrue
if the value at the specified location in this array isJsonValue.NULL
.-
Methods inherited from interface java.util.Collection
parallelStream, removeIf, stream, toArray
-
Methods inherited from interface jakarta.json.JsonStructure
getValue
-
Methods inherited from interface jakarta.json.JsonValue
asJsonArray, asJsonObject, getValueType, toString
-
Methods inherited from interface java.util.List
add, add, addAll, addAll, clear, contains, containsAll, equals, get, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, replaceAll, retainAll, set, size, sort, spliterator, subList, toArray, toArray
-
-
-
-
Method Detail
-
getJsonObject
JsonObject getJsonObject(int index)
Returns the object value at the specified position in this array. This is a convenience method for(JsonObject)get(index)
.- Parameters:
index
- index of the value to be returned- Returns:
- the value at the specified position in this array
- Throws:
IndexOutOfBoundsException
- if the index is out of rangeClassCastException
- if the value at the specified position is not assignable to the JsonObject type
-
getJsonArray
JsonArray getJsonArray(int index)
Returns the array value at the specified position in this array. This is a convenience method for(JsonArray)get(index)
.- Parameters:
index
- index of the value to be returned- Returns:
- the value at the specified position in this array
- Throws:
IndexOutOfBoundsException
- if the index is out of rangeClassCastException
- if the value at the specified position is not assignable to the JsonArray type
-
getJsonNumber
JsonNumber getJsonNumber(int index)
Returns the number value at the specified position in this array. This is a convenience method for(JsonNumber)get(index)
.- Parameters:
index
- index of the value to be returned- Returns:
- the value at the specified position in this array
- Throws:
IndexOutOfBoundsException
- if the index is out of rangeClassCastException
- if the value at the specified position is not assignable to the JsonNumber type
-
getJsonString
JsonString getJsonString(int index)
Returns the string value at ths specified position in this array. This is a convenience method for(JsonString)get(index)
.- Parameters:
index
- index of the value to be returned- Returns:
- the value at the specified position in this array
- Throws:
IndexOutOfBoundsException
- if the index is out of rangeClassCastException
- if the value at the specified position is not assignable to the JsonString type
-
getValuesAs
<T extends JsonValue> List<T> getValuesAs(Class<T> clazz)
Returns a list view of the specified type for the array. This method does not verify if there is a value of wrong type in the array. Providing this typesafe view dynamically may cause a program fail with aClassCastException
, if there is a value of wrong type in this array. Unfortunately, the exception can occur at any time after this method returns.- Type Parameters:
T
- The type of the List for the array- Parameters:
clazz
- a JsonValue type- Returns:
- a list view of the specified type
-
getValuesAs
default <T,K extends JsonValue> List<T> getValuesAs(Function<K,T> func)
Returns a list view for the array. The value and the type of the elements in the list is specified by thefunc
argument.This method can be used to obtain a list of the unwrapped types, such as
or a list of simple projections, such asList<String> strings = ary1.getValuesAs(JsonString::getString); List<Integer> ints = ary2.getValuesAs(JsonNumber::intValue);
List<Integer> stringsizes = ary1.getValueAs((JsonString v)->v.getString().length();
- Type Parameters:
K
- The element type (must be a subtype of JsonValue) of this JsonArray.T
- The element type of the returned List- Parameters:
func
- The function that maps the elements of this JsonArray to the target elements.- Returns:
- A List of the specified values and type.
- Throws:
ClassCastException
- if theJsonArray
contains a value of wrong type- Since:
- 1.1
-
getString
String getString(int index)
A convenience method forgetJsonString(index).getString()
.- Parameters:
index
- index of theJsonString
value- Returns:
- the String value at the specified position
- Throws:
IndexOutOfBoundsException
- if the index is out of rangeClassCastException
- if the value at the specified position is not assignable toJsonString
-
getString
String getString(int index, String defaultValue)
Returns theString
value ofJsonString
at the specified position in this JSON array values. IfJsonString
is found, itsJsonString.getString()
is returned. Otherwise, the specified default value is returned.- Parameters:
index
- index of theJsonString
valuedefaultValue
- the String to return if theJsonValue
at the specified position is not aJsonString
- Returns:
- the String value at the specified position in this array, or the specified default value
-
getInt
int getInt(int index)
A convenience method forgetJsonNumber(index).intValue()
.- Parameters:
index
- index of theJsonNumber
value- Returns:
- the int value at the specified position
- Throws:
IndexOutOfBoundsException
- if the index is out of rangeClassCastException
- if the value at the specified position is not assignable toJsonNumber
-
getInt
int getInt(int index, int defaultValue)
Returns the int value of theJsonNumber
at the specified position. If the value at that position is aJsonNumber
, this method returnsJsonNumber.intValue()
. Otherwise this method returns the specified default value.- Parameters:
index
- index of theJsonNumber
valuedefaultValue
- the int value to return if theJsonValue
at the specified position is not aJsonNumber
- Returns:
- the int value at the specified position in this array, or the specified default value
-
getBoolean
boolean getBoolean(int index)
Returns the boolean value at the specified position. If the value at the specified position isJsonValue.TRUE
this method returnstrue
. If the value at the specified position isJsonValue.FALSE
this method returnsfalse
.- Parameters:
index
- index of the JSON boolean value- Returns:
- the boolean value at the specified position
- Throws:
IndexOutOfBoundsException
- if the index is out of rangeClassCastException
- if the value at the specified position is notJsonValue.TRUE
orJsonValue.FALSE
-
getBoolean
boolean getBoolean(int index, boolean defaultValue)
Returns the boolean value at the specified position. If the value at the specified position isJsonValue.TRUE
this method returnstrue
. If the value at the specified position isJsonValue.FALSE
this method returnsfalse
. Otherwise this method returns the specified default value.- Parameters:
index
- index of the JSON boolean valuedefaultValue
- the boolean value to return if theJsonValue
at the specified position is neither TRUE nor FALSE- Returns:
- the boolean value at the specified position, or the specified default value
-
isNull
boolean isNull(int index)
Returnstrue
if the value at the specified location in this array isJsonValue.NULL
.- Parameters:
index
- index of the JSON null value- Returns:
- return true if the value at the specified location is
JsonValue.NULL
, otherwise false - Throws:
IndexOutOfBoundsException
- if the index is out of range
-
-