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

All Known Implementing Classes:

AbstractPojoPathNavigator, PojoPathNavigatorImpl

@ComponentSpecification
public interface PojoPathNavigator

This is the interface for the navigator used to traverse the object-web spanned by an initial Pojo reflectively according to a given PojoPath.

Design

The PojoPathNavigator is designed to be thread-safe and extensible. Therefore the state is externalized to a context that is provided as argument to the methods of this interface.

Since:

1.1.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

PojoPath, PojoDescriptorBuilder

Method Summary

Object	get(Object pojo, String pojoPath, PojoPathMode mode, PojoPathContext context) This method evaluates the given pojoPath for the given pojo using the given mode and context.
<TYPE> TYPE	get(Object pojo, String pojoPath, PojoPathMode mode, PojoPathContext context, Class<TYPE> targetClass) This method evaluates the given pojoPath for the given pojo using the given mode and context.
GenericType<?>	getType(GenericType<?> pojoType, String pojoPath, boolean failOnUnsafePath, PojoPathContext context) This method determines the result-type for the given pojoPath starting at the given pojoType using the given context.
GenericType<?>	getType(Type pojoType, String pojoPath, boolean failOnUnsafePath, PojoPathContext context) This method determines the result-type for the given pojoPath starting at the given pojoType using the given context.
Map<String,Object>	pojo2Map(Object pojo) This method creates a lazy, immutable Map reflecting the given Pojo.
Map<String,Object>	pojo2Map(Object pojo, PojoPathContext context) This method creates a lazy, immutable Map reflecting the given Pojo.
Object	set(Object pojo, String pojoPath, PojoPathMode mode, PojoPathContext context, Object value) This method sets the given value for the given pojoPath in the given pojo using the given mode and context.

Method Detail

get

Object get(Object pojo,
           String pojoPath,
           PojoPathMode mode,
           PojoPathContext context)
           throws PojoPathException,
                  IllegalPojoPathException,
                  PojoPathSegmentIsNullException,
                  InstantiationFailedException

This method evaluates the given pojoPath for the given pojo using the given mode and context. It returns the result of the evaluation.
ATTENTION:
If you use caching for repetitive calls on the same initial pojo, you might get wrong results if intermediate objects have changed outside this navigator in the meantime.

Parameters:

pojo - is the initial Pojo to operate on.

pojoPath - is the PojoPath to navigate.

mode - is the mode that determines how to deal with null values.

context - is the PojoPathContext for this operation.

Returns:

the result of the navigation of the given pojoPath starting at the given pojo. It may be null according to the given mode.

Throws:

IllegalPojoPathException - if the given pojoPath is illegal.

PojoPathSegmentIsNullException - if an intermediate Pojo was null and the given mode disallows this.

InstantiationFailedException - if an intermediate Pojo was null and should be created but the instantiation failed.

PojoPathException - if the operation failed for arbitrary reasons.

get

<TYPE> TYPE get(Object pojo,
                String pojoPath,
                PojoPathMode mode,
                PojoPathContext context,
                Class<TYPE> targetClass)
         throws PojoPathException,
                IllegalPojoPathException,
                PojoPathSegmentIsNullException,
                InstantiationFailedException,
                PojoPathConversionException

This method evaluates the given pojoPath for the given pojo using the given mode and context. It returns the result of the evaluation.
ATTENTION:
If you use caching for repetitive calls on the same initial pojo, you might get wrong results if intermediate objects have changed outside this navigator in the meantime.

Type Parameters:

TYPE - is the generic type of the result.

Parameters:

pojo - is the initial Pojo to operate on.

pojoPath - is the PojoPath to navigate.

mode - is the mode that determines how to deal with null values.

context - is the PojoPathContext for this operation.

targetClass - is the required result-type.

Returns:

the result of the navigation of the given pojoPath starting at the given pojo. It may be null according to the given mode.

Throws:

IllegalPojoPathException - if the given pojoPath is illegal.

PojoPathSegmentIsNullException - if an intermediate Pojo was null and the given mode disallows this.

InstantiationFailedException - if an intermediate Pojo was null and should be created but the instantiation failed.

PojoPathException - if the operation failed for arbitrary reasons.

PojoPathConversionException - if the result is NOT compatible with the given targetClass and could NOT be converted.

getType

GenericType<?> getType(GenericType<?> pojoType,
                       String pojoPath,
                       boolean failOnUnsafePath,
                       PojoPathContext context)
                       throws PojoPathException,
                              IllegalPojoPathException,
                              PojoPathUnsafeException

This method determines the result-type for the given pojoPath starting at the given pojoType using the given context.
In other words if get is invoked on this navigator with an instance of pojoType the result will be an instance of the type returned by this method.
Please note that the given pojoPath may be unsafe , what means that it has a segment that points to a property that does NOT exist for the Class determined for the according Pojo. In other words a PojoPath is unsafe if it can NOT be written as native Java method cascade without using casts in order to be compiled. It may be illegal depending on the initial Pojo.

