Module json_values
Package jsonvalues

Interface Json<T extends Json<T>>

Type Parameters:
T - Type of the container: either an object (JsObj) or an array (JsArray)
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 either a JsObj or a JsArray. JSON data is modeled as a set of key-value pairs (JsPair) with keys represented by JsPath and values as JsValue. The structure allows for recursion.

For instance, the JSON: { "a": 1, "x": { "c": true, "d": null, "e": [false, 1, "hi"] } }

Can be seen as a set: Set[(a, 1), (x.c, true), (x.d, null), (x.e.0, false), (x.e.1, 1), (x.e.2, "hi"), (_, JsNothing)]

The special element JsNothing.NOTHING represents any other JsPath, making functions like get(JsPath) total (defined for every possible path).

JSON modification operations, such as set(JsPath, JsValue), can insert JsNothing without changing the JSON.

JSONs can also be treated as streams of pairs, enabling operations like map, filter, and reduce.

All methods throw a NullPointerException when passed null parameters, and UserError is thrown for inappropriate method calls. /** The ARRAY_AS parameter in various methods of the Json interface allows you to specify how arrays within the JSON data structure should be treated during specific operations. It provides customization options for handling arrays, giving you control over their behavior in various contexts.

JSON data structures can contain arrays, and the behavior of operations involving these arrays can vary depending on your requirements. The ARRAY_AS parameter serves as a way to define this behavior by offering different options or types, each of which affects how arrays are treated.

Common use cases for the ARRAY_AS parameter include:

  • Defining how arrays should be merged, concatenated, or otherwise combined when performing operations that involve JSON structures.
  • Specifying whether arrays should be considered equal only if they have the same elements in the same order or if the order of elements is not important.
  • Controlling how arrays are affected by operations such as union and intersection between JSON structures.

The specific values or options available for the ARRAY_AS parameter will depend on the JSON library or framework being used. Developers should refer to the documentation of the library or framework to understand the available options and their behavior.

By allowing customization of array handling, the ARRAY_AS parameter enhances the flexibility of working with JSON data, enabling developers to tailor operations to suit specific structural requirements and use cases.

Author:
Rafael Merino Garcia
See Also:

  • Method Details

    • toPrettyString

      default String toPrettyString(int indentLength)
      Converts the JSON to a pretty-printed string with the specified indentation length.
      Parameters:
      indentLength - The number of spaces to use for indentation.
      Returns:
      A pretty-printed JSON string.

    • toPrettyString

      default String toPrettyString()
      Converts the JSON to a pretty-printed string with a default indentation length of 2 spaces.
      Returns:
      A pretty-printed JSON string.
      See Also:

    • containsValue

      boolean containsValue(JsValue element)
      Checks if this JSON contains the given value in its first level.
      Parameters:
      element - The value to check for.
      Returns:
      True if this JSON contains the value, otherwise false.

    • containsPath

      default boolean containsPath(JsPath path)
      Checks if an element exists in this JSON at the given path.
      Parameters:
      path - The path to check.
      Returns:
      True if a value exists at the path, otherwise false.

    • get

      JsValue get(JsPath path)
      Gets the value located at the given path or JsNothing if it doesn't exist.
      Parameters:
      path - The path to the desired value.
      Returns:
      The value at the given path or JsNothing if it doesn't exist.

    • equals

      default boolean equals(JsValue elem, JsArray.TYPE ARRAY_AS)
      Checks if this JSON is equal to another JSON element.
      Parameters:
      elem - The JSON element to compare.
      ARRAY_AS - The type to consider arrays during comparison.
      Returns:
      True if the JSON elements are equal, otherwise false.

    • filterValues

      T filterValues(BiPredicate<? super JsPath,? super JsPrimitive> filter)
      Filters all the pairs of elements of this json, removing those that don't satisfy the given predicate.
      Parameters:
      filter - the predicate which takes as input every JsPair of this json
      Returns:
      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 satisfy the given predicate.
      Parameters:
      filter - the predicate which takes as input every JsPair of this json
      Returns:
      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 satisfy the given predicate.
      Parameters:
      filter - the predicate which takes as input every JsPair of this json
      Returns:
      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 provided 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()
      Description copied from interface: JsValue
      Returns this JsValue as a JsPrimitive.
      Specified by:
      toJsPrimitive in interface JsValue
      Returns:
      This JsValue as a JsPrimitive.

    • 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 provided 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 that specified in BigDecimal.doubleValue().
      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 that specified in BigDecimal.doubleValue().
      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.
      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.
      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.
      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.
      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 a 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 a 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()
      Determines whether this Json instance is empty, i.e., it contains no elements.
      Returns:
      true if empty, false otherwise

    • isNotEmpty

      default boolean isNotEmpty()
      Determines whether this Json instance is not empty, i.e., it contains one or more elements.
      Returns:
      false if empty, true otherwise

    • mapValues

      T mapValues(BiFunction<? super JsPath,? super JsPrimitive,? extends JsValue> fn)
      Recursively maps all the values of this JSON, replacing each value with the result of applying the given mapping function. This operation traverses the entire JSON structure.
      Parameters:
      fn - the mapping function that transforms each value
      Returns:
      a new JSON object of the same type T with the mapped values

    • mapValues

      T mapValues(Function<? super JsPrimitive,? extends JsValue> fn)
      Recursively maps all the values of this JSON, replacing each value with the result of applying the given mapping function. This operation traverses the entire JSON structure.
      Parameters:
      fn - the mapping function that transforms each value
      Returns:
      a new JSON object of the same type T with the mapped values

    • mapKeys

      T mapKeys(BiFunction<? super JsPath,? super JsValue,String> fn)
      Maps all the keys of this JSON object, recursively traversing the entire JSON structure.
      Parameters:
      fn - the mapping function that transforms each key
      Returns:
      a new JSON object of the same type T with the mapped keys

    • mapKeys

      T mapKeys(Function<? super String,String> fn)
      Maps all the keys of this JSON object, recursively traversing the entire JSON structure.
      Parameters:
      fn - the mapping function that transforms each key
      Returns:
      a new JSON object of the same type T with the mapped keys

    • mapObjs

      T mapObjs(BiFunction<? super JsPath,? super JsObj,? extends JsValue> fn)
      Maps all the JSON objects of this JSON, traversing the entire JSON if necessary.
      Parameters:
      fn - the mapping function that transforms each JSON object
      Returns:
      a new JSON object of the same type T with the mapped objects, or the same instance if no objects are found

    • mapObjs

      T mapObjs(Function<? super JsObj,? extends JsValue> fn)
      Maps all the JSON objects of this JSON, traversing the entire JSON if necessary.
      Parameters:
      fn - the mapping function that transforms each JSON object
      Returns:
      a new JSON object of the same type T with the mapped objects, or the same instance if no objects are found

    • set

      T set(JsPath path, JsValue element, JsValue padElement)
      Inserts an element at the specified path in this JSON, replacing any existing element.
      Parameters:
      path - The path to insert the element.
      element - The element to insert.
      padElement - The element to use for padding in arrays when necessary.
      Returns:
      A new JSON with the inserted element, or this instance if the head of the path is incompatible.

    • set

      default T set(JsPath path, JsValue element)
      Inserts the given element at the specified path in this JSON, replacing any existing element. If necessary, it fills empty indexes in arrays with JsNull. You have the option to use set(JsPath, JsValue, JsValue) to specify a custom padding element.
      Parameters:
      path - the path where the element will be inserted
      element - the element to be inserted
      Returns:
      a JSON object of the same type with the new element, or the same instance if the path is invalid

    • reduce

      <R> Optional<R> reduce(BinaryOperator<R> op, BiFunction<? super JsPath,? super JsPrimitive,R> map, BiPredicate<? super JsPath,? super JsPrimitive> predicate)
      Reduces the values of this JSON object that satisfy the given predicate, allowing access to the element's path. This reduction traverses the entire JSON recursively if necessary.
      Type Parameters:
      R - the type of the reduction result
      Parameters:
      op - the operator to apply to values of type R
      map - the mapping function to convert JsPath and JsPrimitive to type R
      predicate - the predicate that determines which values are included in the reduction
      Returns:
      an Optional describing the result of the reduction, or empty if no values satisfy the predicate

    • reduce

      <R> Optional<R> reduce(BinaryOperator<R> op, Function<? super JsPrimitive,R> map, Predicate<? super JsPrimitive> predicate)
      Reduces the values of this JSON object that satisfy the given predicate. This reduction traverses the entire JSON recursively if necessary.
      Type Parameters:
      R - the type of the reduction result
      Parameters:
      op - the operator to apply to values of type R
      map - the mapping function to convert JsValue to type R
      predicate - the predicate that determines which values are included in the reduction
      Returns:
      an Optional describing the result of the reduction, or empty if no values satisfy the predicate

    • delete

      T delete(JsPath path)
      Removes the element at the specified path within this immutable JSON object, if it exists. Returns a new JSON object with the element removed, or the original JSON object if the element does not exist.
      Parameters:
      path - the path specifying the element to be removed
      Returns:
      a new JSON object with the specified element removed, or the original JSON object if the element does not exist

    • size

      int size()
      Returns the number of elements in the first level of this JSON object or array. This method provides the count of elements directly contained in the JSON object or array.
      Returns:
      the number of elements in the first level of this JSON object or array

    • stream

      Stream<JsPair> stream()
      Returns a stream over all the key-value pairs JsPair of elements in this JSON object. This method provides a way to traverse and operate on the key-value pairs within the JSON object.
      Returns:
      a Stream over all the key-value pairs (JsPairs) in this JSON object

    • serialize

      default void serialize(OutputStream outputstream)
      Serializes this JSON object into the given output stream, effectively converting it into its serialized form. Serialization is the process of converting a JSON object into a byte stream representation. The serialized JSON can be written to an output stream, such as a file or network socket.
      Parameters:
      outputstream - the output stream to which the JSON object will be serialized

    • serialize

      default byte[] serialize()
      Serializes this JSON object into a byte array, effectively converting it into its serialized form as a byte sequence. Serialization is the process of converting a JSON object into a byte stream representation. This method returns the serialized JSON as a byte array.
      Returns:
      a byte array containing the serialized representation of this JSON object

    • union

      T union(T that, JsArray.TYPE ARRAY_AS)
      Computes the union of this JSON and another JSON object 'that' with respect to the given array merging strategy. The union of two JSON objects is another JSON object that contains all the key-value pairs present in either 'this' or 'that'. If a key is present in both JSON objects, the value from 'this' will be used. Array merging strategy 'ARRAY_AS' determines how arrays are merged during the union operation. If 'ARRAY_AS' is 'MERGE', arrays are merged by concatenating elements. If 'ARRAY_AS' is 'REPLACE', arrays in 'this' will be replaced with arrays from 'that'.
      Parameters:
      that - the other JSON object to compute the union with
      ARRAY_AS - the array merging strategy, either 'MERGE' or 'REPLACE'
      Returns:
      a new JSON object representing the union of 'this' and 'that'

    • intersection

      T intersection(T that, JsArray.TYPE ARRAY_AS)
      Computes the intersection of this JSON and another JSON object 'that' with respect to the given array merging strategy. The intersection of two JSON objects is another JSON object that contains only the key-value pairs present in both 'this' and 'that'. Array merging strategy 'ARRAY_AS' determines how arrays are merged during the intersection operation. If 'ARRAY_AS' is 'MERGE', arrays are merged by concatenating elements. If 'ARRAY_AS' is 'REPLACE', arrays in 'this' will be replaced with arrays from 'that'.
      Parameters:
      that - the other JSON object to compute the intersection with
      ARRAY_AS - the array merging strategy, either 'MERGE' or 'REPLACE'
      Returns:
      a new JSON object representing the intersection of 'this' and 'that'