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

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

All Implemented Interfaces:

IRule<E>, IStep, Serializable

Direct Known Subclasses:

AbstractRuleDistinctTermScan, AbstractRuleFastClosure_11_13, AbstractRuleFastClosure_3_5_6_7_9, MatchRule, RuleOwlEquivalentClass, RuleOwlEquivalentProperty, RuleOwlHasValue, RuleOwlInverseOf1, RuleOwlInverseOf2, RuleOwlSameAs1, RuleOwlSameAs1b, RuleOwlSameAs2, RuleOwlSameAs3, RuleOwlTransitiveProperty1, RuleOwlTransitiveProperty2, RuleRdfs02, RuleRdfs03, RuleRdfs05, RuleRdfs06, RuleRdfs07, RuleRdfs08, RuleRdfs09, RuleRdfs10, RuleRdfs11, RuleRdfs12, RuleRdfs13

public class Rule<E>
extends Object
implements IRule<E>

Default impl.

Version:

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

Author:

Bryan Thompson

See Also:

Serialized Form

Field Summary

protected static boolean	DEBUG
protected static boolean	INFO
protected static org.apache.log4j.Logger	log

Constructor Summary

Rule(String name, IPredicate head, IPredicate[] tail, IConstraint[] constraints)
Rule ctor.

Rule(String name, IPredicate head, IPredicate[] tail, IQueryOptions queryOptions, IConstraint[] constraints)
Rule ctor.

Rule(String name, IPredicate head, IPredicate[] tail, IQueryOptions queryOptions, IConstraint[] constraints, IBindingSet constants, IRuleTaskFactory taskFactory)
Fully specified ctor.

Method Summary

IBindingSet	getConstants() Returns any variables that were bound to constants when an IRule was specialized.
IConstraint	getConstraint(int index) Return the constraint at the given index.
int	getConstraintCount() The #of constraints on the legal states for bindings of the variables declared by rule.
Iterator<IConstraint>	getConstraints() The optional constraints.
IPredicate	getHead() The head of the rule -or- null iff there is no head for this rule.
String	getName() The name of the rule.
IQueryOptions	getQueryOptions() Return additional constraints that must be imposed during query evaluation.
Set<IVariable>	getSharedVars(int index1, int index2) Return the variables in common for two IPredicates.
static Set<IVariable>	getSharedVars(IPredicate p1, IPredicate p2) Return the variables in common for two IPredicates.
Iterator<IPredicate>	getTail() Iterator visits the IPredicates in the body (ala tail) of the rule.
IPredicate	getTail(int index) Return the predicate at the given index from the tail of the rule.
int	getTailCount() The #of IPredicates in the body (aka tail) of the rule.
IRuleTaskFactory	getTaskFactory() An optional IRuleTaskFactory that will be used in place of the default IRuleTaskFactory to evaluate this rule (optional)
int	getVariableCount() The #of distinct variables declared by the rule.
int	getVariableCount(int index, IBindingSet bindingSet) The #of arguments in the selected predicate that are variables (vs constants) with the given the bindings.
Iterator<IVariable>	getVariables() The variables declared by the rule in no particular order.
boolean	isConsistent(IBindingSet bindingSet) Return true unless the IBindingSet violates a IConstraint declared for this Rule.
boolean	isDeclared(IVariable var) Return true iff the rule declares this variable.
boolean	isFullyBound(IBindingSet bindingSet) If the rule is fully bound for the given bindings.
boolean	isFullyBound(int index, IBindingSet bindingSet) Return true iff the selected predicate is fully bound.
boolean	isRule() true iff the step is an IRule and false iff the step is an IProgram.
IRule<E>	specialize(IBindingSet bindingSet, IConstraint[] constraints) Specialize a rule - the name of the new rule will be derived from the name of the old rule with an appended single quote to indicate that it is a derived variant.
IRule<E>	specialize(String name, IBindingSet bindingSet, IConstraint[] constraints) Specialize a rule by binding zero or more variables and adding zero or more constraints.
String	toString() Externalizes the rule displaying variable names and constants.
String	toString(IBindingSet bindingSet) Externalizes the rule displaying variable names, their bindings, and constants.
protected static Var	var(String name) Singleton factory for Vars (delegates to Var.var(String)).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

log

protected static final transient org.apache.log4j.Logger log

INFO

protected static final transient boolean INFO

DEBUG

protected static final transient boolean DEBUG

Constructor Detail

Rule

public Rule(String name,
            IPredicate head,
            IPredicate[] tail,
            IConstraint[] constraints)

Rule ctor.

Parameters:

name - A label for the rule.

head - The subset of bindings that are selected by the rule.

tail - The tail (aka body) of the rule.

constraints - An array of constaints on the legal states of the bindings materialized for the rule.

Throws:

IllegalArgumentException - if the name is null.

IllegalArgumentException - if the head is null.

