jsonvalues

Interface Json<T extends Json<T>>

Type Parameters:

T - Type of container: either an object or an array

All Superinterfaces:

JsValue

All Known Implementing Classes:

JsArray, JsObj

public interface Json<T extends Json<T>>
extends JsValue

 Represents a json of type T, where T is the type of the container, either a JsObj or a JsArray.
 A json of any type can be modeled as a set of pairs Pair=(JsPath, JsValue), where:
 - a JsValue is a JsBool or JsStr or JsNumber or JsNull, or another Json like JsObj or JsArray,
 what makes the data structure recursive.
 - a JsPath represents the location of the element in the json.
 For example, the json
 {
 "a":1, "x":{ "c": true, "d":null, e: [false, 1, "hi"] }
 }
 can be seen as the following set:
 Set[(a,1), (x.c,true), (x.d,null), (x.e.0,false), (x.e.1,1), (x.e.2,"hi"), (_,NOTHING)]
 where _, which means any other JsPath, and the special element JsNothing.NOTHING, makes the
 function get(JsPath) total (defined for every possible path). Moreover, inserting JsNothing
 in a json doesn't change the json, which is very convenient when passing functions as parameters to
 put data in:
 //all the logic goes into the supplier
 Supplier<JsValue> supplier = ()-> (doesnt-put-anything-condition) ? JsNothing.NOTHING : JsInt.of(2);
 json.putIfAbsent(path,supplier)
 
 Another way to see a json is like a stream of pairs, which opens the door to doing all the operations
 that were introduced in Java 8 (map, filter, reduce, etc). For this purpose the methods stream()
 or stream() are provided.
 There are one convention on method names:
 -Methods that are suffixed with underscore traverse the whole json recursively.
 All the methods throw a NullPointerException when any of the params passed in is null. The exception
 UserError is thrown when the user calls a method inappropriately.
 

Author:

Rafael Merino Garcia

See Also:

to work with jsons that are objects, to work with jsons that are arrays

Method Summary

