com.bigdata.bop

Interface IPredicate<E>

All Superinterfaces:

BOp, Cloneable, IPropertySet, Serializable

All Known Subinterfaces:

IStarJoin<E>

All Known Implementing Classes:

AbstractRuleTestCase.P, LexPredicate, Predicate, SPOPredicate, SPOStarJoin, TestSPORelation.P

public interface IPredicate<E>
extends BOp, Cloneable, Serializable

An immutable constraint on the elements visited using an IAccessPath. The slots in the predicate corresponding to variables are named and those names establish binding patterns access IPredicates. Access is provided to slots by ordinal index regardless of whether or not they are named variables.

Version:

$Id$

Author:

Bryan Thompson

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	IPredicate.Annotations Interface declaring well known annotations.

Field Summary

Fields inherited from interface com.bigdata.bop.BOp

NOANNS, NOARGS

Method Summary

Methods

Modifier and Type	Method and Description
IPredicate<E>	asBound(IBindingSet bindingSet) Return a new instance in which all occurrences of the variable appearing in the binding set have been replaced by their bound values.
Object	asBound(int index, IBindingSet bindingSet) Extract the as bound value from the predicate.
Predicate<E>	asBound(IVariable<?> var, IConstant<?> val) Return a new instance in which all occurrences of the given variable have been replaced by the specified constant.
boolean	equals(Object other) Compares the bindings of two predicates for equality.
IConstant<?>	get(E e, int index) Deprecated. by IElement.get(int) which does exactly what this method is trying to do.
IVariableOrConstant	get(int index) Return the variable or constant at the specified index.
IAccessPathExpander<E>	getAccessPathExpander() Returns the object that may be used to selectively override the evaluation of the predicate.
IFilter	getAccessPathFilter() Return the optional filter to be evaluated once tuples have been converted into relation elements by the access path (local to the caller).
IFilter	getIndexLocalFilter() Return the optional filter to be evaluated local to the index.
IKeyOrder<E>	getKeyOrder() Return the IKeyOrder override for this IPredicate by the query optimizer.
String	getOnlyRelationName() Resource identifier (aka namespace) identifies the IRelation associated with this IPredicate.
int	getPartitionId() The index partition identifier and -1 if no partition identifier was specified.
int	getRelationCount() Deprecated. per getRelationName(int).
String	getRelationName(int index) Deprecated. Unions of predicates must be handled explicitly as a union of pipeline operators reading against the different predicate.
long	getTimestamp() The timestamp or transaction identifier on which the operator will read or write.
int	getVariableCount() Deprecated. This is only used in a few places, which should probably use BOpUtility.getArgumentVariableCount(BOp) instead.
int	getVariableCount(IKeyOrder<E> keyOrder) The #of arguments in the predicate required for the specified IKeyOrder which are unbound.
int	hashCode() The hash code is defined as
boolean	isFullyBound(IKeyOrder<E> keyOrder) Figure out if all positions in the predicate which are required to form the key for this access path are bound in the predicate.
boolean	isOptional() true iff the predicate is optional when evaluated as the right-hand side of a join.
boolean	isRemoteAccessPath() Return true if this is a remote access path.
IPredicate<E>	setArg(int index, IVariableOrConstant arg) Return a copy of this predicate with a different IVariableOrConstant for the arg specified by the supplied index parameter.
IPredicate<E>	setBOpId(int bopId) Sets the BOp.Annotations.BOP_ID annotation.
IPredicate<E>	setPartitionId(int partitionId) Sets the index partition identifier constraint.
IPredicate<E>	setRelationName(String[] relationName) Deprecated. This will be modified to use a scalar relation name per getOnlyRelationName().
String	toString() Representation of the predicate without variable bindings.
String	toString(IBindingSet bindingSet) Representation of the predicate with variable bindings.

Methods inherited from interface com.bigdata.bop.BOp

annotations, argIterator, args, arity, clone, getEvaluationContext, getId, getProperty, getRequiredProperty, isController, setProperty, toArray, toArray, toShortString, toString

