Package org.apache.juneau.objecttools

Class ObjectRest

java.lang.Object
org.apache.juneau.objecttools.ObjectRest
public final class ObjectRest extends Object
POJO REST API.

Provides the ability to perform standard REST operations (GET, PUT, POST, DELETE) against nodes in a POJO model. 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.ofJson("" + "{" + " 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 an ObjectRest object ObjectRest johnSmith = ObjectRest.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.ofJson("" + "{" + " 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 = objectRest.getMap("/items/@name=foo");

See Also:

  • Constructor Details

    • ObjectRest

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

      Uses BeanContext.DEFAULT for working with Java beans.

      Parameters:
      o - The object to be wrapped.

    • ObjectRest

      public ObjectRest(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 ObjectRest create(Object o)
      Static creator.
      Parameters:
      o - The object being wrapped.
      Returns:
      A new ObjectRest object.

    • create

      public static ObjectRest 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 ObjectRest object.

    • setRootLocked

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

    • getRootObject

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

    • 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.

    • 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.

    • 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 BeanSession.convertToType(Object, Class).

      Examples:

      ObjectRest objectRest = new ObjectRest(object); // Value converted to a string. String string = objectRest.get("path/to/string", String.class); // Value converted to a bean. MyBean bean = objectRest.get("path/to/bean", MyBean.class); // Value converted to a bean array. MyBean[] beanArray = objectRest.get("path/to/beanarray", MyBean[].class); // Value converted to a linked-list of objects. List list = objectRest.get("path/to/list", LinkedList.class); // Value converted to a map of object keys/values. Map map = objectRest.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 BeanSession.convertToType(Object, Class).

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

      Examples:

      ObjectRest objectRest = new ObjectRest(object); // Value converted to a linked-list of strings. List<String> list1 = objectRest.get("path/to/list1", LinkedList.class, String.class); // Value converted to a linked-list of beans. List<MyBean> list2 = objectRest.get("path/to/list2", LinkedList.class, MyBean.class); // Value converted to a linked-list of linked-lists of strings. List<List<String>> list3 = objectRest.get("path/to/list3", LinkedList.class, LinkedList.class, String.class); // Value converted to a map of string keys/values. Map<String,String> map1 = objectRest.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 = objectRest.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.

    • 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.

    • 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.

    • 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.

    • 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.

    • 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.

    • 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.

    • 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.

    • 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.

    • 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.

    • invokeMethod

      public Object invokeMethod(String url, String method, String args) throws ExecutableException, ParseException, IOException
      Executes the specified method with the specified parameters on the specified object.
      Parameters:
      url - The URL of the element to retrieve.
      method - The method signature.

      Can be any of the following formats:

      • Method name only. e.g. "myMethod".
      • Method name with class names. e.g. "myMethod(String,int)".
      • Method name with fully-qualified class names. e.g. "myMethod(java.util.String,int)".

      As a rule, use the simplest format needed to uniquely resolve a method.

      args - The arguments to pass as parameters to the method. These will automatically be converted to the appropriate object type if possible. This must be an array, like a JSON array.
      Returns:
      The returned object from the method call.
      Throws:
      ExecutableException - Exception occurred on invoked constructor/method/field.
      ParseException - Malformed input encountered.
      IOException - Thrown by underlying stream.

    • getPublicMethods

      public Collection<String> getPublicMethods(String url)
      Returns the list of available methods that can be passed to the invokeMethod(String, String, String) for the object addressed by the specified URL.
      Parameters:
      url - The URL.
      Returns:
      The list of methods.

    • 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.

    • 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 the element did not previously exist.

    • 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.

    • 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.

    • toString

      public String toString()
      Overrides:
      toString in class Object