IllegalArgumentException - if the tail is null.

IllegalArgumentException - if any element of the tail is null.

IllegalArgumentException - if any element of the optional constraints is null.

IllegalArgumentException - if the tail is empty.

IllegalArgumentException - if the head declares any variables that are not declared in the tail.

Rule

public Rule(String name,
            IPredicate head,
            IPredicate[] tail,
            IQueryOptions queryOptions,
            IConstraint[] constraints)

Rule ctor.

Parameters:

name - A label for the rule.

head - The subset of bindings that are selected by the rule.

tail - The tail (aka body) of the rule.

queryOptions - Options that effect evaluation of the rule as a query.

constraints - An array of constaints on the legal states of the bindings materialized for the rule.

Throws:

IllegalArgumentException - if the name is null.

IllegalArgumentException - if the head is null.

IllegalArgumentException - if the tail is null.

IllegalArgumentException - if any element of the tail is null.

IllegalArgumentException - if any element of the optional constraints is null.

IllegalArgumentException - if the tail is empty.

IllegalArgumentException - if the head declares any variables that are not declared in the tail.

Rule

public Rule(String name,
            IPredicate head,
            IPredicate[] tail,
            IQueryOptions queryOptions,
            IConstraint[] constraints,
            IBindingSet constants,
            IRuleTaskFactory taskFactory)

Fully specified ctor.

Parameters:

name - The name of the rule.

head - The head of the rule. This is optional for rules that will be evaluated using ActionEnum.Query but required for rules that will be evaluated using a mutation ActionEnum.

tail - The predicates in the tail of the rule.

queryOptions - Additional constraints on the evaluate of a rule as a query (required, but see QueryOptions.NONE).

constraints - The constraints on the rule (optional).

constants - Bindings for variables that are bound as constants for the rule (optional).

taskFactory - Optional override for rule evaluation (MAY be null).

Method Detail

var

protected static Var var(String name)

Singleton factory for Vars (delegates to Var.var(String)).

See Also:

Var.var(String)

TODO:

it is a good idea to use this factory rather than Var.var(String) as the latter MAY be replaced by per-rule-instance variables rather than globally canonical variables

the only problem with this is that we need to access the variables in a bindingset by name after high-level query since the rule may not be available to the caller, e.g., the match rule uses dynamically generated rules that are not visible to the caller who only sees the binding sets.

getVariableCount

public final int getVariableCount()

Description copied from interface: IRule

The #of distinct variables declared by the rule.

Specified by:

getVariableCount in interface IRule<E>

getVariables

public final Iterator<IVariable> getVariables()

Description copied from interface: IRule

The variables declared by the rule in no particular order.

Specified by:

getVariables in interface IRule<E>

getTailCount

public final int getTailCount()

Description copied from interface: IRule

The #of IPredicates in the body (aka tail) of the rule.

Specified by:

getTailCount in interface IRule<E>

getHead

public final IPredicate getHead()

Description copied from interface: IRule

The head of the rule -or- null iff there is no head for this rule. Note that rules that are executed as queries DO NOT need to specify a head. However, rules that will be executed as mutation operations (insert or delete) MUST specify the head as it determines the IRelation on which the rule will write.

Specified by:

getHead in interface IRule<E>

See Also:

ActionEnum

getTail

public final Iterator<IPredicate> getTail()

Description copied from interface: IRule

Iterator visits the IPredicates in the body (ala tail) of the rule.

Specified by:

getTail in interface IRule<E>

getTail

public final IPredicate getTail(int index)

Description copied from interface: IRule

Return the predicate at the given index from the tail of the rule.

Specified by:

getTail in interface IRule<E>

Parameters:

index - The index.

Returns:

The predicate at that index.

getQueryOptions

public final IQueryOptions getQueryOptions()

Description copied from interface: IStep

Return additional constraints that must be imposed during query evaluation.

Specified by:

getQueryOptions in interface IStep

getConstraintCount

public final int getConstraintCount()

Description copied from interface: IRule

The #of constraints on the legal states for bindings of the variables declared by rule.

Specified by:

getConstraintCount in interface IRule<E>

getConstraint

public final IConstraint getConstraint(int index)

Description copied from interface: IRule

Return the constraint at the given index.

Specified by:

getConstraint in interface IRule<E>

Parameters:

index - The index.

Returns:

The constraint.

getConstraints

public final Iterator<IConstraint> getConstraints()

Description copied from interface: IRule

The optional constraints.

Specified by:

getConstraints in interface IRule<E>

getConstants

public final IBindingSet getConstants()

Description copied from interface: IRule

Returns any variables that were bound to constants when an IRule was specialized.

Note: IJoinNexus.newBindingSet(IRule) MUST apply the constants before returning the bindings to the caller.

Specified by:

getConstants in interface IRule<E>

Returns:

The bound constants.

getName

public final String getName()

