io.vertx.core.json

## Class JsonArray

- java.lang.Object
- - io.vertx.core.json.JsonArray

- All Implemented Interfaces:
    io.vertx.core.shareddata.impl.ClusterSerializable, Shareable, Iterable<Object>

      public class JsonArray
      extends Object
      implements Iterable<Object>, ClusterSerializable, Shareable

  A representation of a JSON array in Java. Unlike some other languages Java does not have a native understanding of JSON. To enable JSON to be used easily in Vert.x code we use this class to encapsulate the notion of a JSON array. The implementation adheres to the RFC-7493 to support Temporal data types as well as binary data. Please see the documentation for more information.
  Author:
    Tim Fox

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `JsonArray()` Create an empty instance
    `JsonArray(Buffer buf)` Create an instance from a Buffer of JSON.
    `JsonArray(List list)` Create an instance from a List.
    `JsonArray(String json)` Create an instance from a String of JSON, this string must be a valid array otherwise an exception will be thrown.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `JsonArray` | `add(int pos, Object value)` Add an Object to the JSON array at given position `pos`.
    `JsonArray` | `add(Object value)` Add an Object to the JSON array.
    `JsonArray` | `addAll(JsonArray array)` Appends all of the elements in the specified array to the end of this JSON array.
    `JsonArray` | `addNull()` Add a null value to the JSON array.
    `JsonArray` | `clear()` Remove all entries from the JSON array
    `boolean` | `contains(Object value)` Does the JSON array contain the specified value? This method will scan the entire array until it finds a value or reaches the end.
    `JsonArray` | `copy()` Deep copy of the JSON array.
    `JsonArray` | `copy(java.util.function.Function<Object,?> cloner)` Deep copy of the JSON array.
    `String` | `encode()` Encode the JSON array to a string
    `String` | `encodePrettily()` Encode the JSON array prettily as a string
    `boolean` | `equals(Object o)`
    `byte[]` | `getBinary(int pos)` Get the byte[] at position `pos` in the array.
    `Boolean` | `getBoolean(int pos)` Get the Boolean at position `pos` in the array,
    `Buffer` | `getBuffer(int pos)` Get the Buffer at position `pos` in the array.
    `Double` | `getDouble(int pos)` Get the Double at position `pos` in the array,
    `Float` | `getFloat(int pos)` Get the Float at position `pos` in the array,
    `java.time.Instant` | `getInstant(int pos)` Get the Instant at position `pos` in the array.
    `Integer` | `getInteger(int pos)` Get the Integer at position `pos` in the array,
    `JsonArray` | `getJsonArray(int pos)` Get the JsonArray at position `pos` in the array.
    `JsonObject` | `getJsonObject(int pos)` Get the JsonObject at position `pos` in the array.
    `List` | `getList()` Get the underlying `List` as is.
    `Long` | `getLong(int pos)` Get the Long at position `pos` in the array,
    `Number` | `getNumber(int pos)` Get the Number at position `pos` in the array,
    `String` | `getString(int pos)` Get the String at position `pos` in the array,
    `Object` | `getValue(int pos)` Get the value with the specified key, as an Object with types respecting the limitations of JSON.
    `int` | `hashCode()`
    `boolean` | `hasNull(int pos)` Is there a null value at position pos?
    `boolean` | `isEmpty()` Are there zero items in this JSON array?
    `Iterator<Object>` | `iterator()` Get an Iterator over the values in the JSON array
    `static JsonArray` | `of(Object... values)` Create a JsonArray containing an arbitrary number of values.
    `int` | `readFromBuffer(int pos, Buffer buffer)` Method invoked when deserializing bytes to this instance.
    `Object` | `remove(int pos)` Remove the value at the specified position in the JSON array.
    `boolean` | `remove(Object value)` Remove the specified value from the JSON array.
    `JsonArray` | `set(int pos, Object value)` Set an Object to the JSON array at position `pos`.
    `JsonArray` | `setNull(int pos)` Set a null value to the JSON array at position `pos`.
    `int` | `size()` Get the number of values in this JSON array
    `java.util.stream.Stream<Object>` | `stream()` Get a Stream over the entries in the JSON array.
    `Buffer` | `toBuffer()` Encode this JSON object as buffer.
    `String` | `toString()`
    `void` | `writeToBuffer(Buffer buffer)` Method invoked when serializing this instance.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### Constructor Detail

    - #### JsonArray

          public JsonArray(String json)

      Create an instance from a String of JSON, this string must be a valid array otherwise an exception will be thrown.

      If you are unsure of the value, you should use instead `Json.decodeValue(String)` and check the result is a JSON array.
      Parameters:
        `json` - the string of JSON

    - #### JsonArray

          public JsonArray()

      Create an empty instance

    - #### JsonArray

          public JsonArray(List list)

      Create an instance from a List. The List is not copied.
      Parameters:
        `list` - the underlying backing list

    - #### JsonArray

          public JsonArray(Buffer buf)

      Create an instance from a Buffer of JSON.
      Parameters:
        `buf` - the buffer of JSON.

  - ### Method Detail

    - #### of

          public static JsonArray of(Object... values)

      Create a JsonArray containing an arbitrary number of values.
      Parameters:
        `values` - The objects into JsonArray.
      Throws:
        `NullPointerException` - if the args is null.

    - #### getString

          public String getString(int pos)

      Get the String at position `pos` in the array,
      Parameters:
        `pos` - the position in the array
      Returns:
        the String (or String representation), or null if a null value present

    - #### getNumber

          public Number getNumber(int pos)

      Get the Number at position `pos` in the array,
      Parameters:
        `pos` - the position in the array
      Returns:
        the Number, or null if a null value present
      Throws:
        `ClassCastException` - if the value is not a Number

    - #### getInteger

          public Integer getInteger(int pos)

      Get the Integer at position `pos` in the array,
      Parameters:
        `pos` - the position in the array
      Returns:
        the Integer, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to Integer

    - #### getLong

          public Long getLong(int pos)

      Get the Long at position `pos` in the array,
      Parameters:
        `pos` - the position in the array
      Returns:
        the Long, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to Long

    - #### getDouble

          public Double getDouble(int pos)

      Get the Double at position `pos` in the array,
      Parameters:
        `pos` - the position in the array
      Returns:
        the Double, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to Double

    - #### getFloat

          public Float getFloat(int pos)

      Get the Float at position `pos` in the array,
      Parameters:
        `pos` - the position in the array
      Returns:
        the Float, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to Float

    - #### getBoolean

          public Boolean getBoolean(int pos)

      Get the Boolean at position `pos` in the array,
      Parameters:
        `pos` - the position in the array
      Returns:
        the Boolean, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to Integer

    - #### getJsonObject

          public JsonObject getJsonObject(int pos)

      Get the JsonObject at position `pos` in the array.
      Parameters:
        `pos` - the position in the array
      Returns:
        the JsonObject, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to JsonObject

    - #### getJsonArray

          public JsonArray getJsonArray(int pos)

      Get the JsonArray at position `pos` in the array.
      Parameters:
        `pos` - the position in the array
      Returns:
        the Integer, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to JsonArray

    - #### getBinary

          public byte[] getBinary(int pos)

      Get the byte[] at position `pos` in the array. JSON itself has no notion of a binary, so this method assumes there is a String value and it contains a Base64 encoded binary, which it decodes if found and returns.
      Parameters:
        `pos` - the position in the array
      Returns:
        the byte[], or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to String
        `IllegalArgumentException` - if the String value is not a legal Base64 encoded value

    - #### getBuffer

          public Buffer getBuffer(int pos)

      Get the Buffer at position `pos` in the array. JSON itself has no notion of a binary, so this method assumes there is a String value and it contains a Base64 encoded binary, which it decodes if found and returns.
      Parameters:
        `pos` - the position in the array
      Returns:
        the byte[], or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to String
        `IllegalArgumentException` - if the String value is not a legal Base64 encoded value

    - #### getInstant

          public java.time.Instant getInstant(int pos)

      Get the Instant at position `pos` in the array. JSON itself has no notion of a temporal types, this extension allows ISO 8601 string formatted dates with timezone always set to zero UTC offset, as denoted by the suffix "Z" to be parsed as a instant value. `YYYY-MM-DDTHH:mm:ss.sssZ` is the default format used by web browser scripting. This extension complies to the RFC-7493 with all the restrictions mentioned before. The method will then decode and return a instant value.
      Parameters:
        `pos` - the position in the array
      Returns:
        the Instant, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to String
        `java.time.format.DateTimeParseException` - if the String value is not a legal ISO 8601 encoded value

    - #### getValue

          public Object getValue(int pos)

      Get the value with the specified key, as an Object with types respecting the limitations of JSON.
      - `Map` will be wrapped to `JsonObject`
      - `List` will be wrapped to `JsonArray`
      - `Instant` will be converted to `String`
      - `byte[]` will be converted to `String`
      - `Buffer` will be converted to `String`
      - `Enum` will be converted to `String`
      Parameters:
        `pos` - the position in the array
      Returns:
        the Integer, or null if a null value present

    - #### hasNull

          public boolean hasNull(int pos)

      Is there a null value at position pos?
      Parameters:
        `pos` - the position in the array
      Returns:
        true if null value present, false otherwise

    - #### addNull

          public JsonArray addNull()

      Add a null value to the JSON array.
      Returns:
        a reference to this, so the API can be used fluently

    - #### add

          public JsonArray add(Object value)

      Add an Object to the JSON array.
      Parameters:
        `value` - the value
      Returns:
        a reference to this, so the API can be used fluently

    - #### add

          public JsonArray add(int pos,
                               Object value)

      Add an Object to the JSON array at given position `pos`.
      Parameters:
        `pos` - the position
        `value` - the value
      Returns:
        a reference to this, so the API can be used fluently

    - #### addAll

          public JsonArray addAll(JsonArray array)

      Appends all of the elements in the specified array to the end of this JSON array.
      Parameters:
        `array` - the array
      Returns:
        a reference to this, so the API can be used fluently

    - #### setNull

          public JsonArray setNull(int pos)

      Set a null value to the JSON array at position `pos`.
      Returns:
        a reference to this, so the API can be used fluently

    - #### set

          public JsonArray set(int pos,
                               Object value)

      Set an Object to the JSON array at position `pos`.
      Parameters:
        `pos` - position in the array
        `value` - the value
      Returns:
        a reference to this, so the API can be used fluently

    - #### contains

          public boolean contains(Object value)

      Does the JSON array contain the specified value? This method will scan the entire array until it finds a value or reaches the end.
      Parameters:
        `value` - the value
      Returns:
        true if it contains the value, false if not

    - #### remove

          public boolean remove(Object value)

      Remove the specified value from the JSON array. This method will scan the entire array until it finds a value or reaches the end.
      Parameters:
        `value` - the value to remove
      Returns:
        true if it removed it, false if not found

    - #### remove

          public Object remove(int pos)

      Remove the value at the specified position in the JSON array.
      Parameters:
        `pos` - the position to remove the value at
      Returns:
        the removed value if removed, null otherwise. If the value is a Map, a `JsonObject` is built from this Map and returned. It the value is a List, a `JsonArray` is built form this List and returned.

    - #### size

          public int size()

      Get the number of values in this JSON array
      Returns:
        the number of items

    - #### isEmpty

          public boolean isEmpty()

      Are there zero items in this JSON array?
      Returns:
        true if zero, false otherwise

    - #### getList

          public List getList()

      Get the underlying `List` as is. This list may contain values that are not the types returned by the `JsonArray` and with an unpredictable representation of the value, e.g you might get a JSON object as a `JsonObject` or as a `Map`.
      Returns:
        the underlying List.

    - #### clear

          public JsonArray clear()

      Remove all entries from the JSON array
      Returns:
        a reference to this, so the API can be used fluently

    - #### iterator

          public Iterator<Object> iterator()

      Get an Iterator over the values in the JSON array
      Specified by:
        `iterator` in interface `Iterable<Object>`
      Returns:
        an iterator

    - #### encode

          public String encode()

      Encode the JSON array to a string
      Returns:
        the string encoding

    - #### toBuffer

          public Buffer toBuffer()

      Encode this JSON object as buffer.
      Returns:
        the buffer encoding.

    - #### encodePrettily

          public String encodePrettily()

      Encode the JSON array prettily as a string
      Returns:
        the string encoding

    - #### copy

          public JsonArray copy()

      Deep copy of the JSON array.
      Specified by:
        `copy` in interface `Shareable`
      Returns:
        a copy where all elements have been copied recursively
      Throws:
        `IllegalStateException` - when a nested element cannot be copied

    - #### copy

          public JsonArray copy(java.util.function.Function<Object,?> cloner)

      Deep copy of the JSON array.

      Unlike `copy()` that can fail when an unknown element cannot be copied, this method delegates the copy of such element to the `cloner` function and will not fail.

      Parameters:
        `cloner` - a function that copies custom values not supported by the JSON implementation
      Returns:
        a copy where all elements have been copied recursively

    - #### stream

          public java.util.stream.Stream<Object> stream()

      Get a Stream over the entries in the JSON array. The values in the stream will follow the same rules as defined in `getValue(int)`, respecting the JSON requirements. To stream the raw values, use the storage object stream instead:

             jsonArray
               .getList()
               .stream()

      Returns:
        a Stream

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### writeToBuffer

          public void writeToBuffer(Buffer buffer)

      Description copied from interface: `ClusterSerializable`
      Method invoked when serializing this instance.
      Specified by:
        `writeToBuffer` in interface `io.vertx.core.shareddata.impl.ClusterSerializable`
      Parameters:
        `buffer` - the `Buffer` where the serialized bytes must be written to

    - #### readFromBuffer

          public int readFromBuffer(int pos,
                                    Buffer buffer)

      Description copied from interface: `ClusterSerializable`
      Method invoked when deserializing bytes to this instance.
      Specified by:
        `readFromBuffer` in interface `io.vertx.core.shareddata.impl.ClusterSerializable`
      Parameters:
        `pos` - the position where to start reading the `buffer`
        `buffer` - the `Buffer` where the serialized bytes must be read from
      Returns:
        the position after the last serialized byte

Copyright © 2023 Eclipse. All rights reserved.