Module json_values
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 sealed interface Json<T extends Json<T>> extends JsValue permits JsArray, JsObj
 Represents an immutable and persistent 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 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:

  • Method Details

    • 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<JsPair> 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)