Cumulus4j API
(1.0.0)

org.cumulus4j.store.query.eval
Class AbstractExpressionEvaluator<X extends Expression>

java.lang.Object
  extended by org.cumulus4j.store.query.eval.AbstractExpressionEvaluator<X>
Type Parameters:
X - the Expression to be evaluated.
Direct Known Subclasses:
AndExpressionEvaluator, ComparisonExpressionEvaluator, InvokeExpressionEvaluator, LiteralEvaluator, NotExpressionEvaluator, OrExpressionEvaluator, ParameterExpressionEvaluator, PrimaryExpressionEvaluator, SubqueryExpressionEvaluator, VariableExpressionEvaluator

public abstract class AbstractExpressionEvaluator<X extends Expression>
extends Object

Abstract base class for all Expression evaluators.

DataNucleus gives the query implementation a tree composed of Expressions. This tree is nothing more than an object-oriented representation of the query to be executed. In order to actually query data, there needs to be evaluation logic applying the Expression to the Cumulus4j data structure. This logic is implemented in subclasses of AbstractExpressionEvaluator.

Author:
Marco หงุ่ยตระกูล-Schulze - marco at nightlabs dot de

Constructor Summary
AbstractExpressionEvaluator(QueryEvaluator queryEvaluator, AbstractExpressionEvaluator<?> parent, X expression)
          Create an AbstractExpressionEvaluator instance.
 
Method Summary
protected  Set<Symbol> _getResultSymbols()
           Get the Symbols for which queryResultDataEntryIDs(ResultDescriptor) (and thus queryResultObjects(ResultDescriptor)) can return a result.
protected abstract  Set<Long> _queryResultDataEntryIDs(ResultDescriptor resultDescriptor)
          Execute a query for the given resultDescriptor.
protected  List<Object> _queryResultObjects(ResultDescriptor resultDescriptor)
           Get those objects that match the query criteria for the specified resultDescriptor or null, if the given symbol is not queryable by the evaluator implementation.
 X getExpression()
          Get the expression that is to be evaluated by this AbstractExpressionEvaluator.
protected  Class<?> getFieldType(PrimaryExpression primaryExpression)
           Get the field type of the PrimaryExpression.
 AbstractExpressionEvaluator<? extends Expression> getLeft()
          Get the left branch in the tree structure.
 AbstractExpressionEvaluator<?> getParent()
          Get the parent-node in the tree.
 QueryEvaluator getQueryEvaluator()
          Get the evaluator responsible for evaluating the entire query.
 Set<Symbol> getResultSymbols()
           Get the Symbols for which queryResultDataEntryIDs(ResultDescriptor) (and thus queryResultObjects(ResultDescriptor)) can return a result.
 AbstractExpressionEvaluator<? extends Expression> getRight()
          Get the right branch in the tree structure.
 Set<Long> queryResultDataEntryIDs(ResultDescriptor resultDescriptor)
           Get those dataEntryIDs that match the query criteria for the specified resultDescriptor or null, if the given symbol is not queryable by the evaluator implementation.
 List<Object> queryResultObjects(ResultDescriptor resultDescriptor)
           Get those objects that match the query criteria for the specified resultDescriptor or null, if the given symbol is not queryable by the evaluator implementation.
 void setLeft(AbstractExpressionEvaluator<? extends Expression> left)
          Set the left branch in the tree structure.
 void setRight(AbstractExpressionEvaluator<? extends Expression> right)
          Set the right branch in the tree structure.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AbstractExpressionEvaluator

public AbstractExpressionEvaluator(QueryEvaluator queryEvaluator,
                                   AbstractExpressionEvaluator<?> parent,
                                   X expression)
Create an AbstractExpressionEvaluator instance.

Parameters:
queryEvaluator - the evaluator responsible for evaluating the entire query. Must not be null.
parent - the parent-node in the tree. The AbstractExpressionEvaluators form a tree analogue to the tree provided by DataNucleus. This parent is null, if it is the root of the tree.
expression - the expression that is to be evaluated by this AbstractExpressionEvaluator instance.
Method Detail

getQueryEvaluator

public QueryEvaluator getQueryEvaluator()
Get the evaluator responsible for evaluating the entire query.

Returns:
the evaluator responsible for evaluating the entire query.

getParent

public AbstractExpressionEvaluator<?> getParent()
Get the parent-node in the tree. The AbstractExpressionEvaluators form a tree analogue to the tree provided by DataNucleus. This parent is null, if it is the root of the tree.

Returns:
the parent-node in the tree or null, if this is the root.

getExpression

public X getExpression()
Get the expression that is to be evaluated by this AbstractExpressionEvaluator.

Returns:
the expression that is to be evaluated by this AbstractExpressionEvaluator.

getLeft

public AbstractExpressionEvaluator<? extends Expression> getLeft()
Get the left branch in the tree structure.

Returns:
the left branch in the tree structure or null if there is none.
See Also:
setLeft(AbstractExpressionEvaluator), getRight()

setLeft

public void setLeft(AbstractExpressionEvaluator<? extends Expression> left)
Set the left branch in the tree structure.

Parameters:
left - the left branch in the tree structure or null if there is none.
See Also:
getLeft()

getRight

public AbstractExpressionEvaluator<? extends Expression> getRight()
Get the right branch in the tree structure.

Returns:
the right branch in the tree structure or null if there is none.
See Also:
setRight(AbstractExpressionEvaluator), getLeft()

setRight

public void setRight(AbstractExpressionEvaluator<? extends Expression> right)
Set the right branch in the tree structure.

Parameters:
right - the right branch in the tree structure or null if there is none.
See Also:
getRight()

getResultSymbols

public final Set<Symbol> getResultSymbols()

