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

Interface PojoPathFunction<IN,VALUE>

Type Parameters:

IN - is the generic input-type.

VALUE - is the generic value-type

All Known Subinterfaces:

PojoPathNamedFunction<IN,VALUE>

All Known Implementing Classes:

AbstractMapPojoPathFunction, AbstractPojoPathFunction, PojoPathNamedFunctionToString

public interface PojoPathFunction<IN,VALUE>

This is the call-back interface for a PojoPathFunction that allows to add custom functionality to a PojoPathNavigator.
This can help for various use-cases such as retrieving objects from a database (an O/R-mapper), adding custom logic for calculated or combined attributes, etc.
A PojoPathFunction is registered in a PojoPathFunctionManager under a specific name ( functionName). The PojoPathFunction itself does NOT contain that name and gets this name back as parameter when it is invoked. Therefore the same PojoPathFunction instance can be registered with different names and can behave different according to the name it was invoked for.

Since:

1.1.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

Fields

Modifier and Type	Field and Description
static char	FUNCTION_NAME_PREFIX This is the prefix used to indicate a PojoPathFunction in a PojoPath.

Method Summary

Modifier and Type	Method and Description
VALUE	create(IN input, String functionName, PojoPathContext context) This method creates an appropriate new value.
VALUE	get(IN input, String functionName, PojoPathContext context) This method gets the value of this function.
Class<IN>	getInputClass() This method gets the input-type of this function.
Class<VALUE>	getValueClass() This method gets the output-type (or return-type) of this function.
boolean	isDeterministic() This method determines if this PojoPathFunction is deterministic.
VALUE	set(IN input, String functionName, VALUE value, PojoPathContext context) This method sets the given value for the given actual Pojo.

Field Detail

FUNCTION_NAME_PREFIX

static final char FUNCTION_NAME_PREFIX

This is the prefix used to indicate a PojoPathFunction in a PojoPath. The value (64) will never change. It is NOT necessary to use this constant to construct a PojoPath.
For example the segment @myFunction as part of a PojoPath such as foo.bar.@myFunction indicates that the PojoPathFunction named myFunction should be invoked to get, create or set the value for @myFunction based on the result retrieved for foo.bar.

See Also:

PojoPath.getFunction(), Constant Field Values

Method Detail

isDeterministic

boolean isDeterministic()

This method determines if this PojoPathFunction is deterministic. In this case it has to guarantee that repetitive calls of get with the same (unmodified) actual Pojo will produce the same result.
Typically a PojoPathFunction should be deterministic. However in some cases the calculation of a PojoPathFunction may depend on the current time or a random value and will therefore be indeterministic.
If a PojoPathFunction is indeterministic, the caching will disabled for its result and further traversals.
Of course this method has to be deterministic and should always return the same boolean result for the same instance.

Returns:

true if this function is deterministic, false otherwise.

getInputClass

Class<IN> getInputClass()

This method gets the input-type of this function. It is the type of the Pojos this function operates on.

Returns:

the input class.

getValueClass

Class<VALUE> getValueClass()

This method gets the output-type (or return-type) of this function. It is the type of the value this function traverses to, starting from the input- Pojo.

Returns:

the output class.

get

VALUE get(IN input,
          String functionName,
          PojoPathContext context)

This method gets the value of this function. It is invoked by PojoPathNavigator. get independent of the PojoPathMode. A regular implementation should only return what is already there. However in specific cases this may NOT (initially) be available from the given Pojo actual and therefore be retrieved from somewhere else (e.g. a database using a primary key given via a property of the given context). Further it can be legal to modify the actual Pojo e.g. by attaching the externally retrieved result.

Parameters:

input - is the actual Pojo where this function is invoked on. Typically the returned value should be retrieved via this object.

functionName - is the name under which this PojoPathFunction was invoked via the PojoPathNavigator excluding the FUNCTION_NAME_PREFIX.

context - is the PojoPathContext providing additional context information. Objects traversed between actual and the returned value should be recognized via the recognizer.

Returns:

the value of this function or null if NOT available.

create

VALUE create(IN input,
             String functionName,
             PojoPathContext context)

This method creates an appropriate new value. It is invoked by PojoPathNavigator. get if the mode is PojoPathMode.CREATE_IF_NULL after get returned null.
A typical implementation may create a new instance of <VALUE> via the pojo-factory. Further in most cases the created value instance will be attached to the given actual Pojo.

Parameters:

input - is the actual Pojo where this function is invoked on. Typically the returned value should be retrieved via this object.

functionName - is the name under which this PojoPathFunction was invoked via the PojoPathNavigator excluding the FUNCTION_NAME_PREFIX.

context - is the PojoPathContext providing additional context information. Objects traversed between actual and the returned value should be recognized via the recognizer.

Returns:

the created value. It may be null if creation is NOT possible. However returning null here will cause the PojoPathNavigator to fail with an exception.

set

VALUE set(IN input,
          String functionName,
          VALUE value,
          PojoPathContext context)

This method sets the given value for the given actual Pojo.
After this method has been successfully invoked, the method get should return the same value for identical arguments.

Parameters:

input - is the actual Pojo where this function is invoked on. Typically the given value should be set in this object.

functionName - is the name under which this PojoPathFunction was invoked via the PojoPathNavigator excluding the FUNCTION_NAME_PREFIX.

value - is the value to set.

context - is the PojoPathContext providing additional context information. Objects traversed between actual and the returned value should be recognized via the recognizer.

Returns:

the previous value that has been replaced or null.