com.bigdata.relation.rule.eval
Interface IJoinNexus

All Known Implementing Classes:

AbstractJoinNexus, RDFJoinNexus

public interface IJoinNexus

Interface provides an interoperability nexus for the IPredicates, IBindingSets, and ISolutions for the evaluation of an IRule and is responsible for resolving the relation symbol to the IRelation object. Instances of this interface may be type-specific and allow you to control various implementation classes used during IRule execution.

Note: This interface is NOT Serializable. Use an IJoinNexusFactory to create instances of this interface.

Version:

$Id: IJoinNexus.java 4218 2011-02-21 22:01:49Z thompsonbry $

Author:

Bryan Thompson

Field Summary

static int	ALL ELEMENT and BINDINGS and RULE.
static int	BINDINGS Bit flag indicating that newSolution(IRule, IBindingSet) should clone the IBindingSet and make it available via ISolution.getBindingSet().
static int	ELEMENT Bit flag indicating that newSolution(IRule, IBindingSet) should materialize an element from the IRule and IBindingSet and make it available via ISolution.get().
static int	RULE Bit flag indicating that newSolution(IRule, IBindingSet) make the IRule that generated the ISolution available via ISolution.getRule().

Method Summary

boolean	bind(IPredicate<?> pred, IConstraint[] constraints, Object e, IBindingSet bindings) Binds variables from a visited element.
boolean	bind(IRule rule, int index, Object e, IBindingSet bindings) Deprecated. by #bind(IPredicate, Object, IBindingSet)
IConstant	fakeBinding(IPredicate predicate, Var var) Return a 'fake' binding for the given variable in the specified predicate.
boolean	forceSerialExecution() Deprecated. by bop annotations.
ActionEnum	getAction() The kind of operation that is being executed (Query, Insert, or Delete).
IStreamSerializer<IBindingSet[]>	getBindingSetSerializer() Return the object that is responsible for (de-)serializing chunks of IBindingSets.
int	getChunkCapacity() Deprecated. by bop annotations.
int	getChunkOfChunksCapacity() Deprecated. by bop annotations.
int	getFullyBufferedReadThreshold() Deprecated. by bop annotations.
IRelation	getHeadRelationView(IPredicate pred) Locate and return the view of the relation identified by the IPredicate.
IIndexManager	getIndexManager() Used to locate indices, relations and relation containers.
IJoinNexusFactory	getJoinNexusFactory() The factory object is used to materialize appropriate IJoinNexus instances when the rule execution crosses an RMI boundary.
int	getMaxParallelSubqueries() Deprecated. by bop annotations.
IEvaluationPlanFactory	getPlanFactory() Return the factory for IEvaluationPlans.
String	getProperty(String name, String defaultValue) Resolve the property value using the IIndexManager, the namespace of the resource, and the Properties instance to be tested as hidden parameters.
<T> T	getProperty(String name, String defaultValue, IValidator<T> validator) Resolves, parses, and validates the property value.
IRangeCountFactory	getRangeCountFactory() The factory object for range counts used by IEvaluationPlans.
long	getReadTimestamp() Equivalent to IJoinNexusFactory.getReadTimestamp().
IRuleStatisticsFactory	getRuleStatisticsFactory() The factory for rule statistics objects.
IRuleTaskFactory	getRuleTaskFactory(boolean parallel, IRule rule) Deprecated. by annotations on individual BOps which specify which join operator is to be used on a join by join basis.
IElementFilter<ISolution>	getSolutionFilter() Return the IElementFilter that will be used to reject solutions based on the bindings for the head of the rule -or- null if no filter will be imposed.
IStreamSerializer<ISolution[]>	getSolutionSerializer() Return the object that is responsible for (de-)serializing chunks of ISolutions.
IAccessPath	getTailAccessPath(IRelation relation, IPredicate pred) Obtain an access path reading from relation for the specified predicate (from the tail of some rule).
IRelation	getTailRelationView(IPredicate pred) Locate and return the view of the relation(s) identified by the IPredicate.
long	getWriteTimestamp() Equivalent to IJoinNexusFactory.getWriteTimestamp().
Iterator<PartitionLocator>	locatorScan(AbstractScaleOutFederation<?> fed, IPredicate<?> predicate) Return an iterator visiting the PartitionLocator for the index partitions from which an IAccessPath must read in order to materialize all elements which would be visited for that predicate.
IBindingSet	newBindingSet(IRule rule) Factory for IBindingSet implementations.
ISortKeyBuilder<IBindingSet>	newBindingSetSortKeyBuilder(IRule rule) Return an ISortKeyBuilder for an IBindingSet.
IBuffer<ISolution[]>	newDeleteBuffer(IMutableRelation relation) Return a thread-safe buffer onto which chunks of computed ISolutions will be written.
IBuffer<ISolution[]>	newInsertBuffer(IMutableRelation relation) Return a thread-safe buffer onto which chunks of computed ISolutions will be written.
IBlockingBuffer<ISolution[]>	newQueryBuffer() Return a thread-safe buffer onto which chunks of computed ISolutions will be written.
ISolution	newSolution(IRule rule, IBindingSet bindingSet) Create a new ISolution.
IBuffer<ISolution>	newUnsynchronizedBuffer(IBuffer<ISolution[]> targetBuffer, int chunkCapacity) Return a buffer suitable for a single-threaded writer that flushes onto the specified targetBuffer.
long	runMutation(IStep step) Run as mutation operation (it will write any solutions onto the relations named in the head of the various IRules).
IChunkedOrderedIterator<ISolution>	runQuery(IStep step) Run as a query.
int	solutionFlags() The flags that effect the behavior of newSolution(IRule, IBindingSet).