Get the Symbols for which queryResultDataEntryIDs(ResultDescriptor) (and thus queryResultObjects(ResultDescriptor)) can return a result. For all other Symbols, said methods return null.

The implementation in AbstractExpressionEvaluator delegates to _getResultSymbols() and caches the result.

Do not override this method, if you're not absolutely sure you want to deactivate/override the caching! In most cases, you should override _getResultSymbols() instead.

Returns:
the queryable Symbols; never null.
See Also:
_getResultSymbols()

_getResultSymbols

protected Set<Symbol> _getResultSymbols()

Get the Symbols for which queryResultDataEntryIDs(ResultDescriptor) (and thus queryResultObjects(ResultDescriptor)) can return a result. For all other Symbols, said methods return null.

The default implementation in AbstractExpressionEvaluator collects the result-symbols from its left and its right side and returns this combined Set.

This is the actual implementation of getResultSymbols() and should be overridden instead of the non-"_"-prefixed version, in most cases.

Returns:
the queryable Symbols or null (null is equivalent to an empty Set).
See Also:
getResultSymbols()

queryResultDataEntryIDs

public final Set<Long> queryResultDataEntryIDs(ResultDescriptor resultDescriptor)
                                        throws UnsupportedOperationException

Get those dataEntryIDs that match the query criteria for the specified resultDescriptor or null, if the given symbol is not queryable by the evaluator implementation.

This method delegates to _queryResultDataEntryIDs(ResultDescriptor) and caches the result. Thus a second call to this method with the same symbol does not trigger a second query but instead immediately returns the cached result.

If the subclass of AbstractExpressionEvaluator does not support querying on its own (e.g. querying a literal makes no sense at all), this method throws an UnsupportedOperationException. The same exception is thrown, if the requested query functionality is not yet implemented.

Parameters:
resultDescriptor - the descriptor specifying what candidates (usually "this" or a variable) the caller is interested in as well as modifiers (e.g. negation) affecting the query.
Returns:
those dataEntryIDs that match the query criteria for the specified resultSymbol or null, if the symbol is not supported (this should be consistent with the implementation of _getResultSymbols()).
Throws:
UnsupportedOperationException - if the implementation does not support querying at all (e.g. because it makes no sense without more context) or if the concrete query situation is not yet supported.
See Also:
_queryResultDataEntryIDs(ResultDescriptor)

_queryResultDataEntryIDs

protected abstract Set<Long> _queryResultDataEntryIDs(ResultDescriptor resultDescriptor)
                                               throws UnsupportedOperationException
Execute a query for the given resultDescriptor. This method should contain the concrete logic for queryResultDataEntryIDs(ResultDescriptor) and must be implemented by subclasses.

Parameters:
resultDescriptor - the descriptor specifying what candidates (usually "this" or a variable) the caller is interested in as well as modifiers (e.g. negation) affecting the query.
Returns:
those dataEntryIDs that match the query criteria for the specified resultSymbol or null, if the symbol is not supported (this should be consistent with the implementation of _getResultSymbols()).
Throws:
UnsupportedOperationException - if the implementation does not support querying at all (e.g. because it makes no sense without more context) or if the concrete query situation is not yet supported.
See Also:
queryResultDataEntryIDs(ResultDescriptor)

queryResultObjects

public final List<Object> queryResultObjects(ResultDescriptor resultDescriptor)
                                      throws UnsupportedOperationException

Get those objects that match the query criteria for the specified resultDescriptor or null, if the given symbol is not queryable by the evaluator implementation.

This method delegates to _queryResultObjects(ResultDescriptor) and caches the result. Thus a second call to this method with the same symbol does not trigger a second query but instead immediately returns the cached result.

If the subclass of AbstractExpressionEvaluator does not support querying on its own (e.g. querying a literal makes no sense at all), this method throws an UnsupportedOperationException. The same exception is thrown, if the requested query functionality is not yet implemented.

Parameters:
resultDescriptor - the descriptor specifying what candidates (usually "this" or a variable) the caller is interested in as well as modifiers (e.g. negation) affecting the query.
Returns:
the objects matching the criteria or null, if the given resultSymbol is not supported (this should be consistent with the implementation of _getResultSymbols()).
Throws:
UnsupportedOperationException - if the implementation does not support querying at all (e.g. because it makes no sense without more context) or if the concrete query situation is not yet supported.
See Also:
_queryResultObjects(ResultDescriptor)

_queryResultObjects

protected List<Object> _queryResultObjects(ResultDescriptor resultDescriptor)
                                    throws UnsupportedOperationException

Get those objects that match the query criteria for the specified resultDescriptor or null, if the given symbol is not queryable by the evaluator implementation.

The default implementation of this method in AbstractExpressionEvaluator calls queryResultDataEntryIDs(ResultDescriptor) and then resolves the corresponding objects (including decrypting their data).

Parameters:
resultDescriptor - the descriptor specifying what candidates (usually "this" or a variable) the caller is interested in as well as modifiers (e.g. negation) affecting the query.
Returns:
the objects matching the criteria or null, if the given resultDescriptor is not supported (ResultDescriptor.getSymbol() should be consistent with the implementation of _getResultSymbols()).
Throws:
UnsupportedOperationException
See Also:
queryResultObjects(ResultDescriptor)

getFieldType

protected Class<?> getFieldType(PrimaryExpression primaryExpression)

Get the field type of the PrimaryExpression. This is always the type of the last element in the list of tuples.

For example, if the given PrimaryExpression references this.rating.name and the field name of the class Rating is a String, this method returns java.lang.String.

Parameters:
primaryExpression - the PrimaryExpression of which to find out the field's type.
Returns:
the type of the field referenced by the given primaryExpression.

Cumulus4j API
(1.0.0)

Copyright © 2012 NightLabs Consulting GmbH. All Rights Reserved.