Package rife.json

Class JsonArray

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractList<E>

java.util.ArrayList<Object>

rife.json.JsonArray

All Implemented Interfaces:

Serializable, Cloneable, Iterable<Object>, Collection<Object>, List<Object>, RandomAccess

public class JsonArray
extends ArrayList<Object>

A JsonArray represents a JSON array as a regular list, with additional fluent construction methods and typed value retrieval.

The values that are stored are plain Java instances: String, Long, Double, Boolean, null, JsonObject and JsonArray.

All the mutation methods convert maps, collections and arrays to JsonObject and JsonArray instances, while values that are assigned through sublist views bypass this conversion.

The typed retrieval methods are lenient. Strings will be parsed into the requested numeric or boolean types and numbers will be truncated when narrower types are requested. Elements that are null return zero-like values.

Since:

1.10

See Also:

• Json
• JsonObject
• Serialized Form

Field Summary

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

Constructors

Constructor	Description
JsonArray()	Creates an empty JSON array.
JsonArray(Collection<?> elements)	Creates a JSON array with the elements of a collection.

Method Summary

Modifier and Type	Method	Description
void	add(int index, Object value)
boolean	add(Object value)
boolean	addAll(int index, Collection<?> elements)
boolean	addAll(Collection<?> elements)
JsonArray	append(Object value)	Appends a value to this JSON array.
JsonArray	array(JsonArrayAction action)	Appends a new nested JSON array that is constructed by the provided action.
JsonArray	getArray(int index)	Retrieves an element as a nested JSON array.
boolean	getBoolean(int index)	Retrieves an element as a boolean.
Date	getDate(int index)	Retrieves an element as a date.
double	getDouble(int index)	Retrieves an element as a double.
Instant	getInstant(int index)	Retrieves an element as an instant.
int	getInt(int index)	Retrieves an element as an int.
LocalDate	getLocalDate(int index)	Retrieves an element as a local date.
LocalDateTime	getLocalDateTime(int index)	Retrieves an element as a local date and time.
LocalTime	getLocalTime(int index)	Retrieves an element as a local time.
long	getLong(int index)	Retrieves an element as a long.
JsonObject	getObject(int index)	Retrieves an element as a nested JSON object.
String	getString(int index)	Retrieves an element as a string.
JsonArray	object(JsonObjectAction action)	Appends a new nested JSON object that is constructed by the provided action.
static JsonArray	parse(String json)	Parses a JSON document that is expected to be a JSON array.
void	prettyPrint(Writer writer)	Serializes this JSON array in its multi-line indented representation to a writer.
void	print(Writer writer)	Serializes this JSON array in its compact representation to a writer.
void	replaceAll(UnaryOperator<Object> operator)
Object	set(int index, Object value)
<T> List<T>	toBeanList(Class<T> beanClass)	Converts the elements of this JSON array into a list of beans.
String	toPrettyString()	Serializes this JSON array into its multi-line indented string representation.
String	toString()	Serializes this JSON array into its compact string representation.

Methods inherited from class java.util.ArrayList

clear, clone, contains, ensureCapacity, equals, forEach, get, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, removeIf, removeRange, retainAll, size, sort, spliterator, subList, toArray, toArray, trimToSize

Methods inherited from class java.util.AbstractCollection

containsAll

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

parallelStream, stream, toArray

Methods inherited from interface java.util.List

containsAll

Constructor Details

JsonArray

public JsonArray()

Creates an empty JSON array.

Elements can afterwards be added with the regular list methods or with the fluent construction methods.

Since:

1.10

See Also:

• JsonArray(Collection)
• append(Object)

JsonArray

public JsonArray(Collection<?> elements)

Creates a JSON array with the elements of a collection.

This constructor will copy over the elements of the provided collection in the collection's iteration order, while nested maps, collections and arrays are converted to JsonObject and JsonArray instances.

Parameters:

elements - the collection whose elements become the elements of this JSON array, in the collection's iteration order

Since:

1.10

See Also:

• JsonArray()

Method Details

parse

public static JsonArray parse(String json)

Parses a JSON document that is expected to be a JSON array.

This method does the same as Json.parseArray(String) and additionally enables RIFE2's standard conversions to convert strings to JsonArray instances.

Parameters:

json - the JSON document to parse

Returns:

the parsed JsonArray

Throws:

JsonParseException - when the document couldn't be parsed or isn't a JSON array

Since:

1.10

See Also:

• Json.parseArray(String)

append

public JsonArray append(Object value)