Field Detail

ELEMENT

static final int ELEMENT

Bit flag indicating that newSolution(IRule, IBindingSet) should materialize an element from the IRule and IBindingSet and make it available via ISolution.get().

See Also:

Constant Field Values

BINDINGS

static final int BINDINGS

Bit flag indicating that newSolution(IRule, IBindingSet) should clone the IBindingSet and make it available via ISolution.getBindingSet().

See Also:

Constant Field Values

RULE

static final int RULE

Bit flag indicating that newSolution(IRule, IBindingSet) make the IRule that generated the ISolution available via ISolution.getRule().

See Also:

Constant Field Values

ALL

static final int ALL

ELEMENT and BINDINGS and RULE.

See Also:

Constant Field Values

Method Detail

getRuleStatisticsFactory

IRuleStatisticsFactory getRuleStatisticsFactory()

The factory for rule statistics objects.

getJoinNexusFactory

IJoinNexusFactory getJoinNexusFactory()

The factory object is used to materialize appropriate IJoinNexus instances when the rule execution crosses an RMI boundary.

getRangeCountFactory

IRangeCountFactory getRangeCountFactory()

The factory object for range counts used by IEvaluationPlans.

getAction

ActionEnum getAction()

The kind of operation that is being executed (Query, Insert, or Delete).

forceSerialExecution

boolean forceSerialExecution()

Deprecated. by bop annotations.

When true, rule level parallelism is disabled and the ISolution buffers are flushed after after every IStep. This can be enabled if you are exploring apparent concurrency problems with the rules. It should normally be false for better performance.

getMaxParallelSubqueries

int getMaxParallelSubqueries()

Deprecated. by bop annotations.

The maximum #of subqueries for the first join dimension that will be issued in parallel. Use ZERO(0) to avoid submitting tasks to the ExecutorService entirely and ONE (1) to submit a single task at a time to the ExecutorService.

getChunkCapacity

int getChunkCapacity()

Deprecated. by bop annotations.

The #of elements in a chunk for query or mutation. This is normally a relatively large value on the order of 10,000 or better.

getChunkOfChunksCapacity

int getChunkOfChunksCapacity()

Deprecated. by bop annotations.

The #of chunks that can be held by an IBuffer that is the target or one or more UnsynchronizedArrayBuffers. This is generally a small value on the order of the #of parallel producers that might be writing on the IBuffer since the capacity of the UnsynchronizedArrayBuffers is already quite large (10k or better elements, defining a single "chunk" from a single producer).

