de.fuberlin.wiwiss.d2rq.rdql
Class CombinedPatternStage

java.lang.Object
  extended bycom.hp.hpl.jena.graph.query.Stage
      extended byde.fuberlin.wiwiss.d2rq.rdql.CombinedPatternStage
Direct Known Subclasses:
D2RQPatternStage2

public abstract class CombinedPatternStage
extends com.hp.hpl.jena.graph.query.Stage

A CombinedPatternStage is a Stage that handles a conjunction of triples (a pattern). This class is a corrected, clarified and optimized version of PatternStage. In the following we try to document the logic and machinery behind it:

An RDQL query (triples) contains nodes, some of which are (shared) variables (a-z) which will be bound by successive Stages. This Stage for example sees variables a,b,c,i,j,k,x,y,z in triples. The type of the triple nodes (fixed, bound or bind Element) is compiled according to the following schema:

The mapping map lists variables a,b,c...h (pointers to Domain indices) that will be bound by a previous stage and put into the Pipe. (Bound) This stage will pick up each binding (on its own thread), substitute variables with existing bindings, and produce additional bindings. This stage is first to bind some variables i,j,k,x,y,z (1st time Bind) Some variables x,y,z are used in more than one triple/node => (2nd time: Bound)

Some variables l,m,n...u,v,w will still not be bound by this stage and left over for the next stage. compiled: for each query triple the compiled node binding information (Bind, Bound, Fixed) guard: a condition checker for the conditions that come with the query and can be checked after this stage found a matching solution for the variables, for example (?x < ?y) varInfo: fast lookup information for different types of variables (shared, bind, bound) triples: list of find-triples with inserted bindings by previous stages, build each time a binding arrives on the Pipe.

Since:
V0.3
Author:
Joerg Garbers

Field Summary
protected  com.hp.hpl.jena.graph.query.Pattern[] compiled
          For each query triple the compiled node binding information (Bind, Bound, Fixed).
protected  com.hp.hpl.jena.graph.query.ValuatorSet guard
          A condition checker for the conditions that come with the query.
private  int nodeNr
           
private  com.hp.hpl.jena.graph.query.Element[] patternElements
           
protected  com.hp.hpl.jena.graph.query.ExpressionSet queryConstraints
           
protected  com.hp.hpl.jena.graph.query.Mapping queryMapping
           
protected  com.hp.hpl.jena.graph.Triple[] queryTriples
           
private  com.hp.hpl.jena.graph.Node[] tripleNodes
           
private  int tripleNr
           
protected  com.hp.hpl.jena.graph.Triple[] triples
          A list of find-triples with inserted bindings by previous stages, build each time a binding arrives on the Pipe.
protected  VariableBindings varInfo
          Fast lookup information for different types of variables (shared, bind, bound).
 
Fields inherited from class com.hp.hpl.jena.graph.query.Stage
previous, stillOpen
 
Constructor Summary
CombinedPatternStage(com.hp.hpl.jena.graph.Graph graph, com.hp.hpl.jena.graph.query.Mapping map, com.hp.hpl.jena.graph.query.ExpressionSet constraints, com.hp.hpl.jena.graph.Triple[] triples)
           
 
Method Summary
protected  boolean canEval(com.hp.hpl.jena.graph.query.Mapping map, com.hp.hpl.jena.graph.query.Expression e)
          Checks if an Expression can be evaluated when given a Mapping.
protected  com.hp.hpl.jena.graph.query.Pattern[] compile(com.hp.hpl.jena.graph.query.Mapping map, com.hp.hpl.jena.graph.Triple[] triples)
          Compiles triples into compiled.
protected  com.hp.hpl.jena.graph.query.Element compileNode(com.hp.hpl.jena.graph.Node varOrFixedNode, com.hp.hpl.jena.graph.query.Mapping map)
          Gets the binding information for a fixed or variable Node.
 com.hp.hpl.jena.graph.query.Pipe deliver(com.hp.hpl.jena.graph.query.Pipe result)
          Realizes the piping between the previous, this and the following Stage.
protected  void hookPrepareExpression(com.hp.hpl.jena.graph.query.Expression e, boolean evaluable)
           
protected  com.hp.hpl.jena.graph.query.ValuatorSet makeGuard(com.hp.hpl.jena.graph.query.Mapping map, com.hp.hpl.jena.graph.query.ExpressionSet constraints)
          Construct a set of Valuators from RDQL expressions.
(package private) abstract  com.hp.hpl.jena.util.iterator.ClosableIterator resultIteratorForTriplePattern(com.hp.hpl.jena.graph.Triple[] triples)
          It is the subclass' duty to create an iterator.
protected  void run(com.hp.hpl.jena.graph.query.Pipe source, com.hp.hpl.jena.graph.query.Pipe sink)
          Pulls variable bindings from the previous stage adds bindings and pushes all into the following stage.
 void setup()
           
 void updateTriplesWithDomain(com.hp.hpl.jena.graph.query.Domain inputDomain)
          Updates triples with a new set of bindings from the previous stage.
 
Methods inherited from class com.hp.hpl.jena.graph.query.Stage
close, connectFrom, initial, isClosed, markClosed
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

compiled

protected com.hp.hpl.jena.graph.query.Pattern[] compiled
For each query triple the compiled node binding information (Bind, Bound, Fixed).


guard

protected com.hp.hpl.jena.graph.query.ValuatorSet guard
A condition checker for the conditions that come with the query. They can be checked after this stage found a matching solution for the variables, for example (?x < ?y).


varInfo

protected VariableBindings varInfo
Fast lookup information for different types of variables (shared, bind, bound).


tripleNr

private int tripleNr

nodeNr

private int nodeNr