Appends a value to this JSON array.

Maps, collections and arrays are converted to JsonObject and JsonArray instances so that the typed retrieval methods work on them too.

Parameters:

value - the value to append

Returns:

this JsonArray instance

Since:

1.10

See Also:

• object(JsonObjectAction)
• array(JsonArrayAction)

add

public boolean add(Object value)

Specified by:

add in interface Collection<Object>

Specified by:

add in interface List<Object>

Overrides:

add in class ArrayList<Object>

add

public void add(int index,
 Object value)

Specified by:

add in interface List<Object>

Overrides:

add in class ArrayList<Object>

addAll

public boolean addAll(Collection<?> elements)

Specified by:

addAll in interface Collection<Object>

Specified by:

addAll in interface List<Object>

Overrides:

addAll in class ArrayList<Object>

addAll

public boolean addAll(int index,
 Collection<?> elements)

Specified by:

addAll in interface List<Object>

Overrides:

addAll in class ArrayList<Object>

set

public Object set(int index,
 Object value)

Specified by:

set in interface List<Object>

Overrides:

set in class ArrayList<Object>

replaceAll

public void replaceAll(UnaryOperator<Object> operator)

Specified by:

replaceAll in interface List<Object>

Overrides:

replaceAll in class ArrayList<Object>

object

public JsonArray object(JsonObjectAction action)

Appends a new nested JSON object that is constructed by the provided action.

This method will create the nested JsonObject for you and hand it to the action so that you can populate it inline, after which it is appended to this JSON array.

Parameters:

action - the action that constructs the nested object

Returns:

this JsonArray instance

Since:

1.10

See Also:

• array(JsonArrayAction)
• append(Object)

array

public JsonArray array(JsonArrayAction action)

Appends a new nested JSON array that is constructed by the provided action.

This method will create the nested JsonArray for you and hand it to the action so that you can populate it inline, after which it is appended to this JSON array.

Parameters:

action - the action that constructs the nested array

Returns:

this JsonArray instance

Since:

1.10

See Also:

• object(JsonObjectAction)
• append(Object)

getString

public String getString(int index)

Retrieves an element as a string.

Parameters:

index - the index of the element

Returns:

the element value as a string; or

null if the element is null

Since:

1.10

See Also:

• getInt(int)
• getLong(int)
• getDouble(int)
• getBoolean(int)

getInt

public int getInt(int index)

Retrieves an element as an int.

Strings will be parsed and wider numbers will be truncated so that they fit into an int.

Parameters:

index - the index of the element

Returns:

the element value as an int; or

0 if the element is null

Throws:

NumberFormatException - when the value is a string that can't be parsed into this type

IndexOutOfBoundsException - when the index is out of range

Since:

1.10

See Also:

• getString(int)
• getLong(int)
• getDouble(int)

getLong

public long getLong(int index)

Retrieves an element as a long.

Strings will be parsed and floating point numbers will be truncated so that they fit into a long.

Parameters:

index - the index of the element

Returns:

the element value as a long; or

0L if the element is null

Throws:

NumberFormatException - when the value is a string that can't be parsed into this type

IndexOutOfBoundsException - when the index is out of range

Since:

1.10

See Also:

• getString(int)
• getInt(int)
• getDouble(int)

getDouble

public double getDouble(int index)

Retrieves an element as a double.

Strings will be parsed so that they can be used as a double too.

Parameters:

index - the index of the element

Returns:

the element value as a double; or

0.0 if the element is null

Throws:

NumberFormatException - when the value is a string that can't be parsed into this type

IndexOutOfBoundsException - when the index is out of range

Since:

1.10

See Also:

• getString(int)
• getInt(int)
• getLong(int)

getBoolean

public boolean getBoolean(int index)

Retrieves an element as a boolean.

Strings will be parsed so that they can be used as a boolean too.

Parameters:

index - the index of the element

Returns:

the element value as a boolean; or

false if the element is null

Since:

1.10

See Also:

• getString(int)

getDate

public Date getDate(int index)

Retrieves an element as a date.

ISO 8601 strings and epoch millisecond numbers are converted through RIFE2's standard conversions.

Parameters:

index - the index of the element

Returns:

the element value as a Date; or

null if the element is null

Throws:

IllegalArgumentException - when the value can't be converted into this type

IndexOutOfBoundsException - when the index is out of range

Since:

1.10

See Also:

• getInstant(int)
• getLocalDate(int)
• getLocalDateTime(int)
• getLocalTime(int)

