JsonArray (Java(TM) EE 8 Specification APIs)

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 method JsonReader.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, and JsonValue.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 an UnsupportedOperationException.

Nested Class Summary
- Nested classes/interfaces inherited from interface javax.json.JsonValue
  JsonValue.ValueType

Field Summary
- Fields inherited from interface javax.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 and 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 for `getJsonNumber(index).intValue()`.
`int`	`getInt(int index, int defaultValue)` Returns the int value of the `JsonNumber` 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 for `getJsonString(index).getString()`.
`String`	`getString(int index, String defaultValue)` Returns the `String` value of `JsonString` 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)` Returns `true` if the value at the specified location in this array is `JsonValue.NULL`.

Methods inherited from interface javax.json.JsonStructure
getValue

Methods inherited from interface javax.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

Methods inherited from interface java.util.Collection
parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable
forEach

- 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 range
    
    ClassCastException - 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 range
    
    ClassCastException - 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 range
    
    ClassCastException - 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 range
    
    ClassCastException - 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 a ClassCastException, 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 the func argument.
    This method can be used to obtain a list of the unwrapped types, such as
```
     List<String> strings = ary1.getValuesAs(JsonString::getString);
     List<Integer> ints = ary2.getValuesAs(JsonNumber::intValue);
  
```
    or a list of simple projections, such as
```
 
     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 the JsonArray contains a value of wrong type
    
    Since:
    
    1.1
  - getString
```
String getString(int index)
```
    A convenience method for getJsonString(index).getString().
    
    Parameters:
    
    index - index of the JsonString value
    
    Returns:
    
    the String value at the specified position
    
    Throws:
    
    IndexOutOfBoundsException - if the index is out of range
    
    ClassCastException - if the value at the specified position is not assignable to JsonString
  - getString
```
String getString(int index,
                 String defaultValue)
```
    Returns the String value of JsonString at the specified position in this JSON array values. If JsonString is found, its JsonString.getString() is returned. Otherwise, the specified default value is returned.
    
    Parameters:
    
    index - index of the JsonString value
    
    defaultValue - the String to return if the JsonValue at the specified position is not a JsonString
    
    Returns:
    
    the String value at the specified position in this array, or the specified default value
  - getInt
```
int getInt(int index)
```
    A convenience method for getJsonNumber(index).intValue().
    
    Parameters:
    
    index - index of the JsonNumber value
    
    Returns:
    
    the int value at the specified position
    
    Throws:
    
    IndexOutOfBoundsException - if the index is out of range
    
    ClassCastException - if the value at the specified position is not assignable to JsonNumber
  - getInt
```
int getInt(int index,
           int defaultValue)
```
    Returns the int value of the JsonNumber at the specified position. If the value at that position is a JsonNumber, this method returns JsonNumber.intValue(). Otherwise this method returns the specified default value.
    
    Parameters:
    
    index - index of the JsonNumber value
    
    defaultValue - the int value to return if the JsonValue at the specified position is not a JsonNumber
    
    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 is JsonValue.TRUE this method returns true. If the value at the specified position is JsonValue.FALSE this method returns false.
    
    Parameters:
    
    index - index of the JSON boolean value
    
    Returns:
    
    the boolean value at the specified position
    
    Throws:
    
    IndexOutOfBoundsException - if the index is out of range
    
    ClassCastException - if the value at the specified position is not assignable to JsonValue.TRUE or JsonValue.FALSE
  - getBoolean
```
boolean getBoolean(int index,
                   boolean defaultValue)
```
    Returns the boolean value at the specified position. If the value at the specified position is JsonValue.TRUE this method returns true. If the value at the specified position is JsonValue.FALSE this method returns false. Otherwise this method returns the specified default value.
    
    Parameters:
    
    index - index of the JSON boolean value
    
    defaultValue - the boolean value to return if the JsonValue 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)
```
    Returns true if the value at the specified location in this array is JsonValue.NULL.
    
    Parameters:
    
    index - index of the JSON null value
    
    Returns:
    
    return true if the value at the specified location is JsonValue.NUL, otherwise false
    
    Throws:
    
    IndexOutOfBoundsException - if the index is out of range

Interface JsonArray

Nested Class Summary

Nested classes/interfaces inherited from interface javax.json.JsonValue

Field Summary

Fields inherited from interface javax.json.JsonValue

Method Summary

Methods inherited from interface javax.json.JsonStructure

Methods inherited from interface javax.json.JsonValue

Methods inherited from interface java.util.List

Methods inherited from interface java.util.Collection

Methods inherited from interface java.lang.Iterable

Method Detail

getJsonObject

getJsonArray

getJsonNumber

getJsonString

getValuesAs

getValuesAs

getString

getString

getInt

getInt

getBoolean

getBoolean

isNull