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>, io.vertx.core.shareddata.impl.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

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
int	readFromBuffer(int pos, Buffer buffer)
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)

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

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)

Specified by:

writeToBuffer in interface io.vertx.core.shareddata.impl.ClusterSerializable

readFromBuffer

public int readFromBuffer(int pos,
                          Buffer buffer)

Specified by:

readFromBuffer in interface io.vertx.core.shareddata.impl.ClusterSerializable