com.bigdata.bop
Class BOpContext<E>

java.lang.Object
  com.bigdata.bop.BOpContextBase
      com.bigdata.bop.BOpContext<E>

Type Parameters:

E - The generic type of the objects processed by the operator.

public class BOpContext<E>
extends BOpContextBase

The evaluation context for the operator (NOT serializable).

Constructor Summary

BOpContext(IRunningQuery runningQuery, int partitionId, BOpStats stats, ICloseableIterator<E[]> source, IBlockingBuffer<E[]> sink, IBlockingBuffer<E[]> sink2)

Method Summary

static IBindingSet	bind(IBindingSet left, IBindingSet right, IConstraint[] constraints, IVariable[] varsToKeep) Copy the values for variables from the source IBindingSet to the destination IBindingSet.
static boolean	bind(IPredicate<?> pred, IConstraint[] constraints, Object e, IBindingSet bindings) Binds variables from a visited element.
static void	copyValues(IElement e, IPredicate<?> pred, IBindingSet bindingSet) Copy the values for variables in the predicate from the element, applying them to the caller's IBindingSet.
ClientConnectionManager	getClientConnectionManager() Return the ClientConnectionManager used to make remote SERVICE call requests.
IMemoryManager	getMemoryManager(UUID queryId) Return the IMemoryManager associated with the specified query.
int	getPartitionId() The index partition identifier -or- -1 if the index is not sharded.
IQueryAttributes	getQueryAttributes() Return the IQueryAttributes associated with this query.
IQueryAttributes	getQueryAttributes(UUID queryId) Return the IQueryAttributes associated with the specified query.
IRunningQuery	getRunningQuery() The interface for a running query.
IRunningQuery	getRunningQuery(UUID queryId) Return the IRunningQuery associated with the specified queryId.
IBlockingBuffer<E[]>	getSink() Where to write the output of the operator.
IBlockingBuffer<E[]>	getSink2() Optional alternative sink for the output of the operator.
ICloseableIterator<E[]>	getSource() Where to read the data to be consumed by the operator.
BOpStats	getStats() The object used to collect statistics about the evaluation of this operator.
boolean	isLastInvocation() true iff this is the last invocation of the operator.
void	setLastInvocation() Set by the QueryEngine when the criteria specified by isLastInvocation() are satisfied.
static ICloseableIterator<IBindingSet>	solutions(IChunkedIterator<?> src, IPredicate<?> pred, BaseJoinStats stats) Convert an IAccessPath.iterator() into a stream of IBindingSets.

Methods inherited from class com.bigdata.bop.BOpContextBase

getAccessPath, getExecutorService, getFederation, getIndexManager, getRelation, getResource

Methods inherited from class java.lang.Object

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

Constructor Detail

BOpContext

public BOpContext(IRunningQuery runningQuery,
                  int partitionId,
                  BOpStats stats,
                  ICloseableIterator<E[]> source,
                  IBlockingBuffer<E[]> sink,
                  IBlockingBuffer<E[]> sink2)

Parameters:

runningQuery - The IRunningQuery.

partitionId - The index partition identifier -or- -1 if the index is not sharded.

stats - The object used to collect statistics about the evaluation of this operator.

source - Where to read the data to be consumed by the operator.

sink - Where to write the output of the operator.

sink2 - Alternative sink for the output of the operator (optional). This is used by things like SPARQL optional joins to route failed joins outside of the join group.

Throws:

IllegalArgumentException - if the stats is null

IllegalArgumentException - if the source is null (use an empty source if the source will be ignored).

IllegalArgumentException - if the sink is null

TODO:

Modify to accept IChunkMessage or an interface available from getChunk() on IChunkMessage which provides us with flexible mechanisms for accessing the chunk data.

When doing that, modify to automatically track the BOpStats as the source is consumed.

Note: The only call to this method outside of the test suite is from ChunkedRunningQuery. It always has a fully materialized chunk on hand and ready to be processed.

Method Detail

setLastInvocation

public void setLastInvocation()

Set by the QueryEngine when the criteria specified by isLastInvocation() are satisfied.

isLastInvocation

public boolean isLastInvocation()

true iff this is the last invocation of the operator. The property is only set to true for operators which:

1. PipelineOp.Annotations.LAST_PASS is true
2. PipelineOp.Annotations.PIPELINED is true
3. PipelineOp.Annotations.MAX_PARALLEL is 1

Under these circumstances, it is possible for the IQueryClient to atomically decide that a specific invocation of the operator task for the query will be the last invocation for that task. This is not possible if the operator allows concurrent evaluation tasks. Sharded operators are intrinsically concurrent since they can evaluate at each shard in parallel. This is why the evaluation context is locked to the query controller. In addition, the operator must declare that it is NOT thread safe in order for the query engine to serialize its evaluation tasks.

