Package net.dv8tion.jda.api.utils.data

Class DataPath

java.lang.Object
net.dv8tion.jda.api.utils.data.DataPath
public class DataPath extends Object
This utility class can be used to access nested values within DataObjects and DataArrays.

Path Expression Grammar
The syntax for paths is given by this grammar: 


 <name-syntax>  ::= /[^.\[\]]+/;
 <index-syntax> ::= "[" <number> "]";
 <name>         ::= <name-syntax> | <name-syntax> "?";
 <index>        ::= <index-syntax> | <index-syntax> "?";
 <element>      ::= <name> ( <index> )*;
 <path-start>   ::= <element> | <index> ( <index> )*;
 <path>         ::= <path-start> ( "." <element> )*;

Examples
Given a JSON object such as: 


 {
     "array": [{
         "foo": "bar",
     }]
 }
The content of "foo" can be accessed using the code: 
String foo = DataPath.getString(root, "array[0].foo")

With the safe-access operator "?", you can also allow missing values within your path: 

String foo = DataPath.getString(root, "array[1]?.foo", "default")
This will result in foo == "default", since the array element 1 is marked as optional, and missing in the actual object.

  • Constructor Details

    • DataPath

      public DataPath()

  • Method Details

    • get

      public static <T> T get(@Nonnull DataObject root, @Nonnull String path, @Nonnull BiFunction<DataObject,String,? extends T> fromObject, @Nonnull BiFunction<DataArray,Integer,? extends T> fromArray)
      Parses the given path and finds the appropriate value within this DataObject.
      Type Parameters:
      T - The result type
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      fromObject - Object relative resolver of the value, this is used for the final reference and resolves the value. The first parameter is the DataObject where you get the value from, and the second is the field name. An example would be (obj, name) -> obj.getString(name) or as a method reference DataObject::getString.
      fromArray - Array relative resolver of the value, this is used for the final reference and resolves the value. The first parameter is the DataArray where you get the value from, and the second is the field index. An example would be (array, index) -> obj.getString(index) or as a method reference DataArray::getString.
      Returns:
      The value at the provided path, using the provided resolver functions. Possibly null, if the path ends with a "?" operator, or the resolver function returns null.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • get

      public static <T> T get(@Nonnull DataArray root, @Nonnull String path, @Nonnull BiFunction<DataObject,String,? extends T> fromObject, @Nonnull BiFunction<DataArray,Integer,? extends T> fromArray)
      Parses the given path and finds the appropriate value within this DataArray.
      Type Parameters:
      T - The result type
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      fromObject - Object relative resolver of the value, this is used for the final reference and resolves the value. The first parameter is the DataObject where you get the value from, and the second is the field name. An example would be (obj, name) -> obj.getString(name) or as a method reference DataObject::getString.
      fromArray - Array relative resolver of the value, this is used for the final reference and resolves the value. The first parameter is the DataArray where you get the value from, and the second is the field index. An example would be (array, index) -> obj.getString(index) or as a method reference DataArray::getString.
      Returns:
      The value at the provided path, using the provided resolver functions. Possibly null, if the path ends with a "?" operator, or the resolver function returns null.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getBoolean

      public static boolean getBoolean(@Nonnull DataObject root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataObject.
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The boolean value at the given path, if declared as optional this returns false when the value is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getBoolean

      public static boolean getBoolean(@Nonnull DataObject root, @Nonnull String path, boolean fallback)
      Parses the given path and finds the appropriate value within this DataObject.
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The boolean value at the given path, if declared as optional this returns the provided fallback when the value is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getBoolean

      public static boolean getBoolean(@Nonnull DataArray root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataArray.
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The boolean value at the given path, if declared as optional this returns false when the value is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getBoolean

      public static boolean getBoolean(@Nonnull DataArray root, @Nonnull String path, boolean fallback)
      Parses the given path and finds the appropriate value within this DataArray.
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The boolean value at the given path, if declared as optional this returns the provided fallback when the value is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getInt

      public static int getInt(@Nonnull DataObject root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataObject.
      If the resulting value is a string, this will parse the string using Integer.parseInt(String).
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The int value at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getInt

      public static int getInt(@Nonnull DataObject root, @Nonnull String path, int fallback)
      Parses the given path and finds the appropriate value within this DataObject.
      If the resulting value is a string, this will parse the string using Integer.parseInt(String).
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The int value at the given path, returning the fallback if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getInt

      public static int getInt(@Nonnull DataArray root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataArray.
      If the resulting value is a string, this will parse the string using Integer.parseInt(String).
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The int value at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getInt

      public static int getInt(@Nonnull DataArray root, @Nonnull String path, int fallback)
      Parses the given path and finds the appropriate value within this DataArray.
      If the resulting value is a string, this will parse the string using Integer.parseInt(String).
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The int value at the given path, returning the fallback if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getUnsignedInt

      public static int getUnsignedInt(@Nonnull DataObject root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataObject.
      If the resulting value is a string, this will parse the string using Integer.parseUnsignedInt(String).
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The unsigned int value at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getUnsignedInt

      public static int getUnsignedInt(@Nonnull DataObject root, @Nonnull String path, int fallback)
      Parses the given path and finds the appropriate value within this DataObject.
      If the resulting value is a string, this will parse the string using Integer.parseUnsignedInt(String).
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The unsigned int value at the given path, returning the fallback if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getUnsignedInt

      public static int getUnsignedInt(@Nonnull DataArray root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataArray.
      If the resulting value is a string, this will parse the string using Integer.parseUnsignedInt(String).
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The unsigned int value at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getUnsignedInt

      public static int getUnsignedInt(@Nonnull DataArray root, @Nonnull String path, int fallback)
      Parses the given path and finds the appropriate value within this DataArray.
      If the resulting value is a string, this will parse the string using Integer.parseUnsignedInt(String).
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The unsigned int value at the given path, returning the fallback if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getLong

      public static long getLong(@Nonnull DataObject root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataObject.
      If the resulting value is a string, this will parse the string using Long.parseLong(String).
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The long value at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getLong

      public static long getLong(@Nonnull DataObject root, @Nonnull String path, long fallback)
      Parses the given path and finds the appropriate value within this DataObject.
      If the resulting value is a string, this will parse the string using Long.parseLong(String).
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The long value at the given path, returning the fallback if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getLong

      public static long getLong(@Nonnull DataArray root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataArray.
      If the resulting value is a string, this will parse the string using Long.parseLong(String).
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The long value at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getLong

      public static long getLong(@Nonnull DataArray root, @Nonnull String path, long fallback)
      Parses the given path and finds the appropriate value within this DataArray.
      If the resulting value is a string, this will parse the string using Long.parseLong(String).
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The long value at the given path, returning the fallback if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getUnsignedLong

      public static long getUnsignedLong(@Nonnull DataObject root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataObject.
      If the resulting value is a string, this will parse the string using Long.parseUnsignedLong(String).
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The unsigned long value at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getUnsignedLong

      public static long getUnsignedLong(@Nonnull DataObject root, @Nonnull String path, long fallback)
      Parses the given path and finds the appropriate value within this DataObject.
      If the resulting value is a string, this will parse the string using Long.parseUnsignedLong(String).
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The unsigned long value at the given path, returning the fallback if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getUnsignedLong

      public static long getUnsignedLong(@Nonnull DataArray root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataArray.
      If the resulting value is a string, this will parse the string using Long.parseUnsignedLong(String).
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The unsigned long value at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getUnsignedLong

      public static long getUnsignedLong(@Nonnull DataArray root, @Nonnull String path, long fallback)
      Parses the given path and finds the appropriate value within this DataArray.
      If the resulting value is a string, this will parse the string using Long.parseUnsignedLong(String).
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The unsigned long value at the given path, returning the fallback if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getDouble

      public static double getDouble(@Nonnull DataObject root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataObject.
      If the resulting value is a string, this will parse the string using Double.parseDouble(String).
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The double value at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getDouble

      public static double getDouble(@Nonnull DataObject root, @Nonnull String path, double fallback)
      Parses the given path and finds the appropriate value within this DataObject.
      If the resulting value is a string, this will parse the string using Double.parseDouble(String).
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The double value at the given path, returning the fallback if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getDouble

      public static double getDouble(@Nonnull DataArray root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataArray.
      If the resulting value is a string, this will parse the string using Double.parseDouble(String).
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The double value at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getDouble

      public static double getDouble(@Nonnull DataArray root, @Nonnull String path, double fallback)
      Parses the given path and finds the appropriate value within this DataArray.
      If the resulting value is a string, this will parse the string using Double.parseDouble(String).
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The double value at the given path, returning the fallback if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getString

      @Nonnull public static String getString(@Nonnull DataObject root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataObject.
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The String value at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getString

      @Contract("_, _, !null -> !null") public static String getString(@Nonnull DataObject root, @Nonnull String path, @Nullable String fallback)
      Parses the given path and finds the appropriate value within this DataObject.
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The String value at the given path, returning the fallback if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getString

      @Nonnull public static String getString(@Nonnull DataArray root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataArray.
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The String value at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getString

      @Contract("_, _, !null -> !null") public static String getString(@Nonnull DataArray root, @Nonnull String path, @Nullable String fallback)
      Parses the given path and finds the appropriate value within this DataArray.
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The String value at the given path, returning the fallback if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getObject

      @Nonnull public static DataObject getObject(@Nonnull DataObject root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataObject.
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The DataObject at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • optObject

      @Nullable public static DataObject optObject(@Nonnull DataObject root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataObject.
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The DataObject at the given path, or null if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getObject

      @Nonnull public static DataObject getObject(@Nonnull DataArray root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataArray.
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The DataObject at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • optObject

      @Nullable public static DataObject optObject(@Nonnull DataArray root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataArray.
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The DataObject at the given path, or null if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getArray

      @Nonnull public static DataArray getArray(@Nonnull DataObject root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataObject.
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The DataArray at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • optArray

      @Nullable public static DataArray optArray(@Nonnull DataObject root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataObject.
      Parameters:
      root - The root data object, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with a name element, such as "foo".
      Returns:
      The DataArray at the given path, or null if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • getArray

      @Nonnull public static DataArray getArray(@Nonnull DataArray root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataArray.
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The DataArray at the given path
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty

    • optArray

      @Nullable public static DataArray optArray(@Nonnull DataArray root, @Nonnull String path)
      Parses the given path and finds the appropriate value within this DataArray.
      Parameters:
      root - The root data array, which is the top level accessor.
      The very first element in the path corresponds to a field of that name within this root object.
      path - The path of the value, in accordance with the described grammar by DataPath. This must start with an index element, such as "[0]".
      Returns:
      The DataArray at the given path, or null if the path resolves to an optional value that is missing.
      Throws:
      ParsingException - If the path is invalid or resolving fails due to missing elements
      IndexOutOfBoundsException - If any of the elements in the path refer to an array index that is out of bounds
      IllegalArgumentException - If null is provided or the path is empty