com.bigdata.relation.rule
Interface IPredicate<E>

All Superinterfaces:

Cloneable, Serializable

All Known Implementing Classes:

MagicPredicate, Predicate, SPOPredicate

public interface IPredicate<E>
extends 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 in the context of a IRule. Access is provided to slots by ordinal index regardless of whether or not they are named variables.

Version:

$Id: IPredicate.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

Method Summary

int	arity() The #of slots in the predicate.
IPredicate<E>	asBound(IBindingSet bindingSet) A copy of this IPredicate in which zero or more variables have been bound to constants using the given IBindingSet.
boolean	equals(Object other) Compares the bindings of two predicates for equality.
IConstant<?>	get(E e, int index) Return the asBound value at the specified index for the given element.
IVariableOrConstant	get(int index) Return the variable or constant at the specified index.
IElementFilter<E>	getConstraint() An optional constraint on the visitable elements.
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() The #of elements in the relation view.
String	getRelationName(int index) Return the ith element of the relation view.
ISolutionExpander<E>	getSolutionExpander() Returns the object that may be used to selectively override the evaluation of the predicate.
int	getVariableCount() The #of arguments in the predicate that are variables.
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() Deprecated. by isFullyBound(IKeyOrder)
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.
IPredicate<E>	setPartitionId(int partitionId) Sets the index partition identifier constraint.
IPredicate<E>	setRelationName(String[] relationName) A copy of this IPredicate in which the relationName(s) replace the existing set of relation name(s).
String	toString() Representation of the predicate without variable bindings.
String	toString(IBindingSet bindingSet) Representation of the predicate with variable bindings.

Method Detail

getOnlyRelationName

String getOnlyRelationName()

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

This is more or less ignored when the IRule is executed as a query.

When the IRule is executed as an ActionEnum.Insert or ActionEnum.Delete then this identifies the target IMutableRelation on which the computed ISolutions will be written.

Throws:

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

getRelationName

String getRelationName(int index)

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.

TODO:

is there any particular reason to use an ordered view? TM does not appear to require this and we always write on the relation that is associated with the head of the rule, and that should always be the "database" (vs the focusStore).

getRelationCount

int getRelationCount()

The #of elements in the relation view.

getPartitionId

int getPartitionId()

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

Note: The ability to specify an index partition identifier for a predicate is provided in support of scale-out JOIN strategies. The AbstractAccessPath and the JoinMasterTask are both aware of this property. The JoinMasterTask sets the partition identifier in order to request an access path backed by the name of the local index object on a DataService rather than the name of the scale-out index.

The index partition can not be specified until a choice has been made concerning which IAccessPath to use for a predicate without an index partition constraint. The IAccessPath choice is therefore made by the IEvaluationPlan using the scale-out index view and an AbstractScaleOutFederation.locatorScan(String, long, byte[], byte[], boolean) is used to identify the index partitions on which the IAccessPath will read. The index partition is then set on a constrained IPredicate for each target index partition and the JOINs are then distributed to the DataServices on which those index partitions reside.

Returns:

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

See Also:

PartitionLocator, AbstractAccessPath, 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.

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.

More control over the behavior of optionals may be gained through the use of an ISolutionExpander pattern.

Returns:

true iff this predicate is optional when evaluating a JOIN.

getSolutionExpander

ISolutionExpander<E> getSolutionExpander()

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

Returns:

The ISolutionExpander.

TODO:

replace with ISolutionExpander.getAccessPath(IAccessPath), which is the only method declared by ISolutionExpander.

getConstraint

IElementFilter<E> getConstraint()

An optional constraint on the visitable elements.

isFullyBound

boolean isFullyBound()

Deprecated. by isFullyBound(IKeyOrder)

Return true iff all arguments of the predicate are bound (vs variables).

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.

Note: This is more correct than isFullyBound() since the latter does not know which the slots in the predicate are required for the specified key order.

getVariableCount

int getVariableCount()

The #of arguments in the predicate that are variables.

See Also:

getVariableCount(IKeyOrder)

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.

arity

int arity()

The #of slots in the predicate.

get

IVariableOrConstant get(int index)

Return the variable or constant at the specified index.

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 arity() of the IPredicate.

get

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

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.

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

IPredicate<E> asBound(IBindingSet bindingSet)

A copy of this IPredicate in which zero or more variables have been bound to constants using the given IBindingSet.

setRelationName

IPredicate<E> setRelationName(String[] relationName)

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.

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 arity() of the predicate, and ^ indicates exponentiation.

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

Overrides:

hashCode in class Object