javax.json

## 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 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`.

  Author:
    Jitendra Kotamraju

- - ### Nested Class Summary

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

      `JsonValue.ValueType`

  - ### Field Summary

    - ### Fields inherited from interface javax.json.JsonValue

      `FALSE, NULL, TRUE`

  - ### Method Summary

    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 a view of the specified type 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.JsonValue

      `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, retainAll, set, size, 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 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 a 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.
      Parameters:
        `clazz` - a JsonValue type
      Returns:
        a list view of the specified type

    - #### 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
      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
      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
      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

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.