Methods inherited from interface cutthecrap.utils.striterators.IPropertySet

getProperty

Method Detail

getOnlyRelationName

String getOnlyRelationName()

Resource identifier (aka namespace) identifies the IRelation associated with this IPredicate.

Throws:

IllegalStateException - if there is more than on element in the view.

See Also:

ILocatableResourceAnnotations.RELATION_NAME

getRelationName

String getRelationName(int index)

Deprecated. Unions of predicates must be handled explicitly as a union of pipeline operators reading against the different predicate.

Return the ith element of the relation view. The view is an ordered array of resource identifiers that describes the view for the relation.

Parameters:

index - The index into the array of relation names in the view.

getRelationCount

int getRelationCount()

Deprecated. per getRelationName(int).

The #of elements in the relation view.

getPartitionId

int getPartitionId()

The index partition identifier and -1 if no partition identifier was specified.

Returns:

The index partition identifier -or- -1 if the predicate is not locked to a specific index partition.

See Also:

IPredicate.Annotations.PARTITION_ID, PartitionLocator, AccessPath, JoinMasterTask

setPartitionId

IPredicate<E> setPartitionId(int partitionId)

Sets the index partition identifier constraint.

Parameters:

partitionId - The index partition identifier.

Returns:

The constrained IPredicate.

Throws:

IllegalArgumentException - if the index partition identified is a negative integer.

IllegalStateException - if the index partition identifier was already specified.

See Also:

IPredicate.Annotations.PARTITION_ID

isOptional

boolean isOptional()

true iff the predicate is optional when evaluated as the right-hand side of a join. An optional predicate will match once after all matches in the data have been exhausted. By default, the match will NOT bind any variables that have been determined to be bound by the predicate based on the computed IEvaluationPlan.

For mutation, some IRelations may require that all variables appearing in the head are bound. This and similar constraints can be enforced using IConstraints on the IRule.

Returns:

true iff this predicate is optional when evaluating a JOIN.

getAccessPathExpander

IAccessPathExpander<E> getAccessPathExpander()

Returns the object that may be used to selectively override the evaluation of the predicate.

Returns:

The IAccessPathExpander.

See Also:

IPredicate.Annotations.ACCESS_PATH_EXPANDER

getIndexLocalFilter

IFilter getIndexLocalFilter()

Return the optional filter to be evaluated local to the index.

See Also:

IPredicate.Annotations.INDEX_LOCAL_FILTER

getAccessPathFilter

IFilter getAccessPathFilter()

Return the optional filter to be evaluated once tuples have been converted into relation elements by the access path (local to the caller).

See Also:

IPredicate.Annotations.ACCESS_PATH_FILTER

getKeyOrder

IKeyOrder<E> getKeyOrder()

Return the IKeyOrder override for this IPredicate by the query optimizer.

Returns:

The assigned IKeyOrder or null if the IKeyOrder was not overridden.

See Also:

IPredicate.Annotations.KEY_ORDER

isFullyBound

boolean isFullyBound(IKeyOrder<E> keyOrder)

Figure out if all positions in the predicate which are required to form the key for this access path are bound in the predicate.

getVariableCount

int getVariableCount()

Deprecated. This is only used in a few places, which should probably use BOpUtility.getArgumentVariableCount(BOp) instead.

getVariableCount

int getVariableCount(IKeyOrder<E> keyOrder)

The #of arguments in the predicate required for the specified IKeyOrder which are unbound.

Parameters:

keyOrder - The key order.

Returns:

The #of unbound arguments for that IKeyOrder.

isRemoteAccessPath

boolean isRemoteAccessPath()

Return true if this is a remote access path.

See Also:

IPredicate.Annotations.REMOTE_ACCESS_PATH

get

IVariableOrConstant get(int index)

Return the variable or constant at the specified index.

Specified by:

get in interface BOp

Parameters:

index - The index.

Returns:

The variable or constant at the specified index.

Throws:

IllegalArgumentException - if the index is less than zero or GTE the BOp.arity() of the IPredicate.

get

