com.bigdata.relation.rule
Class Predicate<E>

java.lang.Object
  com.bigdata.relation.rule.Predicate<E>

All Implemented Interfaces:

IPredicate<E>, Serializable, Cloneable

public class Predicate<E>
extends Object
implements IPredicate<E>

A generic implementation of an immutable IPredicate.

Version:

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

Author:

Bryan Thompson

See Also:

Serialized Form

Constructor Summary

protected	Predicate(Predicate<E> src, IBindingSet bindingSet) Copy constructor creates a new instance of this class with any unbound variables overriden by their bindings from the given binding set (if any).
protected	Predicate(Predicate<E> src, int partitionId) Copy constructor creates a new instance of this class in which the index partition constraint as specified.
protected	Predicate(Predicate<E> src, String[] relationName) Copy constructor creates a new instance of this class replacing the existing relation name(s) with the given one(s).
	Predicate(String[] relationName, int partitionId, IVariableOrConstant[] values, boolean optional, IElementFilter<E> constraint, ISolutionExpander<E> expander) Fully specified ctor.
	Predicate(String relationName, IVariableOrConstant[] values) Simplified ctor.

Method Summary

int	arity() The #of slots in the predicate.
Predicate<E>	asBound(IBindingSet bindingSet) Note: easily implemented using toArray(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()
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.
Predicate<E>	setPartitionId(int partitionId) Sets the index partition identifier constraint.
Predicate<E>	setRelationName(String[] relationName) A copy of this IPredicate in which the relationName(s) replace the existing set of relation name(s).
IVariableOrConstant[]	toArray(IBindingSet bindingSet) Returns an ordered array of the values for this predicate with the given bindings overriding any unbound variables.
String	toString() Representation of the predicate without variable bindings.
String	toString(IBindingSet bindingSet) Representation of the predicate with variable bindings.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Predicate

protected Predicate(Predicate<E> src,
                    IBindingSet bindingSet)

Copy constructor creates a new instance of this class with any unbound variables overriden by their bindings from the given binding set (if any).

Parameters:

src - The source predicate.

bindingSet - Additional bindings.

Predicate

protected Predicate(Predicate<E> src,
                    String[] relationName)

Copy constructor creates a new instance of this class replacing the existing relation name(s) with the given one(s).

Parameters:

src - The source predicate.

relationName - The new relation name(s).

Predicate

protected Predicate(Predicate<E> src,
                    int partitionId)

Copy constructor creates a new instance of this class in which the index partition constraint as specified.

Parameters:

src - The source predicate.

partitionId - The index partition constraint.

Throws:

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

IllegalStateException - if the index partition identifier was already specified.

Predicate

public Predicate(String relationName,
                 IVariableOrConstant[] values)

Simplified ctor.

Parameters:

relationName - Identifies the relation to be queried.

values - The values (order is important!).

Predicate

public Predicate(String[] relationName,
                 int partitionId,
                 IVariableOrConstant[] values,
                 boolean optional,
                 IElementFilter<E> constraint,
                 ISolutionExpander<E> expander)

Fully specified ctor.

Parameters:

relationName - Identifies the relation(s) in the view.

partitionId - The index partition constraint -or- -1 if there is no index partition constraint.

values - The values (order is important!).

optional - true iff the predicate is optional when evaluated in a JOIN.

constraint - An optional constraint.

expander - Allows selective override of the predicate evaluation.

Method Detail

getOnlyRelationName

public String getOnlyRelationName()

Description copied from interface: IPredicate

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.

Specified by:

getOnlyRelationName in interface IPredicate<E>

getRelationName

public String getRelationName(int index)

Description copied from interface: IPredicate

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

Specified by:

getRelationName in interface IPredicate<E>

Parameters:

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

getPartitionId

public int getPartitionId()

Description copied from interface: IPredicate

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.

Specified by:

getPartitionId in interface IPredicate<E>

Returns:

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

See Also:

PartitionLocator, AbstractAccessPath, JoinMasterTask

getRelationCount

public int getRelationCount()

Description copied from interface: IPredicate

The #of elements in the relation view.

Specified by:

getRelationCount in interface IPredicate<E>

arity

public final int arity()

Description copied from interface: IPredicate

The #of slots in the predicate.

Specified by:

arity in interface IPredicate<E>

get

public IVariableOrConstant<?> get(int index)

Description copied from interface: IPredicate

Return the variable or constant at the specified index.

Specified by:

get in interface IPredicate<E>

Parameters:

index - The index.

Returns:

The variable or constant at the specified index.

get

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

Description copied from interface: IPredicate

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.

Specified by:

get in interface IPredicate<E>

Parameters:

e - The element.

index - The index.

Returns:

The value.

TODO:

there is no general means available to implement this method of an awareness of the internal structure of the element type.

isOptional

public final boolean isOptional()

Description copied from interface: IPredicate

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.

Specified by:

isOptional in interface IPredicate<E>

Returns:

true iff this predicate is optional when evaluating a JOIN.

getConstraint

public final IElementFilter<E> getConstraint()

Description copied from interface: IPredicate

An optional constraint on the visitable elements.

Specified by:

getConstraint in interface IPredicate<E>

getSolutionExpander

public final ISolutionExpander<E> getSolutionExpander()

Description copied from interface: IPredicate

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

Specified by:

getSolutionExpander in interface IPredicate<E>

Returns:

The ISolutionExpander.

getVariableCount

public final int getVariableCount()

Description copied from interface: IPredicate

The #of arguments in the predicate that are variables.

Specified by:

getVariableCount in interface IPredicate<E>

See Also:

IPredicate.getVariableCount(IKeyOrder)

isFullyBound

public final boolean isFullyBound()

Deprecated. by isFullyBound()

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

Specified by:

isFullyBound in interface IPredicate<E>

isFullyBound

public boolean isFullyBound(IKeyOrder<E> keyOrder)

Description copied from interface: IPredicate

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 IPredicate.isFullyBound() since the latter does not know which the slots in the predicate are required for the specified key order.

Specified by:

isFullyBound in interface IPredicate<E>

getVariableCount

public int getVariableCount(IKeyOrder<E> keyOrder)

Description copied from interface: IPredicate

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

Specified by:

getVariableCount in interface IPredicate<E>

Parameters:

keyOrder - The key order.

Returns:

The #of unbound arguments for that IKeyOrder.

toArray

public IVariableOrConstant[] toArray(IBindingSet bindingSet)

Returns an ordered array of the values for this predicate with the given bindings overriding any unbound variables.

Parameters:

bindingSet - The bindings (optional).

Returns:

asBound

public Predicate<E> asBound(IBindingSet bindingSet)

Note: easily implemented using toArray(IBindingSet).

Specified by:

asBound in interface IPredicate<E>

setRelationName

public Predicate<E> setRelationName(String[] relationName)

Description copied from interface: IPredicate

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

Specified by:

setRelationName in interface IPredicate<E>

Parameters:

relationName - The relation name(s).

setPartitionId

public Predicate<E> setPartitionId(int partitionId)

Description copied from interface: IPredicate

Sets the index partition identifier constraint.

Specified by:

setPartitionId in interface IPredicate<E>

Parameters:

partitionId - The index partition identifier.

Returns:

The constrained IPredicate.

toString

public String toString()

Description copied from interface: IPredicate

Representation of the predicate without variable bindings.

Specified by:

toString in interface IPredicate<E>

Overrides:

toString in class Object

toString

public String toString(IBindingSet bindingSet)

Description copied from interface: IPredicate

Representation of the predicate with variable bindings.

Specified by:

toString in interface IPredicate<E>

Parameters:

bindingSet - The variable bindings

equals

public boolean equals(Object other)

Description copied from interface: IPredicate

Compares the bindings of two predicates for equality.

Specified by:

equals in interface IPredicate<E>

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

public int hashCode()

Description copied from interface: IPredicate

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

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

Specified by:

hashCode in interface IPredicate<E>

Overrides:

hashCode in class Object