getInstant

public Instant getInstant(int index)

Retrieves an element as an instant.

ISO 8601 strings and epoch millisecond numbers are converted through RIFE2's standard conversions.

Parameters:

index - the index of the element

Returns:

the element value as an Instant; or

null if the element is null

Throws:

IllegalArgumentException - when the value can't be converted into this type

IndexOutOfBoundsException - when the index is out of range

Since:

1.10

See Also:

• getDate(int)
• getLocalDate(int)
• getLocalDateTime(int)
• getLocalTime(int)

getLocalDate

public LocalDate getLocalDate(int index)

Retrieves an element as a local date.

ISO 8601 strings and epoch millisecond numbers are converted through RIFE2's standard conversions.

Parameters:

index - the index of the element

Returns:

the element value as a LocalDate; or

null if the element is null

Throws:

IllegalArgumentException - when the value can't be converted into this type

IndexOutOfBoundsException - when the index is out of range

Since:

1.10

See Also:

• getDate(int)
• getInstant(int)
• getLocalDateTime(int)
• getLocalTime(int)

getLocalDateTime

public LocalDateTime getLocalDateTime(int index)

Retrieves an element as a local date and time.

ISO 8601 strings and epoch millisecond numbers are converted through RIFE2's standard conversions.

Parameters:

index - the index of the element

Returns:

the element value as a LocalDateTime; or

null if the element is null

Throws:

IllegalArgumentException - when the value can't be converted into this type

IndexOutOfBoundsException - when the index is out of range

Since:

1.10

See Also:

• getDate(int)
• getInstant(int)
• getLocalDate(int)
• getLocalTime(int)

getLocalTime

public LocalTime getLocalTime(int index)

Retrieves an element as a local time.

ISO 8601 strings and epoch millisecond numbers are converted through RIFE2's standard conversions.

Parameters:

index - the index of the element

Returns:

the element value as a LocalTime; or

null if the element is null

Throws:

IllegalArgumentException - when the value can't be converted into this type

IndexOutOfBoundsException - when the index is out of range

Since:

1.10

See Also:

• getDate(int)
• getInstant(int)
• getLocalDate(int)
• getLocalDateTime(int)

toBeanList

public <T> List<T> toBeanList(Class<T> beanClass)

Converts the elements of this JSON array into a list of beans.

Each element is converted with the same rules as Json.toBean(rife.json.JsonObject, java.lang.Class<T>), while elements that are null stay null.

Parameters:

beanClass - the class of the beans

Returns:

the list with a bean instance for each element

Since:

1.10

See Also:

• Json.toBeanList(JsonArray, Class)

getObject

public JsonObject getObject(int index)

Retrieves an element as a nested JSON object.

Parameters:

index - the index of the element

Returns:

the nested JsonObject; or

null if the element is null

Throws:

ClassCastException - when the value is of another type

IndexOutOfBoundsException - when the index is out of range

Since:

1.10

See Also:

• getArray(int)
• object(JsonObjectAction)

getArray

public JsonArray getArray(int index)

Retrieves an element as a nested JSON array.

Parameters:

index - the index of the element

Returns:

the nested JsonArray; or

null if the element is null

Throws:

ClassCastException - when the value is of another type

IndexOutOfBoundsException - when the index is out of range

Since:

1.10

See Also:

• getObject(int)
• array(JsonArrayAction)

toString

public String toString()

Serializes this JSON array into its compact string representation.

Overrides:

toString in class AbstractCollection<Object>

Returns:

the JSON string

Since:

1.10

See Also:

• toPrettyString()
• print(Writer)

toPrettyString

public String toPrettyString()

Serializes this JSON array into its multi-line indented string representation.

Returns:

the pretty-printed JSON string

Since:

1.10

See Also:

• toString()
• prettyPrint(Writer)

print

public void print(Writer writer)
           throws IOException

Serializes this JSON array in its compact representation to a writer.

The output is streamed so that no intermediate string has to be built up in memory.

Parameters:

writer - the writer to serialize to

Throws:

IOException - when an error occurred while writing

Since:

1.10

See Also:

• prettyPrint(Writer)
• toString()

prettyPrint

public void prettyPrint(Writer writer)
                 throws IOException

Serializes this JSON array in its multi-line indented representation to a writer.

The output is streamed so that no intermediate string has to be built up in memory.

Parameters:

writer - the writer to serialize to

Throws:

IOException - when an error occurred while writing

Since:

1.10

See Also:

• print(Writer)
• toPrettyString()