See Also:

getMaxParallelSubqueries(), getChunkCapacity()

getFullyBufferedReadThreshold

int getFullyBufferedReadThreshold()

Deprecated. by bop annotations.

The #of elements that will be materialized in a fully buffered read by an IAccessPath. When this threshold is exceeded the IAccessPath will use an IAsynchronousIterator instead. This value should on the order of getChunkCapacity().

See Also:

IAccessPath.iterator(int, int), AbstractResource.Options#FULLY_BUFFERED_READ_THRESHOLD

getProperty

String getProperty(String name,
                   String defaultValue)

Resolve the property value using the IIndexManager, the namespace of the resource, and the Properties instance to be tested as hidden parameters.

Parameters:

name - The property name.

defaultValue - The default.

Returns:

The resolved property value.

See Also:

Configuration

getProperty

<T> T getProperty(String name,
                  String defaultValue,
                  IValidator<T> validator)

Resolves, parses, and validates the property value.

Parameters:

name - The property name.

defaultValue - The default value.

Returns:

bind

boolean bind(IRule rule,
             int index,
             Object e,
             IBindingSet bindings)

Deprecated. by #bind(IPredicate, Object, IBindingSet)

Binds variables from a visited element.

Note: The bindings are propagated before the constraints are verified so this method will have a side-effect on the bindings even if the constraints were not satisfied. Therefore you should clone the bindings before calling this method.

Parameters:

rule - The rule.

index - The index of the IPredicate in the body of the Rule.

e - An element materialized by the IAccessPath for that IPredicate.

bindingSet - the bindings to which new bindings from the element will be applied.

Returns:

true unless the new bindings would violate any of the IConstraints declared for the Rule).

Throws:

NullPointerException - if an argument is null.

IndexOutOfBoundsException - if the index is out of bounds.

bind

boolean bind(IPredicate<?> pred,
             IConstraint[] constraints,
             Object e,
             IBindingSet bindings)

Binds variables from a visited element.

Note: The bindings are propagated before the constraints are verified so this method will have a side-effect on the bindings even if the constraints were not satisfied. Therefore you should clone the bindings before calling this method.

Parameters:

pred - The IPredicate from which the element was read.

constraints - An array of constraints which must be satisfied (optional).

e - An element materialized by the IAccessPath for that IPredicate.

bindingSet - the bindings to which new bindings from the element will be applied.

Returns:

true unless the new bindings would violate any of the optional IConstraint.

Throws:

NullPointerException - if an argument is null.

fakeBinding

IConstant fakeBinding(IPredicate predicate,
                      Var var)

Return a 'fake' binding for the given variable in the specified predicate. The binding should be such that it is of a legal type for the slot in the predicate associated with that variable. This is used to discovery the IKeyOrder associated with the IAccessPath that will be used to evaluate the predicate when it appears in the tail of an IRule for a given IEvaluationPlan.

Parameters:

predicate - The predicate.

var - A variable appearing in that predicate.

Returns:

The 'fake' binding.

newSolution

ISolution newSolution(IRule rule,
                      IBindingSet bindingSet)

Create a new ISolution. The behavior of this method generally depends on bit flags specified when the IJoinNexus was created.

Note: For many purposes, it is only the computed ELEMENTs that are of interest. For high-level query, you will generally specify only the BINDINGS. The BINDINGS are also useful for some truth maintenance applications. The RULE is generally only of interest for inspecting the behavior of some rule set.

Parameters:

rule - The rule.

bindingSet - The bindings (the implementation MUST clone the bindings if they will be saved with the ISolution).

Returns:

The new ISolution.

Throws:

IllegalArgumentException - if any parameter is null.

See Also:

ELEMENT, BINDINGS, RULE, solutionFlags(), Solution

newBindingSetSortKeyBuilder

ISortKeyBuilder<IBindingSet> newBindingSetSortKeyBuilder(IRule rule)

Return an ISortKeyBuilder for an IBindingSet. The sort key may be used to SORT IBindingSets or to impose a DISTINCT filter on ISolutions, etc.

Parameters:

