net.sf.mmm.util.pojo.path.api
Interface PojoPath

All Known Implementing Classes:

AbstractPojoPathNavigator.CachingPojoPath, BasicPojoPath

public interface PojoPath

A PojoPath is a String that acts as expression to navigate (traverse) the object-web spanned by an initial Pojo reflectively.
As part of the API this interface is mainly used for documentation of what a PojoPath is all about. For the API-user a PojoPath is just a String with a specific syntax and semantic.

Syntax

The syntax of a PojoPath is defined as follows:
PojoPath = «Segment» | «PojoPath».«Segment»
Segment = «Property» | «Index» | «Function»
Property = [a-zA-Z][^.]*
Index = [0-9]+
Function = @[^.]+

Semantic

«Property» stands for a property of the Pojo.

• If the actual Pojo is a Map, the «Property» is the key to get and set the value.
• Otherwise the «Property» is the name of a property of the actual Pojo. If the actual Pojo does NOT have such property, the PojoPath will be illegal and cause a PojoPathException.

«Index» is an Integer that represents the position of an ordered container.

• If the actual Pojo is an array, the «Index» represents the array-index to access a contained value.
• If the actual Pojo is a List, the «Index» is used as the list-index to get and set a value.

«Function» represents a PojoPathFunction.

• The «Function» is indicated by the prefix '@' and is followed by the name of the function. PojoPathFunction can make assumptions on the actual Pojo they operate on. If the actual Pojo does NOT follow these assumptions the PojoPath will be illegal and cause a PojoPathException.

Transitivity

For two PojoPath-strings path1 and path2 and for
Object pojo;
PojoPathNavigator navigator;
PojoPathMode mode;
PojoPathContext context;

The following code
Object result = navigator.get(pojo, path1, mode, context);
result = navigator.get(result, path2, mode, context);
will produce the same result as:
String path = path1 + "." + path2;
result = navigator.get(pojo, path, mode, context);


Examples

The following table gives some examples:

Initial Pojo	PojoPath	Get-Code
Object object	class	object.getClass()
String string	bytes	string.getBytes()
Object[] array	0	array[0]
List list	0	list.get(0)
Map map	key	map.get("key")
Throwable t	cause.cause.message.bytes.0	t.getCause().getCause().getMessage().getBytes()[0]

Since:

1.1.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

static char

SEPARATOR The character that separates the segments of a PojoPath.

Method Summary

String	getFunction() This method gets the name of the function given by the segment or null if it is no function.
Integer	getIndex() This method gets the index given by the segment or null if it is no index.
String	getParentPath() This method gets the parent-path of this PojoPath.
String	getPojoPath() This method gets the actual PojoPath represented by this object.
String	getSegment() This method gets the last segment of this current PojoPath.

Field Detail

SEPARATOR

static final char SEPARATOR

The character that separates the segments of a PojoPath. The value (46 ) will never change. It is NOT necessary to use this constant to construct a PojoPath.

See Also:

Constant Field Values

Method Detail

getPojoPath

String getPojoPath()

This method gets the actual PojoPath represented by this object.

Returns:

the actual PojoPath.

getParentPath

String getParentPath()

This method gets the parent-path of this PojoPath.
E.g. if this path represents "foo.bar.property" then this method would return "foo.bar".

Returns:

the parent-path or null if this is the root-segment.

getSegment

String getSegment()

This method gets the last segment of this current PojoPath. E.g. if this path represents "foo.bar.property" then this method would return "property".

Returns:

the last segment.

getIndex

Integer getIndex()

This method gets the index given by the segment or null if it is no index.
An index is an integer that represents the position of an ordered container (array or List).
If a segment starts with a Latin digit, it is treated as index and has to be a valid integer-value. However parsing should be done when this object is constructed and therefore this method should never cause an exception.

Returns:

the index given by the segment or null if it is no index.

getFunction

String getFunction()

This method gets the name of the function given by the segment or null if it is no function.
The function-name identifies a PojoPathFunction that will be used to evaluate the segment.
If a segment starts with the character PojoPathFunction.FUNCTION_NAME_PREFIX ('@'), it is treated as function.

Returns:

the segment excluding the first character or null if the segment does NOT start with PojoPathFunction.FUNCTION_NAME_PREFIX.