org.apache.juneau.utils

Class PojoRest

java.lang.Object

org.apache.juneau.utils.PojoRest

public final class PojoRest
extends Object

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 ObjectMap m = new ObjectMap("" + "{" + " 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 PojoRest object PojoRest johnSmith = new PojoRest(m); // 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 ObjectMap medicalInfo = new ObjectMap("" + "{" + " 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 m = pojoRest.getMap("/items/@name=foo");

Constructor Summary

Constructors

Constructor and Description
PojoRest(Object o) Create a new instance of a REST interface over the specified object.
PojoRest(Object o, ReaderParser parser) Create a new instance of a REST interface over the specified object.

Method Summary

Modifier and Type	Method and Description
Object	delete(String url) Remove an element from a POJO model.
Object	get(String url) Retrieves the element addressed by the URL.
<T> T	get(String url, Class<T> type) Retrieves the element addressed by the URL as the specified object type.
<T> T	get(String url, Type type, Type... args) Retrieves the element addressed by the URL as the specified object type.
Boolean	getBoolean(String url) Returns the specified entry value converted to a Boolean.
Boolean	getBoolean(String url, Boolean defVal) Returns the specified entry value converted to a Boolean.
ClassMeta	getClassMeta(String url) Returns the class type of the object at the specified URL.
Integer	getInt(String url) Returns the specified entry value converted to an Integer.
Integer	getInt(String url, Integer defVal) Returns the specified entry value converted to an Integer.
List<?>	getList(String url) Returns the specified entry value converted to a List.
List<?>	getList(String url, List<?> defVal) Returns the specified entry value converted to a List.
Long	getLong(String url) Returns the specified entry value converted to a Long.
Long	getLong(String url, Long defVal) Returns the specified entry value converted to a Long.
Map<?,?>	getMap(String url) Returns the specified entry value converted to a Map.
Map<?,?>	getMap(String url, Map<?,?> defVal) Returns the specified entry value converted to a Map.
ObjectList	getObjectList(String url) Returns the specified entry value converted to a ObjectList.
ObjectList	getObjectList(String url, ObjectList defVal) Returns the specified entry value converted to a ObjectList.
ObjectMap	getObjectMap(String url) Returns the specified entry value converted to a Map.
ObjectMap	getObjectMap(String url, ObjectMap defVal) Returns the specified entry value converted to a ObjectMap.
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.
Object	getRootObject() The root object that was passed into the constructor of this method.
String	getString(String url) Returns the specified entry value converted to a String.
String	getString(String url, String defVal) Returns the specified entry value converted to a String.
Object	getWithDefault(String url, Object defVal) Retrieves the element addressed by the URL.
<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.
<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.
Object	invokeMethod(String url, String method, String args) Executes the specified method with the specified parameters on the specified object.
String	post(String url, Object val) Adds a value to a list element in a POJO model.
Object	put(String url, Object val) Sets/replaces the element addressed by the URL.
PojoRest	setRootLocked() Call this method to prevent the root object from being overwritten on put("", xxx); calls.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PojoRest

public PojoRest(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.

PojoRest

public PojoRest(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 Detail

setRootLocked

public PojoRest setRootLocked()

Call this method to prevent the root object from being overwritten on put("", xxx); calls.

Returns:

This object (for method chaining).

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:

PojoRest r = new PojoRest(object); // Value converted to a string. String s = r.get("path/to/string", String.class); // Value converted to a bean. MyBean b = r.get("path/to/bean", MyBean.class); // Value converted to a bean array. MyBean[] ba = r.get("path/to/beanarray", MyBean[].class); // Value converted to a linked-list of objects. List l = r.get("path/to/list", LinkedList.class); // Value converted to a map of object keys/values. Map m2 = r.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:

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

getObjectMap

public ObjectMap getObjectMap(String url)

Returns the specified entry value converted to a Map.

Shortcut for get(ObjectMap.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.

getObjectMap

public ObjectMap getObjectMap(String url,
                              ObjectMap defVal)

Returns the specified entry value converted to a ObjectMap.

Shortcut for get(ObjectMap.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.

getObjectList

public ObjectList getObjectList(String url)

Returns the specified entry value converted to a ObjectList.

Shortcut for get(ObjectList.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.

getObjectList

public ObjectList getObjectList(String url,
                                ObjectList defVal)

Returns the specified entry value converted to a ObjectList.

Shortcut for get(ObjectList.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 InvocationTargetException,
                           IllegalArgumentException,
                           IllegalAccessException,
                           ParseException,
                           NoSuchMethodException,
                           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:

IllegalAccessException - If the Constructor object enforces Java language access control and the underlying constructor is inaccessible.

IllegalArgumentException - If one of the following occurs:

• The number of actual and formal parameters differ.
• An unwrapping conversion for primitive arguments fails.
• A parameter value cannot be converted to the corresponding formal parameter type by a method invocation conversion.
• The constructor pertains to an enum type.

InvocationTargetException - If the underlying constructor throws an exception.

ParseException - If the input contains a syntax error or is malformed.

NoSuchMethodException

IOException

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