rule - The rule that will determine the order imposed amoung the bound variables (which variable is 1st, 2nd, 3rd, etc.).

Returns:

The sort key builder (NOT thread-safe).

solutionFlags

int solutionFlags()

The flags that effect the behavior of newSolution(IRule, IBindingSet).

newBindingSet

IBindingSet newBindingSet(IRule rule)

Factory for IBindingSet implementations.

Note: The factory MUST apply any bound constants for the IRule before returning the IBindingSet.

Parameters:

rule - The rule whose bindings will be stored in the binding set.

Returns:

A new binding set suitable for that rule.

getRuleTaskFactory

IRuleTaskFactory getRuleTaskFactory(boolean parallel,
                                    IRule rule)

Deprecated. by annotations on individual BOps which specify which join operator is to be used on a join by join basis.

Return the effective IRuleTaskFactory for the rule. When the rule is a step of a sequential program writing on one or more IMutableRelations, then the returned IStepTask must automatically flush the buffer after the rule executes in order to ensure that the state of the IMutableRelation(s) are updated before the next IRule is executed.

Parameters:

parallel - true unless the rule is a step is a sequential IProgram. Note that a sequential step MUST flush its buffer since steps are run in sequence precisely because they have a dependency!

rule - A rule that is a step in some program. If the program is just a rule then the value of parallel does not matter. The buffer will is cleared when it flushed so a re-flushed is always a NOP.

Returns:

The IStepTask to execute for that rule.

See Also:

RunRuleAndFlushBufferTaskFactory, RunRuleAndFlushBufferTask

getPlanFactory

IEvaluationPlanFactory getPlanFactory()

Return the factory for IEvaluationPlans.

Returns:

The factory.

getWriteTimestamp

long getWriteTimestamp()

Equivalent to IJoinNexusFactory.getWriteTimestamp().

getReadTimestamp

long getReadTimestamp()

Equivalent to IJoinNexusFactory.getReadTimestamp().

getHeadRelationView

IRelation getHeadRelationView(IPredicate pred)

Locate and return the view of the relation identified by the IPredicate. The implementation must choose a view that will accept writes iff this is a mutation operation and which is associated with an appropriate timestamp.

Parameters:

pred - The IPredicate, which MUST be the head of some IRule.

Returns:

The IRelation, which will never be a fused view and which will accept writes iff the rules are being executed as a mutation operation.

getTailRelationView

IRelation getTailRelationView(IPredicate pred)

Locate and return the view of the relation(s) identified by the IPredicate.

Note: This method is responsible for returning a fused view when more than one relation name was specified for the IPredicate. It SHOULD be used whenever the IRelation is selected based on a predicate in the tail of an IRule and could therefore be a fused view of more than one relation instance. (The head of the IRule must be a simple IRelation and not a view.)

Note: The implementation should choose the read timestamp for each relation in the view using #getReadTimestamp(String).

Parameters:

pred - The IPredicate, which MUST be a tail from some IRule.

Returns:

The IRelation, which might be a RelationFusedView.

getTailAccessPath

IAccessPath getTailAccessPath(IRelation relation,
                              IPredicate pred)

Obtain an access path reading from relation for the specified predicate (from the tail of some rule).

Note that passing in the IRelation is important since it otherwise must be discovered using the IResourceLocator. By requiring the caller to resolve it before hand and pass it into this method the contention and demand on the IResourceLocator cache is reduced.

Parameters:

relation - The relation.

pred - The predicate. When IPredicate.getPartitionId() is set, the returned IAccessPath MUST read on the identified local index partition (directly, not via RMI).

Returns:

The access path.

locatorScan

Iterator<PartitionLocator> locatorScan(AbstractScaleOutFederation<?> fed,
                                       IPredicate<?> predicate)

Return an iterator visiting the PartitionLocator for the index partitions from which an IAccessPath must read in order to materialize all elements which would be visited for that predicate.

Note: You can use an IDataServiceCallable to obtain the reference of the IDataService and pass that into your AbstractTask in order to have the federation reference available when running under the ConcurrencyManager.

Parameters:

predicate - The predicate, with whatever bindings already applied.

