Class JsonArray

java.lang.Object
io.vertx.core.json.JsonArray
All Implemented Interfaces:
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 Details

    • 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 Details

    • 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 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
      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)
      Returns true if this JSON Array contains the specified value. More formally, returns true if and only if this JSON array contains at least one entry entry such that Objects.equals(value, entry).
      Parameters:
      value - the value whose presence in this JSON array is to be tested
      Returns:
      true if it contains the value, false if not

    • indexOf

      public int indexOf(Object value)
      Returns the index of the last occurrence of the specified value in this JSON array, or -1 if this JSON array does not contain the value. More formally, returns the highest index i such that Objects.equals(value, get(i)), or -1 if there is no such index.
      Parameters:
      value - the value whose index in this JSON array is to be returned
      Returns:
      the index of the value in the array, or -1 if the value is not in the array

    • 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(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 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 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 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