Parameters:

pojoType - is the type of the initial Pojo.

pojoPath - is the PojoPath to navigate.

failOnUnsafePath - determines how to deal with unsafe PojoPaths. If true and the given pojoPath is unsafe for the given pojoType an PojoPathUnsafeException is thrown and if false this method returns null in such case.

context - is the PojoPathContext for this operation.

Returns:

the guaranteed result-type of the navigation of the given pojoPath starting at the given pojoType. It may be Object.class e.g. in case an untyped Collection is hit. It will be null if the given pojoPath is unsafe and the given mode is PojoPathMode.RETURN_IF_NULL.

Throws:

IllegalPojoPathException - if the given pojoPath is illegal.

PojoPathUnsafeException - if the given pojoPath is unsafe for the given pojoType and this is disallowed by mode.

PojoPathException - if the operation failed for arbitrary reasons.

getType

GenericType<?> getType(Type pojoType,
                       String pojoPath,
                       boolean failOnUnsafePath,
                       PojoPathContext context)
                       throws PojoPathException,
                              IllegalPojoPathException,
                              PojoPathUnsafeException

This method determines the result-type for the given pojoPath starting at the given pojoType using the given context.
In other words if get is invoked on this navigator with an instance of pojoType the result will be an instance of the type returned by this method.
Please note that the given pojoPath may be unsafe , what means that it has a segment that points to a property that does NOT exist for the Class determined for the according Pojo. In other words a PojoPath is unsafe if it can NOT be written as native Java method cascade without using casts in order to be compiled. It may be illegal depending on the initial Pojo.

Parameters:

pojoType - is the type of the initial Pojo.

pojoPath - is the PojoPath to navigate.

failOnUnsafePath - determines how to deal with unsafe PojoPaths. If true and the given pojoPath is unsafe for the given pojoType an PojoPathUnsafeException is thrown and if false this method returns null in such case.

context - is the PojoPathContext for this operation.

Returns:

the guaranteed result-type of the navigation of the given pojoPath starting at the given pojoType. It may be Object.class e.g. in case an untyped Collection is hit. It will be null if the given pojoPath is unsafe and the given mode is PojoPathMode.RETURN_IF_NULL.

Throws:

IllegalPojoPathException - if the given pojoPath is illegal.

PojoPathUnsafeException - if the given pojoPath is unsafe for the given pojoType and this is disallowed by mode.

PojoPathException - if the operation failed for arbitrary reasons.

set

Object set(Object pojo,
           String pojoPath,
           PojoPathMode mode,
           PojoPathContext context,
           Object value)
           throws PojoPathException,
                  IllegalPojoPathException,
                  PojoPathSegmentIsNullException,
                  InstantiationFailedException,
                  PojoPathConversionException

This method sets the given value for the given pojoPath in the given pojo using the given mode and context. It acts like a get on the parent-path and then setting the value for the remaining segment on the result.
The result of this method is defined as following:

• If the last segment points to a PojoPathFunction the result of its set -method is returned.
• Otherwise if segment points to an index,
• the depends on the result of the parent-path is a List, Map or array, this will be the old value of the given pojoPath that has been replaced by value.

If pojo is This will typically be the value that replaced value. It may be null.

Parameters:

pojo - is the initial Pojo to operate on.

pojoPath - is the PojoPath to navigate.

mode - is the mode that determines how to deal with null values.

context - is the PojoPathContext for this operation.

value - is the value to set. It may be null.

Returns:

the result of the set operation.

Throws:

IllegalPojoPathException - if the given pojoPath is illegal.

PojoPathSegmentIsNullException - if an intermediate Pojo was null and the given mode disallows this.

InstantiationFailedException - if an intermediate Pojo was null and should be created but the instantiation failed.

PojoPathException - if the operation failed for arbitrary reasons.

PojoPathConversionException - if the given pojo is NOT compatible with the type required for the given pojoPath and could NOT be converted.

pojo2Map

Map<String,Object> pojo2Map(Object pojo)

This method creates a lazy, immutable Map reflecting the given Pojo.
ATTENTION:
The Map will be simple and will NOT support size or iteration.

Parameters:

pojo - is the Pojo to convert.

Returns:

the Map reflecting the given Pojo.

Since:

1.1.1

See Also:

PojoDescriptorBuilder.pojo2Map(Object)

pojo2Map

Map<String,Object> pojo2Map(Object pojo,
                            PojoPathContext context)

This method creates a lazy, immutable Map reflecting the given Pojo.
ATTENTION:
The Map will be simple and will NOT support size or iteration.

Parameters:

pojo - is the Pojo to convert.

context - is the PojoPathContext for this operation.

Returns:

the Map reflecting the given Pojo.

Since:

1.1.1

See Also:

PojoDescriptorBuilder.pojo2Map(Object)