Modifier and Type	Method and Description
default boolean	containsPath(JsPath path) Returns true if an element exists in this json at the given path.
boolean	containsValue(JsValue element) Returns true if this json contains the given element in the first level.
T	delete(JsPath path) Removes the element in this json located at the given path, if it exists, returning the same this instance otherwise
default boolean	equals(JsValue elem, JsArray.TYPE ARRAY_AS)
T	filterKeys(BiPredicate<? super JsPath,? super JsValue> filter) Filters all the keys of this json, removing those that don't ifPredicateElse the predicate.
T	filterKeys(Predicate<? super String> filter) Filters all the keys of this json, removing those that don't ifPredicateElse the predicate.
T	filterObjs(BiPredicate<? super JsPath,? super JsObj> filter) Filters all the pair of jsons of this json, removing those that don't ifPredicateElse the predicate.
T	filterObjs(Predicate<? super JsObj> filter) Filters all the pair of jsons of this json, removing those that don't ifPredicateElse the predicate.
T	filterValues(BiPredicate<? super JsPath,? super JsPrimitive> filter) Filters all the pairs of elements of this json, removing those that don't ifPredicateElse the predicate.
T	filterValues(Predicate<? super JsPrimitive> filter) Filters all the pairs of elements of this json, removing those that don't ifPredicateElse the predicate.
JsValue	get(JsPath path) Returns the element located at the given path or JsNothing if it doesn't exist.
default JsArray	getArray(JsPath path) Returns the array located at the given path or null if it doesn't exist or it's not an array.
default JsArray	getArray(JsPath path, Supplier<JsArray> orElse) Returns the array located at the given path or the default value provided if it doesn't exist or it's not an array.
default BigDecimal	getBigDec(JsPath path) Returns the number located at the given path as a big decimal or null if it doesn't exist or it's not a decimal number.
default BigDecimal	getBigDec(JsPath path, Supplier<BigDecimal> orElse) Returns the number located at the given path as a big decimal or the default value if it doesn't exist or it's not a decimal number.
default BigInteger	getBigInt(JsPath path) Returns the number located at the given path as a big integer or null if it doesn't exist or it's not an integral number.
default BigInteger	getBigInt(JsPath path, Supplier<BigInteger> orElse) Returns the number located at the given path as a big integer or the default value if it doesn't exist or it's not an integral number.
default byte[]	getBinary(JsPath path) Returns the bytes located at the given path or null if it doesn't exist.
default byte[]	getBinary(JsPath path, Supplier<byte[]> orElse) Returns the bytes located at the given path or the default value provided if it doesn't exist.
default Boolean	getBool(JsPath path) Returns the boolean located at the given path or null if it doesn't exist.
default Boolean	getBool(JsPath path, Supplier<Boolean> orElse) Returns the boolean located at the given path or the default value provided if it doesn't exist.
default Double	getDouble(JsPath path) Returns the decimal number located at the given path as a double or null if it doesn't exist or it's not a decimal number.
default Double	getDouble(JsPath path, Supplier<Double> orElse) Returns the decimal number located at the given path as a double or the default value provided if it doesn't exist or it's not a decimal number.
default Instant	getInstant(JsPath path) Returns the instant located at the given path or null if it doesn't exist.
default Instant	getInstant(JsPath path, Supplier<Instant> orElse) Returns the instant located at the given path or the default value provided if it doesn't exist.
default Integer	getInt(JsPath path) Returns the integral number located at the given path as an integer or null if it doesn't exist or it's not an integral number or it's an integral number but doesn't fit in an integer.
default Integer	getInt(JsPath path, Supplier<Integer> orElse) Returns the integral number located at the given path as an integer or the default value provided if it doesn't exist or it's not an integral number or it's an integral number but doesn't fit in an integer.
default Long	getLong(JsPath path) Returns the integral number located at the given path as a long or null if it doesn't exist or it's not an integral number or it's an integral number but doesn't fit in a long.
default Long	getLong(JsPath path, Supplier<Long> orElse) Returns the integral number located at the given path as a long or the default value provided if it doesn't exist or it's not an integral number or it's an integral number but doesn't fit in a long.
default JsObj	getObj(JsPath path) Returns the object located at the given path or null if it doesn't exist or it's not an object.
default JsObj	getObj(JsPath path, Supplier<JsObj> orElse) Returns the object located at the given path or the default value provided if it doesn't exist or it's not an object.
default String	getStr(JsPath path) Returns the string located at the given path or null if it doesn't exist or it's not an string.
default String	getStr(JsPath path, Supplier<String> orElse) Returns the string located at the given path or the default value provided if it doesn't exist or it's not an string.
default <A> A	ifEmptyElse(Supplier<A> emptySupplier, Supplier<A> nonemptySupplier) Declarative way of implementing if(this.isEmpty()) return emptySupplier.get() else return nonEmptySupplier.get()
T	intersection(T that, JsArray.TYPE ARRAY_AS)
boolean	isEmpty() return true if there's no element in this json
default boolean	isNotEmpty() return true if this json it not empty
T	mapKeys(BiFunction<? super JsPath,? super JsValue,String> fn) Maps all the keys of this json.
T	mapKeys(Function<? super String,String> fn) Maps all the keys of this json.
T	mapObjs(BiFunction<? super JsPath,? super JsObj,? extends JsValue> fn) Maps all the jsons of this json.
T	mapObjs(Function<? super JsObj,? extends JsValue> fn) Maps all the jsons of this json.
T	mapValues(BiFunction<? super JsPath,? super JsPrimitive,? extends JsValue> fn) Maps all the values of this json.
T	mapValues(Function<? super JsPrimitive,? extends JsValue> fn) Maps all the values of this json.
<R> Optional<R>	reduce(BinaryOperator<R> op, BiFunction<? super JsPath,? super JsPrimitive,R> map, BiPredicate<? super JsPath,? super JsPrimitive> predicate) Performs a reduction on the values of this json that satisfy the predicate.
<R> Optional<R>	reduce(BinaryOperator<R> op, Function<? super JsPrimitive,R> map, Predicate<? super JsPrimitive> predicate) Performs a reduction on the values of this json that satisfy the predicate.
default byte[]	serialize() Serialize this Json into an array of bytes.
default void	serialize(OutputStream outputstream) Serializes this Json into the given output stream, no returning anything
default T	set(JsPath path, JsValue element) Inserts the element at the path in this json, replacing any existing element and filling with JsNull empty indexes in arrays when necessary.
T	set(JsPath path, JsValue element, JsValue padElement) Inserts the element at the path in this json, replacing any existing element and filling with padElement empty indexes in arrays when necessary.
int	size() Returns the number of elements in the first level of this json
Stream<fun.tuple.Pair<JsPath,JsValue>>	stream() Returns a stream over all the pairs of elements in this json object.
default JsPrimitive	toJsPrimitive()
default String	toPrettyString() Converts the string representation of this Json to a pretty print version.
default String	toPrettyString(int indentLength) Converts the string representation of this Json to a pretty print version It's indented using whitespaces
T	union(T that, JsArray.TYPE ARRAY_AS)

