Package 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 JsPair=(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 streamAll()
 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:
 for example calling the method asJsStr in a JsNull instance or calling the
 method head in an empty array, etc. Normally, when that happens, a previous check is missing.
    Author:
    Rafael Merino Garcia
    See Also:
    to work with jsons that are objects, to work with jsons that are arrays

    • Method Detail

      • toPrettyString

        default String toPrettyString()
        Converts the string representation of this Json to a pretty print version
        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

      • filterValues

        T filterValues​(Predicate<? super JsPair> filter)
        Filters the pairs of elements in the first level of this json, removing those that don't ifPredicateElse the predicate.
        Parameters:
        filter - the predicate which takes as the input every JsPair in the first level of this json
        Returns:
        same this instance if all the pairs satisfy the predicate or a new filtered json of the same type T
        See Also:
        how to filter the pair of elements of the whole json and not only the first level

      • filterAllValues

        T filterAllValues​(Predicate<? super JsPair> 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
        See Also:
        how to filter the pairs of values of only the first level

      • filterKeys

        T filterKeys​(Predicate<? super JsPair> filter)
        Filters the keys in the first level of this json, removing those that don't ifPredicateElse the predicate.
        Parameters:
        filter - the predicate which takes as the input every JsPair in the first level of this json
        Returns:
        same this instance if all the keys satisfy the predicate or a new filtered json of the same type T
        See Also:
        how to filter the keys of the whole json and not only the first level

      • filterAllKeys

        T filterAllKeys​(Predicate<? super JsPair> 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
        See Also:
        how to filter the keys of only the first level

      • filterAllObjs

        T filterAllObjs​(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
        See Also:
        how to filter the pair of jsons of only the first level

      • 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

      • 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

      • 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

      • 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

      • 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

      • 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

      • 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

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

      • 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,
                       Function<? super JsPair,​R> map,
                       Predicate<? super JsPair> predicate)
        Performs a reduction on the values that satisfy the predicate in the first level of this json. 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 of of the reduction
        See Also:
        to apply the reduction in all the Json and not only in the first level

      • reduceAll

        <R> Optional<R> reduceAll​(BinaryOperator<R> op,
                          Function<? super JsPair,​R> map,
                          Predicate<? super JsPair> 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
        See Also:
        to apply the reduction only in the first level

      • 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

      • sizeAll

        default int sizeAll()
        Returns the number of all the elements in this json
        Returns:
        the number of all the elements in this json

      • streamAll

        Stream<JsPair> streamAll()
        Returns a stream over all the pairs of elements in this json object.
        Returns:
        a Stream over all the JsPairs in this json

      • times

        default long times​(JsValue e)

      • stream

        Stream<JsPair> stream()
        Returns a stream over the pairs of elements in the first level of this json object.
        Returns:
        a Stream over all the JsPairs in the first level of this json

      • timesAll

        default long timesAll​(JsValue e)

      • serialize

        default byte[] serialize()
                  throws SerializerException
        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
        Throws:
        SerializerException