Description copied from interface: IRule

The name of the rule.

Specified by:

getName in interface IRule<E>

Specified by:

getName in interface IStep

toString

public String toString()

Description copied from interface: IRule

Externalizes the rule displaying variable names and constants.

Specified by:

toString in interface IRule<E>

Specified by:

toString in interface IStep

Overrides:

toString in class Object

toString

public String toString(IBindingSet bindingSet)

Description copied from interface: IRule

Externalizes the rule displaying variable names, their bindings, and constants.

Specified by:

toString in interface IRule<E>

Parameters:

bindingSet - When non-null, the current variable bindings will be displayed. Otherwise, the names of variables will be displayed rather than their bindings.

specialize

public IRule<E> specialize(IBindingSet bindingSet,
                           IConstraint[] constraints)

Description copied from interface: IRule

Specialize a rule - the name of the new rule will be derived from the name of the old rule with an appended single quote to indicate that it is a derived variant.

Specified by:

specialize in interface IRule<E>

Parameters:

bindingSet - Bindings for zero or more free variables in this rule. The rule will be rewritten such that the variable is replaced by the binding throughout the rule. An attempt to bind a variable not declared by the rule will be ignored.

constraints - An array of additional constraints to be imposed on the rule (optional).

Returns:

The specialized rule.

specialize

public IRule<E> specialize(String name,
                           IBindingSet bindingSet,
                           IConstraint[] constraints)

Description copied from interface: IRule

Specialize a rule by binding zero or more variables and adding zero or more constraints.

Specified by:

specialize in interface IRule<E>

bindingSet - Bindings for zero or more free variables in this rule. The rule will be rewritten such that the variable is replaced by the binding throughout the rule. An attempt to bind a variable not declared by the rule will be ignored.

constraints - An array of additional constraints to be imposed on the rule (optional).

Returns:

The specialized rule.

getSharedVars

public Set<IVariable> getSharedVars(int index1,
                                    int index2)

Description copied from interface: IRule

Return the variables in common for two IPredicates.

Specified by:

getSharedVars in interface IRule<E>

Parameters:

index1 - The index of a predicate in the #tail.

index2 - The index of a different predicate in the #tail.

Returns:

The variables in common -or- null iff there are no variables in common.

getSharedVars

public static Set<IVariable> getSharedVars(IPredicate p1,
                                           IPredicate p2)

Return the variables in common for two IPredicates.

Parameters:

p1 - A predicate.

p2 - A different predicate.

Returns:

The variables in common -or- null iff there are no variables in common.

Throws:

IllegalArgumentException - if the two predicates are the same reference.

getVariableCount

public int getVariableCount(int index,
                            IBindingSet bindingSet)

Description copied from interface: IRule

The #of arguments in the selected predicate that are variables (vs constants) with the given the bindings.

Specified by:

getVariableCount in interface IRule<E>

Parameters:

index - The index of a predicate declared the tail of the IRule.

bindingSet - The bindings under which the variable count will be obtained (any variables in the predicate that are bound in the binding set will be treated as constants for the purposes of this method).

isFullyBound

public boolean isFullyBound(int index,
                            IBindingSet bindingSet)

Description copied from interface: IRule

Return true iff the selected predicate is fully bound.

Specified by:

isFullyBound in interface IRule<E>

Parameters:

index - The index of a predicate declared the tail of the IRule.

bindingSet - The variable bindings.

Returns:

True iff it is fully bound (a mixture of constants and/or bound variables).

isFullyBound

public boolean isFullyBound(IBindingSet bindingSet)

Description copied from interface: IRule

If the rule is fully bound for the given bindings.

Specified by:

isFullyBound in interface IRule<E>

Parameters:

bindingSet - The bindings.

Returns:

true if there are no unbound variables in the rule given those bindings.

isConsistent

public boolean isConsistent(IBindingSet bindingSet)

Description copied from interface: IRule

Return true unless the IBindingSet violates a IConstraint declared for this Rule.

Specified by:

isConsistent in interface IRule<E>

Parameters:

bindingSet - The binding set.

Returns:

true unless a constraint is violated by the bindings.

isDeclared

public boolean isDeclared(IVariable var)

Description copied from interface: IRule

Return true iff the rule declares this variable.

Specified by:

isDeclared in interface IRule<E>

Parameters:

var - Some variable.

Returns:

True if the rule declares that variable.

getTaskFactory

public IRuleTaskFactory getTaskFactory()

Description copied from interface: IRule

An optional IRuleTaskFactory that will be used in place of the default IRuleTaskFactory to evaluate this rule (optional)

Specified by:

getTaskFactory in interface IRule<E>

Returns:

null unless custom evaluation is desired.

isRule

public final boolean isRule()

Description copied from interface: IStep

true iff the step is an IRule and false iff the step is an IProgram.

Specified by:

isRule in interface IStep