Methods inherited from interface jsonvalues.JsValue

id, ifNothing, ifNull, isArray, isArray, isBigDec, isBigDec, isBigInt, isBigInt, isBinary, isBool, isDecimal, isDouble, isDouble, isFalse, isInstant, isInstant, isInt, isInt, isIntegral, isJson, isJson, isLong, isLong, isNothing, isNotNothing, isNotNull, isNotNumber, isNull, isNumber, isObj, isObj, isPrimitive, isSameType, isStr, isStr, isTrue, toJsArray, toJsBigDec, toJsBigInt, toJsBinary, toJsBool, toJsDouble, toJsInstant, toJsInt, toJsLong, toJsNumber, toJsObj, toJson, toJsStr

Method Detail

toPrettyString

default String toPrettyString(int indentLength)

Converts the string representation of this Json to a pretty print version It's indented using whitespaces

Parameters:

indentLength - indented with this number of spaces

Returns:

pretty print version of the string representation of this Json

toPrettyString

default String toPrettyString()

Converts the string representation of this Json to a pretty print version. It's indented using whitespaces

Returns:

pretty print version of the string representation of this Json

containsValue

boolean containsValue(JsValue element)

Returns true if this json contains the given element in the first level.

Parameters:

element - the give element JsValue whose presence in this JsArray is to be tested

Returns:

true if this JsArray contains the JsValue

containsPath

default boolean containsPath(JsPath path)

Returns true if an element exists in this json at the given path.

Parameters:

path - the JsPath

Returns:

true if a JsValue exists at the JsPath

get

JsValue get(JsPath path)

Returns the element located at the given path or JsNothing if it doesn't exist.

Parameters:

path - the JsPath object of the element that will be returned

Returns:

the JsValue located at the given JsPath or JsNothing if it doesn't exist

equals

default boolean equals(JsValue elem,
                       JsArray.TYPE ARRAY_AS)

filterValues

T filterValues(BiPredicate<? super JsPath,? super JsPrimitive> filter)

Filters all the pairs of elements of this json, removing those that don't ifPredicateElse the predicate.

Parameters:

filter - the predicate which takes as the input every JsPair of this json

Returns:

same this instance if all the pairs satisfy the predicate or a new filtered json of the same type T

filterValues

T filterValues(Predicate<? super JsPrimitive> filter)

Filters all the pairs of elements of this json, removing those that don't ifPredicateElse the predicate.

Parameters:

filter - the predicate which takes as the input every JsPair of this json

Returns:

same this instance if all the pairs satisfy the predicate or a new filtered json of the same type T

filterKeys

T filterKeys(BiPredicate<? super JsPath,? super JsValue> filter)

Filters all the keys of this json, removing those that don't ifPredicateElse the predicate.

Parameters:

filter - the predicate which takes as the input every JsPair of this json

Returns:

same this instance if all the keys satisfy the predicate or a new filtered json of the same type T

filterKeys

T filterKeys(Predicate<? super String> filter)

Filters all the keys of this json, removing those that don't ifPredicateElse the predicate.

Parameters:

filter - the predicate which takes as the input every JsPair of this json

Returns:

same this instance if all the keys satisfy the predicate or a new filtered json of the same type T

filterObjs

T filterObjs(BiPredicate<? super JsPath,? super JsObj> filter)

Filters all the pair of jsons of this json, removing those that don't ifPredicateElse the predicate.

Parameters:

filter - the predicate which takes as the input every JsPair of this json

Returns:

same this instance if all the pairs satisfy the predicate or a new filtered json of the same type T

filterObjs

T filterObjs(Predicate<? super JsObj> filter)

Filters all the pair of jsons of this json, removing those that don't ifPredicateElse the predicate.

Parameters:

filter - the predicate which takes as the input every JsPair of this json

Returns:

same this instance if all the pairs satisfy the predicate or a new filtered json of the same type T

getArray

default JsArray getArray(JsPath path)

Returns the array located at the given path or null if it doesn't exist or it's not an array.

Parameters:

path - the path

Returns:

the JsArray located at the given JsPath or null

getArray

default JsArray getArray(JsPath path,
                         Supplier<JsArray> orElse)

Returns the array located at the given path or the default value provided if it doesn't exist or it's not an array.

Parameters:

path - the path

orElse - the default value provided

Returns:

the JsArray located at the given JsPath or null

getBigDec

default BigDecimal getBigDec(JsPath path)

Returns the number located at the given path as a big decimal or null if it doesn't exist or it's not a decimal number.

Parameters:

path - the path

Returns:

the number located at the given JsPath or null

getBigDec

default BigDecimal getBigDec(JsPath path,
                             Supplier<BigDecimal> orElse)

Returns the number located at the given path as a big decimal or the default value if it doesn't exist or it's not a decimal number.

Parameters:

path - the path

orElse - the default value

Returns:

the number located at the given JsPath or null

toJsPrimitive

default JsPrimitive toJsPrimitive()

Specified by:

toJsPrimitive in interface JsValue

getBigInt

default BigInteger getBigInt(JsPath path)

Returns the number located at the given path as a big integer or null if it doesn't exist or it's not an integral number.

Parameters:

path - the path

Returns:

the BigInteger located at the given JsPath or null

getBigInt

default BigInteger getBigInt(JsPath path,
                             Supplier<BigInteger> orElse)

Returns the number located at the given path as a big integer or the default value if it doesn't exist or it's not an integral number.

Parameters:

path - the path

orElse - the default value

Returns:

the BigInteger located at the given JsPath or null

getBool

default Boolean getBool(JsPath path)

Returns the boolean located at the given path or null if it doesn't exist.

Parameters:

path - the path

Returns:

the Boolean located at the given JsPath or null

getBool

default Boolean getBool(JsPath path,
                        Supplier<Boolean> orElse)

Returns the boolean located at the given path or the default value provided if it doesn't exist.

Parameters:

path - the path

orElse - the default value

Returns:

the Boolean located at the given JsPath or null

getBinary

default byte[] getBinary(JsPath path)

Returns the bytes located at the given path or null if it doesn't exist.

Parameters:

path - the path

Returns:

the bytes located at the given JsPath or null

getBinary

default byte[] getBinary(JsPath path,
                         Supplier<byte[]> orElse)

Returns the bytes located at the given path or the default value provided if it doesn't exist.

Parameters:

path - the path

orElse - the default value

Returns:

the bytes located at the given JsPath or null

getInstant

default Instant getInstant(JsPath path)

Returns the instant located at the given path or null if it doesn't exist.

Parameters:

path - the path

Returns:

the instant located at the given JsPath or null

getInstant

default Instant getInstant(JsPath path,
                           Supplier<Instant> orElse)

Returns the instant located at the given path or the default value provided if it doesn't exist.

