Module json_values
Package jsonvalues

Class JsPath

java.lang.Object
jsonvalues.JsPath
All Implemented Interfaces:
Comparable<JsPath>
public final class JsPath extends Object implements Comparable<JsPath>
 Represents the full path location of an element in a json. It's a list of Position. Exists
 two different ways to create a JsPath:
 - From a path-like string using the static factory method path(String), where the path
 follows the Json Pointer specification RFC 6901.
 In order to be able to use paths to put data in a Json, keys which name are numbers have to
 to be single-quoted:
 
 a={"0": true}
 b=[false]
 
 According to the rfc 6901:
 the pointer /0 points to true in a, and to false in b.
 In json-values it's slightly different:
 /0 points to false in b, and /'0' points to true in a.
 It's necessary to make that distinction because otherwise, there are scenarios when there is no way
 to know if the user wants to insert an array or an object:
 <script>
 JsObj obj = empty.put("/a/0/0",true)
 obj = {"a":[[true]]}       //valid result according to the rfc and json-values
 obj = {"a":{"0":{"0":true} //valid result according to the rfc
 <script>
 - By the API, using the methods fromKey(String) and fromIndex(int) to create
 a JsPath and then the methods index(int) and key(String) to append keys or indexes:
 <script>
 JsPath a = JsPath.fromKey("a").index(0).key("b") =  /a/0/b
 JsPath b = JsPath.fromIndex(0).key("a").index(0) =  /0/a/0
 <script>
 For example, given the following Json object:
 {
 "a": { "x":[ {"c": [1,2, { "": { "1" : true, " ": false, "'": 4} }]} ]}}
 "1": null,
 "": ""
 }
 / = ""                      //an empty string is a valid name for a key
 /'1' = null                 //numeric keys have to be single-quoted
 /a/x/0/c/0 = 1
 /a/x/0/c/1 = 2
 /a/x/0/c/2//'1' = true      // single quotes are only mandatory when the key is a number
 according to the rfc, # at the beginning indicates that the path is a fragment of an url and
 therefore the keys have to be url-encoded:
 #/a/x/0/c/2//+" = false     // + is url-decoded to the white-space
 #/a/x/0/c/2//%27" = 4       // %27 is url-decoded to '
 and using the API:
 <script>
 fromKey("") = ""
 fromKey("1") = null
 fromKey("a").key("x").index(0).key("c").index(0) = 1
 fromKey("a").key("x").index(0).key("c").index(1) = 2
 fromKey("a").key("x").index(0).key("c").index(2).key("").key("1") = true
 fromKey("a").key("x").index(0).key("c").index(2).key("").key(" ") = false
 fromKey("a").key("x").index(0).key("c").index(2).key("").key("'") = 4
 <script>

  • Method Summary

    Modifier and Type
    Method
    Description
    JsPath
    append(JsPath path)
    Creates a new JsPath appending the given path to this path.
    int
    compareTo(JsPath that)
    Compares this path with another given as a parameter by comparing in order each of their positions, one by one, until a result different from zero is returned or all the positions of any path are consumed.
    boolean
    contains(JsPath path)
    returns true if this path contains the given path
    boolean
    containsKey(String name)
    returns true if this path contains the given key
    JsPath
    dec()
    Returns a new path decrementing the last index by one, throwing an UserError if the last Position is not an index
    static JsPath
    empty()
    Returns the singleton empty path.
    boolean
    endsWith(JsPath path)
    returns true if this path ends with the given path.
    boolean
    endsWithKey(String key)
     
    boolean
    equals(Object that)
    Indicates whether some other object is "equal to" this path
    static JsPath
    fromIndex(int i)
    returns a path from an index
    static JsPath
    fromKey(String key)
    returns a path from a key
    int
    hashCode()
    Returns the hashcode of this path
    Position
    head()
    Returns the head of this path if it's not empty, throwing an exception otherwise.
    JsPath
    inc()
    Returns a new path incrementing the last index by one, throwing an UserError if the last Position is not an index
    JsPath
    index(int i)
    Returns a new path appending an index with the given value to the back of this path.
    JsPath
    init()
    Returns a new path without the last Position of this path.
    boolean
    isEmpty()
    Returns true if the path is empty.
    JsPath
    key(String key)
    creates a new JsPath appending the key to this JsPath.
    Position
    last()
    returns the last position this JsPath if it's not empty or an exception otherwise.
    JsPath
    mapKeys(UnaryOperator<String> map)
    Creates a new JsPath applying the given map function to every key of this path.
    static JsPath
    path(String path)
     
    JsPath
    prepend(JsPath path)
    Creates a new JsPath prepending the given path to this path.
    int
    size()
    Returns the number of Position (keys and indexes) of this JsPath
    boolean
    startsWith(JsPath path)
    returns true if this path starts with the given path.
    boolean
    startsWithKey(String key)
     
    Stream<Position>
    stream()
    Returns a sequential Stream of Positions with this path as its source.
    JsPath
    tail()
    Returns a JsPath without the head of this JsPath
    String
    toString()
    Returns a string representation of this path following the format defined in the RFC 6901 with the exception that keys which names are numbers are single-quoted.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • empty

      public static JsPath empty()
      Returns the singleton empty path.
      Returns:
      the singleton empty path

    • fromIndex

      public static JsPath fromIndex(int i)
      returns a path from an index
      Parameters:
      i - the index
      Returns:
      a new JsPath

    • path

      public static JsPath path(String path)

    • fromKey

      public static JsPath fromKey(String key)
      returns a path from a key
      Parameters:
      key - the name of the key
      Returns:
      a new JsPath

    • key

      public JsPath key(String key)
      creates a new JsPath appending the key to this JsPath.
      Parameters:
      key - the key name to be appended in raw, without encoding nor single-quoting like in path(String) )}
      Returns:
      a JsPath with the key appended to the back

    • compareTo

      public int compareTo(JsPath that)
      Compares this path with another given as a parameter by comparing in order each of their positions, one by one, until a result different from zero is returned or all the positions of any path are consumed.
      Specified by:
      compareTo in interface Comparable<JsPath>
      Parameters:
      that - the given path
      Returns:
      1 if this is greater than that, -1 if this is lower than that, 0 otherwise
      See Also:

    • head

      public Position head()
      Returns the head of this path if it's not empty, throwing an exception otherwise.
      Returns:
      the head of the path witch is an object of type Position representing and Index or a Key
      Throws:
      UserError - if the path is empty

    • stream

      public Stream<Position> stream()
      Returns a sequential Stream of Positions with this path as its source.
      Returns:
      stream of Positions of this path

    • inc

      public JsPath inc()
      Returns a new path incrementing the last index by one, throwing an UserError if the last Position is not an index
      Returns:
      a new JsPath with the last index incremented by one
      Throws:
      UserError - if the last position is not an Index

    • last

      public Position last()
      returns the last position this JsPath if it's not empty or an exception otherwise.
      Returns:
      the last position the JsPath witch is an object of type Position representing and Index or a Key
      Throws:
      UserError - if the JsPath is empty

    • index

      public JsPath index(int i)
      Returns a new path appending an index with the given value to the back of this path.
      Parameters:
      i - the value of the index to be appended
      Returns:
      a new JsPath with the Index appended to the back

    • init

      public JsPath init()
      Returns a new path without the last Position of this path.
      Returns:
      a new JsPath without the last Position of this JsPath
      Throws:
      UserError - if the JsPath is empty

    • isEmpty

      public boolean isEmpty()
      Returns true if the path is empty. An empty path represents the empty key
      Returns:
      true if this path is empty, false otherwise

    • dec

      public JsPath dec()
      Returns a new path decrementing the last index by one, throwing an UserError if the last Position is not an index
      Returns:
      a new JsPath with the last index decremented by one
      Throws:
      UserError - if the last position is not an Index

    • size

      public int size()
      Returns the number of Position (keys and indexes) of this JsPath
      Returns:
      the number of Position (keys and indexes) of this JsPath

    • tail

      public JsPath tail()
      Returns a JsPath without the head of this JsPath
      Returns:
      a JsPath without the head of this JsPath
      Throws:
      UserError - if the JsPath is empty

    • mapKeys

      public JsPath mapKeys(UnaryOperator<String> map)
      Creates a new JsPath applying the given map function to every key of this path.
      Parameters:
      map - the given map function
      Returns:
      a new JsPath with all its Keys mapped with the given function

    • append

      public JsPath append(JsPath path)
      Creates a new JsPath appending the given path to this path.
      Parameters:
      path - the given JsPath to be appended
      Returns:
      a new JsPath with the given JsPath appended to this JsPath

    • prepend

      public JsPath prepend(JsPath path)
      Creates a new JsPath prepending the given path to this path.
      Parameters:
      path - the given path to be prepended
      Returns:
      a new JsPath with the given JsPath prepended to this JsPath

    • startsWith

      public boolean startsWith(JsPath path)
      returns true if this path starts with the given path. If the given path is JsPath.empty(), it always returns true
      Parameters:
      path - the given path
      Returns:
      true if this JsPath starts with the given JsPath

    • startsWithKey

      public boolean startsWithKey(String key)

    • endsWithKey

      public boolean endsWithKey(String key)

    • endsWith

      public boolean endsWith(JsPath path)
      returns true if this path ends with the given path. If the given path is JsPath.empty(), it always returns true
      Parameters:
      path - the given path
      Returns:
      true if this JsPath ends with the given JsPath

    • hashCode

      public int hashCode()
      Returns the hashcode of this path
      Overrides:
      hashCode in class Object
      Returns:
      hashcode of this JsPath

    • equals

      public boolean equals(Object that)
      Indicates whether some other object is "equal to" this path
      Overrides:
      equals in class Object
      Parameters:
      that - the reference object with which to compare.
      Returns:
      true if that is a JsPath which represents the same location as this JsPath

    • toString

      public String toString()
      Returns a string representation of this path following the format defined in the RFC 6901 with the exception that keys which names are numbers are single-quoted. Example: /a/b/0/'1'/
      Overrides:
      toString in class Object
      Returns:
      a string representation of this JsPath following the RFC 6901

    • containsKey

      public boolean containsKey(String name)
      returns true if this path contains the given key
      Parameters:
      name - the name of the key
      Returns:
      true if this path contains the key

    • contains

      public boolean contains(JsPath path)
      returns true if this path contains the given path
      Parameters:
      path - the path
      Returns:
      true if this path contains the given path