TODO:

This should be a ctor parameter. We just have to update the test suites for the changed method signature.

getRunningQuery

public IRunningQuery getRunningQuery()

The interface for a running query.

Note: In scale-out each node will have a distinct IRunningQuery object and the query controller will have access to additional state, such as the aggregation of the BOpStats for the query on all nodes.

getPartitionId

public final int getPartitionId()

The index partition identifier -or- -1 if the index is not sharded.

getStats

public final BOpStats getStats()

The object used to collect statistics about the evaluation of this operator.

getSource

public final ICloseableIterator<E[]> getSource()

Where to read the data to be consumed by the operator.

getSink

public final IBlockingBuffer<E[]> getSink()

Where to write the output of the operator.

See Also:

PipelineOp.Annotations.SINK_REF

getSink2

public final IBlockingBuffer<E[]> getSink2()

Optional alternative sink for the output of the operator. This is used by things like SPARQL optional joins to route failed joins outside of the join group.

See Also:

PipelineOp.Annotations.ALT_SINK_REF, PipelineOp.Annotations#ALT_SINK_GROUP

getRunningQuery

public IRunningQuery getRunningQuery(UUID queryId)

Return the IRunningQuery associated with the specified queryId.

Parameters:

queryId - The UUID of some IRunningQuery.

Returns:

The IRunningQuery.

Throws:

RuntimeException - if the IRunningQuery has halted.

RuntimeException - if the IRunningQuery is not found.

getQueryAttributes

public IQueryAttributes getQueryAttributes(UUID queryId)

Return the IQueryAttributes associated with the specified query.

Parameters:

queryId - The UUID of some IRunningQuery.

Returns:

The IQueryAttributes for that IRunningQuery.

Throws:

RuntimeException - if the IRunningQuery has halted.

RuntimeException - if the IRunningQuery is not found.

getQueryAttributes

public IQueryAttributes getQueryAttributes()

Return the IQueryAttributes associated with this query.

Returns:

The IQueryAttributes.

getMemoryManager

public IMemoryManager getMemoryManager(UUID queryId)

Return the IMemoryManager associated with the specified query.

Parameters:

queryId - The UUID of some IRunningQuery.

Returns:

The IMemoryManager for that IRunningQuery.

Throws:

RuntimeException - if the IRunningQuery has halted.

RuntimeException - if the IRunningQuery is not found.

getClientConnectionManager

public ClientConnectionManager getClientConnectionManager()

Return the ClientConnectionManager used to make remote SERVICE call requests.

bind

public static final 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.

constraint - A constraint 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.

copyValues

public static void copyValues(IElement e,
                              IPredicate<?> pred,
                              IBindingSet bindingSet)

Copy the values for variables in the predicate from the element, applying them to the caller's IBindingSet.

Note: A variable which is bound outside of the query to a constant gets turned into a Constant with that variable as its annotation. This method causes the binding to be created for the variable and the constant when the constant is JOINed.

Parameters:

e - The element.

pred - The predicate.

bindingSet - The binding set, which is modified as a side-effect. TODO Make this method package private once we convert to using an inline access path.

bind

public static IBindingSet bind(IBindingSet left,
                               IBindingSet right,
                               IConstraint[] constraints,
                               IVariable[] varsToKeep)

Copy the values for variables from the source IBindingSet to the destination IBindingSet. It is an error if a binding already exists in the destination IBindingSet which is not consistent with a binding in the source IBindingSet.

Parameters:

left - The left binding set.

right - The right binding set.

constraints - An array of constraints (optional). When given, destination IBindingSet will be validated after mutation.

varsToKeep - An array of variables whose bindings will be retained. The bindings are not stripped out until after the constraint(s) (if any) have been tested.

Returns:

The solution with the combined bindings and null if the bindings were not consistent, if a constraint was violated, etc.

solutions

public static ICloseableIterator<IBindingSet> solutions(IChunkedIterator<?> src,
                                                        IPredicate<?> pred,
                                                        BaseJoinStats stats)

Convert an IAccessPath.iterator() into a stream of IBindingSets.

Parameters:

src - The iterator draining the IAccessPath. This will visit IElements.

pred - The predicate for that IAccessPath

stats - Statistics to be updated as elements and chunks are consumed (optional).

Returns:

The dechunked iterator visiting the solutions. The order of the original IElements is preserved.

See Also:

(AccessPath should visit binding sets rather than elements when used for high level query.), (Inline access path). TODO Move to {@link IAccessPath}? {@link AccessPath}?