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

Interface PojoPath

All Superinterfaces:

PojoPropertyPath

All Known Implementing Classes:

AbstractPojoPathNavigator.CachingPojoPath, BasicPojoPath

public interface PojoPath
extends PojoPropertyPath

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

Fields inherited from interface net.sf.mmm.util.pojo.path.api.PojoPropertyPath

SEPARATOR

Method Summary

Modifier and Type	Method and Description
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.

Methods inherited from interface net.sf.mmm.util.pojo.path.api.PojoPropertyPath

getParentPath, getPojoPath, getSegment

Method Detail

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.