tripleNodes

private com.hp.hpl.jena.graph.Node[] tripleNodes

patternElements

private com.hp.hpl.jena.graph.query.Element[] patternElements

triples

protected com.hp.hpl.jena.graph.Triple[] triples
A list of find-triples with inserted bindings by previous stages, build each time a binding arrives on the Pipe.


queryMapping

protected com.hp.hpl.jena.graph.query.Mapping queryMapping

queryTriples

protected com.hp.hpl.jena.graph.Triple[] queryTriples

queryConstraints

protected com.hp.hpl.jena.graph.query.ExpressionSet queryConstraints
Constructor Detail

CombinedPatternStage

public CombinedPatternStage(com.hp.hpl.jena.graph.Graph graph,
                            com.hp.hpl.jena.graph.query.Mapping map,
                            com.hp.hpl.jena.graph.query.ExpressionSet constraints,
                            com.hp.hpl.jena.graph.Triple[] triples)
Method Detail

setup

public void setup()

compile

protected com.hp.hpl.jena.graph.query.Pattern[] compile(com.hp.hpl.jena.graph.query.Mapping map,
                                                        com.hp.hpl.jena.graph.Triple[] triples)
Compiles triples into compiled. A clarified and optimized version of PatternStage.compile.

Parameters:
map - a mapping between variable Nodes and Domain indices.
triples - a Triple list containing Jena variable Nodes.
Returns:
for each triple its Pattern form, where each Node is either a Bind, Bound or Fixed Element.

compileNode

protected com.hp.hpl.jena.graph.query.Element compileNode(com.hp.hpl.jena.graph.Node varOrFixedNode,
                                                          com.hp.hpl.jena.graph.query.Mapping map)
Gets the binding information for a fixed or variable Node. This is a condensed version of PatternStageCompiler's functionality. In addition to the PatternStage version, the indices of sets of elements of different types are collected in varInfo For overwriting techniques, see more flexible but less understandable solution in PatternStage.

Parameters:
varOrFixedNode - the node
map - the Mapping which is given by previous stages
Returns:
the compiled Element.
See Also:
compiled, varInfo

makeGuard

protected com.hp.hpl.jena.graph.query.ValuatorSet makeGuard(com.hp.hpl.jena.graph.query.Mapping map,
                                                            com.hp.hpl.jena.graph.query.ExpressionSet constraints)
Construct a set of Valuators from RDQL expressions. A condensed and corrected version of PatternStage.makeGuards(Mapping, ExpressionSet, int). Answers an ExpressionSet that contains the prepared [against map] expression that can be evaluated after the triples have matched. By "can be evaluated" we mean that all its variables are bound.

Note: makeGuards/canEval() can not work correctly in PatternStage, because makeBoundVariables() is wrong there. It just unifies all variables that will be bound in this stage, but does not contain the variables that are bound by a previous stage. So expressions like x=y where x is bound by previous stage and y by this stage cannot be evaluated.

Parameters:
map - the Mapping to prepare Expressions against
constraints - the set of (RDQL) constraint expressions
Returns:
the prepared ExpressionSet

hookPrepareExpression

protected void hookPrepareExpression(com.hp.hpl.jena.graph.query.Expression e,
                                     boolean evaluable)

canEval

protected boolean canEval(com.hp.hpl.jena.graph.query.Mapping map,
                          com.hp.hpl.jena.graph.query.Expression e)
Checks if an Expression can be evaluated when given a Mapping. All variables of an expression must be bound before it can be evaluated. This is a sufficient but not a necessary condition, because in principle some contradictions can be found even in terms with variables, such as (x=0 AND x=1).

We redefined PatternStage.canEval(com.hp.hpl.jena.graph.query.Expression, int) so that it looks up the variables of the expression in Mapping. After compile() map contains all the variable bindings of this and the previous stages.

Parameters:
map - the Mapping
e - a compiled RDQL expression
Returns:
true iff all variables of the expression are bound in map

deliver

public com.hp.hpl.jena.graph.query.Pipe deliver(com.hp.hpl.jena.graph.query.Pipe result)
Realizes the piping between the previous, this and the following Stage. A new thread is created for this stage.

See Also:
PatternStage, run(Pipe, Pipe)

run

protected void run(com.hp.hpl.jena.graph.query.Pipe source,
                   com.hp.hpl.jena.graph.query.Pipe sink)
Pulls variable bindings from the previous stage adds bindings and pushes all into the following stage. A more efficient version of PatternStage.run(com.hp.hpl.jena.graph.query.Pipe, com.hp.hpl.jena.graph.query.Pipe). Includes its run(Pipe,Pipe) and nest() functionality. Handles the case, where bindings for triples are not found triple by triple, but in one step. This is the case for D2RQ.

In our example: a,b,c get bound by source. They are substituted by asTripleMatch(). (Bound) i,j,k,x,y,z are bound by p.match() the first time they are seen. (Bind) x,y,z are checked by p.match() the second time they are seen. (Bound)

Parameters:
source - the connector to the previous stage
sink - the connector to the next stage

updateTriplesWithDomain

public void updateTriplesWithDomain(com.hp.hpl.jena.graph.query.Domain inputDomain)
Updates triples with a new set of bindings from the previous stage.

Parameters:
inputDomain - for each variable number a binding entry

resultIteratorForTriplePattern

abstract com.hp.hpl.jena.util.iterator.ClosableIterator resultIteratorForTriplePattern(com.hp.hpl.jena.graph.Triple[] triples)
It is the subclass' duty to create an iterator.

Parameters:
triples - all Triple nodes are fixed or ANY.
Returns:
iterator that returns instanciations (Triple[]) of the triples find pattern.