Parameters:

path - the path

orElse - the default value

Returns:

the instant located at the given JsPath or null

getDouble

default Double getDouble(JsPath path)

Returns the decimal number located at the given path as a double or null if it doesn't exist or it's not a decimal number. If the number is a BigDecimal, the conversion is identical to the specified in BigDecimal.doubleValue() and in some cases it can lose information about the precision of the BigDecimal

Parameters:

path - the path

Returns:

the decimal number located at the given JsPath or null

getDouble

default Double getDouble(JsPath path,
                         Supplier<Double> orElse)

Returns the decimal number located at the given path as a double or the default value provided if it doesn't exist or it's not a decimal number. If the number is a BigDecimal, the conversion is identical to the specified in BigDecimal.doubleValue() and in some cases it can lose information about the precision of the BigDecimal

Parameters:

path - the path

orElse - the default value

Returns:

the decimal number located at the given JsPath or null

getInt

default Integer getInt(JsPath path)

Returns the integral number located at the given path as an integer or null if it doesn't exist or it's not an integral number or it's an integral number but doesn't fit in an integer.

Parameters:

path - the path

Returns:

the integral number located at the given JsPath or null

getInt

default Integer getInt(JsPath path,
                       Supplier<Integer> orElse)

Returns the integral number located at the given path as an integer or the default value provided if it doesn't exist or it's not an integral number or it's an integral number but doesn't fit in an integer.

Parameters:

path - the path

orElse - the default value

Returns:

the integral number located at the given JsPath or null

getLong

default Long getLong(JsPath path)

Returns the integral number located at the given path as a long or null if it doesn't exist or it's not an integral number or it's an integral number but doesn't fit in a long.

Parameters:

path - the path

Returns:

the integral number located at the given JsPath or null

getLong

default Long getLong(JsPath path,
                     Supplier<Long> orElse)

Returns the integral number located at the given path as a long or the default value provided if it doesn't exist or it's not an integral number or it's an integral number but doesn't fit in a long.

Parameters:

path - the path

orElse - the default value

Returns:

the integral number located at the given JsPath or null

getObj

default JsObj getObj(JsPath path,
                     Supplier<JsObj> orElse)

Returns the object located at the given path or the default value provided if it doesn't exist or it's not an object.

Parameters:

path - the path

orElse - the default value

Returns:

the JsObj located at the given JsPath or null

getObj

default JsObj getObj(JsPath path)

Returns the object located at the given path or null if it doesn't exist or it's not an object.

Parameters:

path - the path

Returns:

the JsObj located at the given JsPath or null

getStr

default String getStr(JsPath path)

Returns the string located at the given path or null if it doesn't exist or it's not an string.

Parameters:

path - the path

Returns:

the string located at the given path or null

getStr

default String getStr(JsPath path,
                      Supplier<String> orElse)

Returns the string located at the given path or the default value provided if it doesn't exist or it's not an string.

Parameters:

path - the path

orElse - the default value

Returns:

the string located at the given path or null

ifEmptyElse

default <A> A ifEmptyElse(Supplier<A> emptySupplier,
                          Supplier<A> nonemptySupplier)

Declarative way of implementing if(this.isEmpty()) return emptySupplier.get() else return nonEmptySupplier.get()

Type Parameters:

A - the type of the result

Parameters:

emptySupplier - Supplier that will produce the result if this json is empty

nonemptySupplier - Supplier that will produce the result if this json is not empty

Returns:

an object of type A

isEmpty

boolean isEmpty()

return true if there's no element in this json

Returns:

true if empty, false otherwise

isNotEmpty

default boolean isNotEmpty()

return true if this json it not empty

Returns:

false if empty, true otherwise

mapValues

T mapValues(BiFunction<? super JsPath,? super JsPrimitive,? extends JsValue> fn)

Maps all the values of this json.

Parameters:

fn - the mapping function

Returns:

a new mapped json of the same type T

mapValues

T mapValues(Function<? super JsPrimitive,? extends JsValue> fn)

