Package org.apache.juneau.marshall.objecttools

Class PathTraversal

java.lang.Object
org.apache.juneau.marshall.objecttools.PathTraversal
public class PathTraversal extends Object
Traversal engine for performing standard REST operations (GET, PUT, POST, DELETE) against nodes in a POJO model.

Internal API: This class is the relocated traversal engine behind the Marshalled* path-addressing methods and the Swagger/OpenApi $ref resolver. It is public only for cross-module access and is not a supported public API — do not use it directly.

Nodes in the POJO model are addressed using URLs.

A POJO model is defined as a tree model where nodes consist of consisting of the following:

  • Maps and Java beans representing JSON objects.
  • Collections and arrays representing JSON arrays.
  • Java beans.

Leaves of the tree can be any type of object.

Use get() to retrieve an element from a JSON tree.
Use put() to create (or overwrite) an element in a JSON tree.
Use post() to add an element to a list in a JSON tree.
Use delete() to remove an element from a JSON tree.

Leading slashes in URLs are ignored. So "/xxx/yyy/zzz" and "xxx/yyy/zzz" are considered identical.

Example:

// Construct an unstructured POJO model JsonMap map = JsonMap.ofText("" + "{" + " name:'John Smith', " + " address:{ " + " streetAddress:'21 2nd Street', " + " city:'New York', " + " state:'NY', " + " postalCode:10021 " + " }, " + " phoneNumbers:[ " + " '212 555-1111', " + " '212 555-2222' " + " ], " + " additionalInfo:null, " + " remote:false, " + " height:62.4, " + " 'fico score':' > 640' " + "} " ); // Wrap Map inside a PathTraversal object PathTraversal johnSmith = PathTraversal.create(map); // Get a simple value at the top level // "John Smith" String name = johnSmith.getString("name"); // Change a simple value at the top level johnSmith.put("name", "The late John Smith"); // Get a simple value at a deep level // "21 2nd Street" String streetAddress = johnSmith.getString("address/streetAddress"); // Set a simple value at a deep level johnSmith.put("address/streetAddress", "101 Cemetery Way"); // Get entries in a list // "212 555-1111" String firstPhoneNumber = johnSmith.getString("phoneNumbers/0"); // Add entries to a list johnSmith.post("phoneNumbers", "212 555-3333"); // Delete entries from a model johnSmith.delete("fico score"); // Add entirely new structures to the tree JsonMap medicalInfo = JsonMap.ofText("" + "{" + " currentStatus: 'deceased'," + " health: 'non-existent'," + " creditWorthiness: 'not good'" + "}" ); johnSmith.put("additionalInfo/medicalInfo", medicalInfo);

In the special case of collections/arrays of maps/beans, a special XPath-like selector notation can be used in lieu of index numbers on GET requests to return a map/bean with a specified attribute value.
The syntax is @attr=val, where attr is the attribute name on the child map, and val is the matching value.

Example:

