Package io.vertx.core.json

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

      • 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

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • 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