fed - The federation, which is required in order to access the IMetadataIndex for a scale-out index.

joinNexus - The IJoinNexus.

Returns:

The iterator.

getIndexManager

IIndexManager getIndexManager()

Used to locate indices, relations and relation containers.

runQuery

IChunkedOrderedIterator<ISolution> runQuery(IStep step)
                                            throws Exception

Run as a query.

Parameters:

step - The IRule or IProgram.

Returns:

An iterator from which you can read the solutions.

Throws:

IllegalStateException - unless this is an ActionEnum.Query.

IllegalArgumentException - if either argument is null.

Exception

TODO:

ISolution is only used when constructing entailments for which we also need to know the rule which licensed the entailment in order to generate the justification chain. This should all be done by a CONSTRUCT operator. The solutionFlags() should also go away, including BINDINGS, ELEMENT, RULE, and ALL.

runMutation

long runMutation(IStep step)
                 throws Exception

Run as mutation operation (it will write any solutions onto the relations named in the head of the various IRules).

Parameters:

step - The IRule or IProgram.

Returns:

The mutation count (#of distinct elements modified in the relation(s)).

Throws:

IllegalArgumentException - unless ActionEnum.isMutation() is true.

IllegalArgumentException - if either argument is null.

Exception

newQueryBuffer

IBlockingBuffer<ISolution[]> newQueryBuffer()

Return a thread-safe buffer onto which chunks of computed ISolutions will be written. The client will drain ISolutions from buffer using IBlockingBuffer.iterator().

newInsertBuffer

IBuffer<ISolution[]> newInsertBuffer(IMutableRelation relation)

Return a thread-safe buffer onto which chunks of computed ISolutions will be written. When the buffer is flushed the chunked ISolutions will be inserted into the IMutableRelation.

Parameters:

relation - The relation.

Returns:

The buffer.

newDeleteBuffer

IBuffer<ISolution[]> newDeleteBuffer(IMutableRelation relation)

Return a thread-safe buffer onto which chunks of computed ISolutions will be written. When the buffer is flushed the chunks of ISolutions will be deleted from the IMutableRelation.

Parameters:

relation - The relation.

Returns:

The buffer.

newUnsynchronizedBuffer

IBuffer<ISolution> newUnsynchronizedBuffer(IBuffer<ISolution[]> targetBuffer,
                                           int chunkCapacity)

Return a buffer suitable for a single-threaded writer that flushes onto the specified targetBuffer.

The returned buffer MUST apply the optional filter value returned by getSolutionFilter() in order to keep individual ISolutions out of the buffer. Filtering is done at this level since the targetBuffer contains chunks of solutions.

Parameters:

targetBuffer - A thread-safe buffer for chunks of ISolutions that was allocated with newQueryBuffer(), newInsertBuffer(IMutableRelation), or newDeleteBuffer(IMutableRelation).

chunkCapacity - The capacity of the new buffer. This should be maximum chunk size that will be produced or getChunkCapacity() if you do not have better information.

Returns:

A non-thread-safe buffer.

getSolutionFilter

IElementFilter<ISolution> getSolutionFilter()

Return the IElementFilter that will be used to reject solutions based on the bindings for the head of the rule -or- null if no filter will be imposed. This may be used for query or mutation.

Returns:

The optional filter.

TODO:

Normally the IElementFilter is specified in terms of the elements of some IRelation and then wrapped as a SolutionFilter.

The return type here should be strongly typed. The generic argument is not a sufficient guarantee and the compiler can be fooled by passing an IElementFilter that is already defined in terms of an ISolution rather than element of an IRelation.

getSolutionSerializer

IStreamSerializer<ISolution[]> getSolutionSerializer()

Return the object that is responsible for (de-)serializing chunks of ISolutions. This is used by high-level query to transfer ISolutions back to the client.

getBindingSetSerializer

IStreamSerializer<IBindingSet[]> getBindingSetSerializer()

Return the object that is responsible for (de-)serializing chunks of IBindingSets. This is used by JoinTasks to transfer intermediate IBindingSets from one join dimension to the next.