// Get map/bean with name attribute value of 'foo' from a list of items Map map = pathTraversal.getMap("/items/@name=foo");

  • Constructor Details

    • PathTraversal

      public PathTraversal(Object o)
      Create a new instance of a REST interface over the specified object.

      Uses MarshallingContext.DEFAULT for working with Java beans.

      Parameters:
      o - The object to be wrapped.

    • PathTraversal

      public PathTraversal(Object o, ReaderParser parser)
      Create a new instance of a REST interface over the specified object.

      The parser is used as the bean context.

      Parameters:
      o - The object to be wrapped.
      parser - The parser to use for parsing arguments and converting objects to the correct data type.

  • Method Details

    • create

      public static PathTraversal create(Object o)
      Static creator.
      Parameters:
      o - The object being wrapped.
      Returns:
      A new PathTraversal object.

    • create

      public static PathTraversal create(Object o, ReaderParser parser)
      Static creator.
      Parameters:
      o - The object being wrapped.
      parser - The parser to use for parsing arguments and converting objects to the correct data type.
      Returns:
      A new PathTraversal object.

    • delete

      public Object delete(String url)
      Remove an element from a POJO model.

      If the element does not exist, no action is taken.

      Parameters:
      url - The URL of the element being deleted. If null or blank, the root itself is deleted.
      Returns:
      The removed element, or null if that element does not exist.

    • get

      public Object get(String url)
      Retrieves the element addressed by the URL.
      Parameters:
      url - The URL of the element to retrieve.
      If null or blank, returns the root.
      Returns:
      The addressed element, or null if that element does not exist in the tree.

    • get

      public <T> T get(String url, Class<T> type)
      Retrieves the element addressed by the URL as the specified object type.

      Will convert object to the specified type per MarshallingSession.convertToType(Object, Class).

      Examples:

      PathTraversal pathTraversal = new PathTraversal(object); // Value converted to a string. String string = pathTraversal.get("path/to/string", String.class); // Value converted to a bean. MyBean bean = pathTraversal.get("path/to/bean", MyBean.class); // Value converted to a bean array. MyBean[] beanArray = pathTraversal.get("path/to/beanarray", MyBean[].class); // Value converted to a linked-list of objects. List list = pathTraversal.get("path/to/list", LinkedList.class); // Value converted to a map of object keys/values. Map map = pathTraversal.get("path/to/map", TreeMap.class);

      Type Parameters:
      T - The specified object type.
      Parameters:
      url - The URL of the element to retrieve. If null or blank, returns the root.
      type - The specified object type.
      Returns:
      The addressed element, or null if that element does not exist in the tree.

    • get

      public <T> T get(String url, Type type, Type... args)
      Retrieves the element addressed by the URL as the specified object type.

      Will convert object to the specified type per MarshallingSession.convertToType(Object, Class).

      The type can be a simple type (e.g. beans, strings, numbers) or parameterized type (collections/maps).

      Examples:

      PathTraversal pathTraversal = new PathTraversal(object); // Value converted to a linked-list of strings. List<String> list1 = pathTraversal.get("path/to/list1", LinkedList.class, String.class); // Value converted to a linked-list of beans. List<MyBean> list2 = pathTraversal.get("path/to/list2", LinkedList.class, MyBean.class); // Value converted to a linked-list of linked-lists of strings. List<List<String>> list3 = pathTraversal.get("path/to/list3", LinkedList.class, LinkedList.class, String.class); // Value converted to a map of string keys/values. Map<String,String> map1 = pathTraversal.get("path/to/map1", TreeMap.class, String.class, String.class); // Value converted to a map containing string keys and values of lists containing beans. Map<String,List<MyBean>> map2 = pathTraversal.get("path/to/map2", TreeMap.class, String.class, List.class, MyBean.class);

      Collection classes are assumed to be followed by zero or one objects indicating the element type.

      Map classes are assumed to be followed by zero or two meta objects indicating the key and value types.

      The array can be arbitrarily long to indicate arbitrarily complex data structures.

      Notes:
      • Use the get(String, Class) method instead if you don't need a parameterized map/collection.
      Type Parameters:
      T - The specified object type.
      Parameters:
      url - The URL of the element to retrieve. If null or blank, returns the root.
      type - The specified object type.
      args - The specified object parameter types.
      Returns:
      The addressed element, or null if that element does not exist in the tree.

    • getBoolean

      public Boolean getBoolean(String url)
      Returns the specified entry value converted to a Boolean.

      Shortcut for get(Boolean.class, key).

      Parameters:
      url - The key.
      Returns:
      The converted value, or null if the map contains no mapping for this key.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getBoolean

      public Boolean getBoolean(String url, Boolean defVal)
      Returns the specified entry value converted to a Boolean.

      Shortcut for get(Boolean.class, key, defVal).

      Parameters:
      url - The key.
      defVal - The default value if the map doesn't contain the specified mapping.
      Returns:
      The converted value, or the default value if the map contains no mapping for this key.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getClassMeta

      public ClassMeta getClassMeta(String url)
      Returns the class type of the object at the specified URL.
      Parameters:
      url - The URL.
      Returns:
      The class type, or null if the addressed element does not exist in the tree.

    • getInt

      public Integer getInt(String url)
      Returns the specified entry value converted to an Integer.

      Shortcut for get(Integer.class, key).

      Parameters:
      url - The key.
      Returns:
      The converted value, or null if the map contains no mapping for this key.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getInt

      public Integer getInt(String url, Integer defVal)
      Returns the specified entry value converted to an Integer.

      Shortcut for get(Integer.class, key, defVal).

      Parameters:
      url - The key.
      defVal - The default value if the map doesn't contain the specified mapping.
      Returns:
      The converted value, or the default value if the map contains no mapping for this key.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getJsonList

      public JsonList getJsonList(String url)
      Returns the specified entry value converted to a JsonList.

      Shortcut for get(JsonList.class, key).

      Parameters:
      url - The key.
      Returns:
      The converted value, or null if the map contains no mapping for this key.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getJsonList

      public JsonList getJsonList(String url, JsonList defVal)
      Returns the specified entry value converted to a JsonList.

      Shortcut for get(JsonList.class, key, defVal).

      Parameters:
      url - The key.
      defVal - The default value if the map doesn't contain the specified mapping.
      Returns:
      The converted value, or the default value if the map contains no mapping for this key.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getJsonMap

      public JsonMap getJsonMap(String url)
      Returns the specified entry value converted to a Map.

      Shortcut for get(JsonMap.class, key).

      Parameters:
      url - The key.
      Returns:
      The converted value, or null if the map contains no mapping for this key.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getJsonMap

      public JsonMap getJsonMap(String url, JsonMap defVal)
      Returns the specified entry value converted to a JsonMap.

      Shortcut for get(JsonMap.class, key, defVal).

      Parameters:
      url - The key.
      defVal - The default value if the map doesn't contain the specified mapping.
      Returns:
      The converted value, or the default value if the map contains no mapping for this key.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getList

      public List<?> getList(String url)
      Returns the specified entry value converted to a List.

      Shortcut for get(List.class, key).

      Parameters:
      url - The key.
      Returns:
      The converted value, or null if the map contains no mapping for this key.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getList

      public List<?> getList(String url, List<?> defVal)
      Returns the specified entry value converted to a List.

      Shortcut for get(List.class, key, defVal).

      Parameters:
      url - The key.
      defVal - The default value if the map doesn't contain the specified mapping.
      Returns:
      The converted value, or the default value if the map contains no mapping for this key.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getLong

      public Long getLong(String url)
      Returns the specified entry value converted to a Long.

      Shortcut for get(Long.class, key).

      Parameters:
      url - The key.
      Returns:
      The converted value, or null if the map contains no mapping for this key.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getLong

      public Long getLong(String url, Long defVal)
      Returns the specified entry value converted to a Long.

      Shortcut for get(Long.class, key, defVal).

      Parameters:
      url - The key.
      defVal - The default value if the map doesn't contain the specified mapping.
      Returns:
      The converted value, or the default value if the map contains no mapping for this key.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getMap

      public Map<?,?> getMap(String url)
      Returns the specified entry value converted to a Map.

      Shortcut for get(Map.class, key).

      Parameters:
      url - The key.
      Returns:
      The converted value, or null if the map contains no mapping for this key.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getMap

      public Map<?,?> getMap(String url, Map<?,?> defVal)
      Returns the specified entry value converted to a Map.

      Shortcut for get(Map.class, key, defVal).

      Parameters:
      url - The key.
      defVal - The default value if the map doesn't contain the specified mapping.
      Returns:
      The converted value, or the default value if the map contains no mapping for this key.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getRootObject

      public Object getRootObject()
      The root object that was passed into the constructor of this method.
      Returns:
      The root object.

    • getString

      public String getString(String url)
      Returns the specified entry value converted to a String.

      Shortcut for get(String.class, key).

      Parameters:
      url - The key.
      Returns:
      The converted value, or null if the map contains no mapping for this key.

    • getString

      public String getString(String url, String defVal)
      Returns the specified entry value converted to a String.

      Shortcut for get(String.class, key, defVal).

      Parameters:
      url - The key.
      defVal - The default value if the map doesn't contain the specified mapping.
      Returns:
      The converted value, or the default value if the map contains no mapping for this key.

    • getWithDefault

      public Object getWithDefault(String url, Object defVal)
      Retrieves the element addressed by the URL.
      Parameters:
      url - The URL of the element to retrieve.
      If null or blank, returns the root.
      defVal - The default value if the map doesn't contain the specified mapping.
      Returns:
      The addressed element, or null if that element does not exist in the tree.

    • getWithDefault

      public <T> T getWithDefault(String url, T def, Class<T> type)
      Same as get(String, Class) but returns a default value if the addressed element is null or non-existent.
      Type Parameters:
      T - The specified object type.
      Parameters:
      url - The URL of the element to retrieve. If null or blank, returns the root.
      def - The default value if addressed item does not exist.
      type - The specified object type.
      Returns:
      The addressed element, or null if that element does not exist in the tree.

    • getWithDefault

      public <T> T getWithDefault(String url, T def, Type type, Type... args)
      Same as get(String,Type,Type[]) but returns a default value if the addressed element is null or non-existent.
      Type Parameters:
      T - The specified object type.
      Parameters:
      url - The URL of the element to retrieve. If null or blank, returns the root.
      def - The default value if addressed item does not exist.
      type - The specified object type.
      args - The specified object parameter types.
      Returns:
      The addressed element, or null if that element does not exist in the tree.

    • post

      public String post(String url, Object val)
      Adds a value to a list element in a POJO model.

      The URL is the address of the list being added to.

      If the list does not already exist, it will be created.

      This method expands the POJO model as necessary to create the new element.

      Notes:
      • You can only post to three types of nodes:
        • Lists
        • Maps containing integers as keys (i.e sparse arrays)
        • arrays
      Parameters:
      url - The URL of the element being added to. If null or blank, the root itself (assuming it's one of the types specified above) is added to.
      val - The value being added.
      Returns:
      The URL of the element that was added, or null if the value was added to a non-indexable (non-List) collection.

    • put

      public Object put(String url, Object val)
      Sets/replaces the element addressed by the URL.

      This method expands the POJO model as necessary to create the new element.

      Parameters:
      url - The URL of the element to create. If null or blank, the root itself is replaced with the specified value.
      val - The value being set. Value can be of any type.
      Returns:
      The previously addressed element, or null if the element did not previously exist.

    • setRootLocked

      public PathTraversal setRootLocked()
      Call this method to prevent the root object from being overwritten on put("", xxx); calls.
      Returns:
      This object.

    • toString

      public String toString()
      Overrides:
      toString in class Object