Package org.eclipse.ditto.json

Interface JsonPointer

All Superinterfaces:
CharSequence, Iterable<JsonKey>
public interface JsonPointer extends CharSequence, Iterable<JsonKey>
A JSON pointer defines a path within a JSON object. This path is hierarchical like a file tree. Thus each element of this path is a sub level of it predecessor beginning at the root and ending at the leaf. For example, given the following JSON object 
    {
       "thingId": "myThing",
       "attributes": {
          "location": {
             "latitude": 47.003215,
             "longitude": 9.0815
          }
       },
       "features": {}
    }
The root of the JSON pointer "/attributes/location/longitude" is "/attributes" and the leaf is "longitude". This pointer points to the field with key "longitude" and value 9.0815 of the aforementioned JSON object.

Implementations of this interface are required to be immutable!

  • Method Details

    • empty

      @Nonnull static JsonPointer empty()
      Returns an empty JSON pointer. An empty pointer is represented by string "/".
      Returns:
      the pointer.

    • of

      static JsonPointer of(CharSequence slashDelimitedCharSequence)
      Parses the given string to obtain a new JSON pointer. This method is the inverse of toString() with one exception: both strings "/" and "" lead to an empty pointer while the string representation of an empty string is always "/".

      To support tildes in JsonKeys, they have to be escaped with "~0". For example, parsing the string "/foo/~0dum~0die~0dum/baz" would result in a JsonPointer consisting of the JsonKeys

      1. "foo",
      2. "~dum~die~dum" and
      3. "baz".
      Parameters:
      slashDelimitedCharSequence - slash-delimited string representing of a JSON pointer. The leading slash may be omitted.
      Returns:
      a new JSON pointer consisting of the JSON keys which were extracted from slashDelimitedCharSequence.
      Throws:
      NullPointerException - if slashDelimitedCharSequence is null.
      JsonPointerInvalidException - if the passed slashDelimitedCharSequence contained double slashes.

    • addLeaf

      JsonPointer addLeaf(JsonKey key)
      Creates a new JSON pointer by adding a level to this JSON pointer. For example, if this pointer is "/foo/bar" and addLevel() is called with a JSON key "baz" then the new JSON pointer is "/foo/bar/baz".
      Parameters:
      key - the new level JSON key.
      Returns:
      a new JSON pointer consisting of the old pointer extended by jsonField.
      Throws:
      NullPointerException - if key is null.

    • append

      JsonPointer append(JsonPointer pointer)
      Creates a new JSON pointer by appending the given pointer to this pointer.
      Parameters:
      pointer - the pointer to be appended to this pointer.
      Returns:
      a new JSON pointer with this pointer as root followed by pointer.
      Throws:
      NullPointerException - if pointer is null.

    • getLevelCount

      int getLevelCount()
      Returns the number of levels of this JSON pointer. For example, if the pointer is "foo/bar/baz" this method will return the value 3.
      Returns:
      the number of levels of this pointer.

    • isEmpty

      boolean isEmpty()
      Indicates whether this pointer does contain any elements or not. If the level count is zero the pointer is regarded to be empty.
      Specified by:
      isEmpty in interface CharSequence
      Returns:
      true if this pointer does not contain any elements, false else.

    • get

      Optional<JsonKey> get(int level)
      Returns the JSON key at the specified level within this JSON pointer.
      Parameters:
      level - the level of the JSON key to return.
      Returns:
      the JSON key at the specified level within this JSON pointer. If the level is outside the bounds of this pointer the result is empty.

    • getRoot

      Optional<JsonKey> getRoot()
      Returns the root JSON key of this pointer. If the level count of this pointer is one the root is the same as the leaf.
      Returns:
      the root key if this pointer is not empty.

    • getLeaf

      Optional<JsonKey> getLeaf()
      Returns the leaf JSON key of this pointer. If the level count of this pointer is one the leaf is the same as the root.
      Returns:
      the leaf key if this pointer is not empty.

    • cutLeaf

      JsonPointer cutLeaf()
      Creates a new pointer by removing the leaf element of this pointer.
      Returns:
      a new pointer which does not contain the leaf element of this pointer. If this pointer is empty this pointer instance is returned.

    • nextLevel

      JsonPointer nextLevel()
      Goes to the next sub level of this pointer.
      Returns:
      a new pointer beginning with the element after the root of this pointer. If this pointer is empty this pointer instance is returned.

    • getSubPointer

      Optional<JsonPointer> getSubPointer(int level)
      Returns a new JSON pointer including all JSON keys from to the passed level and upwards. For example, if this pointer is /foo/bar/baz then calling this method with level 1 returns the pointer /bar/baz.
      Parameters:
      level - the level from which (upwards) JSON keys should be included in the result. The key at the specified level is part of the result.
      Returns:
      the sub pointer starting from level. If the level is outside the bounds of this pointer the result is empty.

    • getPrefixPointer

      Optional<JsonPointer> getPrefixPointer(int level)
      Returns a new JSON pointer including all JSON keys from the root until the passed in level. For example, if this pointer is /foo/bar/baz then calling this method with level 1 returns the pointer /foo/bar.
      Parameters:
      level - the level from which (downwards) JSON keys should be included in the result. The key at the specified level is part of the result.
      Returns:
      the sub pointer starting from the root until level. If level is outside the bounds of this pointer the result is empty.

    • toFieldSelector

      JsonFieldSelector toFieldSelector()
      Returns a new JsonFieldSelector containing this pointer as its only element.
      Returns:
      a new JSON field selector containing only this pointer.

    • toString

      String toString()
      The string representation of this pointer, i. e. all of its levels concatenated by "/". For example, if this pointer consists of the three levels "foo", "bar" and "baz", this method will return the string "/foo/bar/baz".
      Specified by:
      toString in interface CharSequence
      Overrides:
      toString in class Object
      Returns:
      the string representation of this pointer.