IConstant<?> get(E e,
               int index)

Deprecated. by IElement.get(int) which does exactly what this method is trying to do.

Return the asBound value at the specified index for the given element. This method does not consider the bindings of the predicate instance.

Note: there is no general means available to implement this method of an awareness of the internal structure of the element type. General purpose record types, such as GOM or relation records, can generally implement this method in the context of the "schema" imposed by the predicate.

Parameters:

e - The element, which must implement IElement.

index - The index.

Returns:

The value.

Throws:

UnsupportedOperationException - If this operation is not supported by the IPredicate implementation or for the given element type.

asBound

Predicate<E> asBound(IVariable<?> var,
                   IConstant<?> val)

Return a new instance in which all occurrences of the given variable have been replaced by the specified constant.

Note: The optimal IKeyOrder often changes when binding a variable on a predicate.

Parameters:

var - The variable.

val - The constant.

Returns:

A new instance of the predicate in which all occurrences of the variable have been replaced by the constant.

Throws:

IllegalArgumentException - if either argument is null.

asBound

IPredicate<E> asBound(IBindingSet bindingSet)

Return a new instance in which all occurrences of the variable appearing in the binding set have been replaced by their bound values.

Note: The optimal IKeyOrder often changes when binding a variable on a predicate.

Parameters:

bindingSet - The binding set.

Returns:

The as-bound IPredicate -or- null if the IPredicate can not be unified with the IBindingSet.

See Also:

(RDR query does too much work)

asBound

Object asBound(int index,
             IBindingSet bindingSet)

Extract the as bound value from the predicate. When the predicate is not bound at that index, the value of the variable is taken from the binding set.

Parameters:

index - The index into that predicate.

bindingSet - The binding set.

Returns:

The bound value -or- null if no binding is available (the predicate is not bound at that index and the variable at that index in the predicate is not bound in the binding set).

Throws:

IndexOutOfBoundsException - unless the index is in [0:{@link #arity()-1], inclusive.

IllegalArgumentException - if the bindingSet is null.

setRelationName

IPredicate<E> setRelationName(String[] relationName)

Deprecated. This will be modified to use a scalar relation name per getOnlyRelationName().

A copy of this IPredicate in which the relationName(s) replace the existing set of relation name(s).

Parameters:

relationName - The relation name(s).

Throws:

IllegalArgumentException - if relationName is empty.

IllegalArgumentException - if relationName is null

IllegalArgumentException - if any element of relationName is null

toString

String toString()

Representation of the predicate without variable bindings.

Specified by:

toString in interface BOp

Overrides:

toString in class Object

toString

String toString(IBindingSet bindingSet)

Representation of the predicate with variable bindings.

Parameters:

bindingSet - The variable bindings

equals

boolean equals(Object other)

Compares the bindings of two predicates for equality.

Overrides:

equals in class Object

Parameters:

other - Another predicate.

Returns:

true iff the predicate have the same arity and their ordered bindings are the same. when both predicates have a variable at a given index, the names of the variables must be the same.

hashCode

int hashCode()

The hash code is defined as

 get(0).hashCode()*31ˆ(n-1) + get(1).hashCode()*31ˆ(n-2) + ... + get(n-1).hashCode()
 

using int arithmetic, where n is the BOp.arity() of the predicate, and ^ indicates exponentiation.

Note: This is similar to how String.hashCode() is defined.

Overrides:

hashCode in class Object

setBOpId

IPredicate<E> setBOpId(int bopId)

Sets the BOp.Annotations.BOP_ID annotation.

Parameters:

bopId - The bop id.

Returns:

The newly annotated IPredicate.

setArg

IPredicate<E> setArg(int index,
                   IVariableOrConstant arg)

Return a copy of this predicate with a different IVariableOrConstant for the arg specified by the supplied index parameter.

getTimestamp

long getTimestamp()

The timestamp or transaction identifier on which the operator will read or write.

Throws:

IllegalStateException - if ITimestampAnnotations.TIMESTAMP was not specified.

See Also:

ITimestampAnnotations.TIMESTAMP