Maps all the values of this json.

Parameters:

fn - the mapping function

Returns:

a new mapped json of the same type T

mapKeys

T mapKeys(BiFunction<? super JsPath,? super JsValue,String> fn)

Maps all the keys of this json.

Parameters:

fn - the mapping function

Returns:

a new mapped json of the same type T

mapKeys

T mapKeys(Function<? super String,String> fn)

Maps all the keys of this json.

Parameters:

fn - the mapping function

Returns:

a new mapped json of the same type T

mapObjs

T mapObjs(BiFunction<? super JsPath,? super JsObj,? extends JsValue> fn)

Maps all the jsons of this json.

Parameters:

fn - the mapping function

Returns:

a new mapped json of the same type T

mapObjs

T mapObjs(Function<? super JsObj,? extends JsValue> fn)

Maps all the jsons of this json.

Parameters:

fn - the mapping function

Returns:

a new mapped json of the same type T

set

T set(JsPath path,
      JsValue element,
      JsValue padElement)

Inserts the element at the path in this json, replacing any existing element and filling with padElement empty indexes in arrays when necessary.

The same instance is returned when the head of the path is a key and this is an array or the head of the path is an index and this is an object or the element is JsNothing

Parameters:

path - the JsPath object where the element will be inserted at

element - the JsValue that will be inserted

padElement - the JsValue that will be inserted in arrays when padding is necessary

Returns:

the same instance or a new json of the same type T

set

default T set(JsPath path,
              JsValue element)

Inserts the element at the path in this json, replacing any existing element and filling with JsNull empty indexes in arrays when necessary.

The same instance is returned when the head of the path is a key and this is an array or the head of the path is an index and this is an object or the element is JsNothing

Parameters:

path - the JsPath object where the element will be inserted at

element - the JsValue that will be inserted

Returns:

the same instance or a new json of the same type T

reduce

<R> Optional<R> reduce(BinaryOperator<R> op,
                       BiFunction<? super JsPath,? super JsPrimitive,R> map,
                       BiPredicate<? super JsPath,? super JsPrimitive> predicate)

Performs a reduction on the values of this json that satisfy the predicate. The reduction is performed mapping each value with the mapping function and then applying the operator

Type Parameters:

R - the type of the operands of the operator

Parameters:

op - the operator upon two objects of type R

map - the mapping function which produces an object of type R from a JsValue

predicate - the predicate that determines what JsValue will be mapped and reduced

Returns:

an Optional describing the result of the reduction

reduce

<R> Optional<R> reduce(BinaryOperator<R> op,
                       Function<? super JsPrimitive,R> map,
                       Predicate<? super JsPrimitive> predicate)

Performs a reduction on the values of this json that satisfy the predicate. The reduction is performed mapping each value with the mapping function and then applying the operator

Type Parameters:

R - the type of the operands of the operator

Parameters:

op - the operator upon two objects of type R

map - the mapping function which produces an object of type R from a JsValue

predicate - the predicate that determines what JsValue will be mapped and reduced

Returns:

an Optional describing the result of the reduction

delete

T delete(JsPath path)

Removes the element in this json located at the given path, if it exists, returning the same this instance otherwise

Parameters:

path - the given JsPath object

Returns:

a json of the same type T

size

int size()

Returns the number of elements in the first level of this json

Returns:

the number of elements in the first level of this json

stream

Stream<fun.tuple.Pair<JsPath,JsValue>> stream()

Returns a stream over all the pairs of elements in this json object.

Returns:

a Stream over all the JsPairs in this json

serialize

default void serialize(OutputStream outputstream)

Serializes this Json into the given output stream, no returning anything

Parameters:

outputstream - the output stream

serialize

default byte[] serialize()

Serialize this Json into an array of bytes. When possible, it's more efficient to work on byte level that with strings

Returns:

this Json serialized into an array of bytes

union

T union(T that,
        JsArray.TYPE ARRAY_AS)

intersection

T intersection(T that,
               JsArray.TYPE ARRAY_AS)