eu.fbk.rdfpro

Class Rule

java.lang.Object

eu.fbk.rdfpro.Rule

All Implemented Interfaces:

Comparable<Rule>

public final class Rule
extends Object
implements Comparable<Rule>

Rule definition.

Constructor Summary

Constructors

Constructor and Description
Rule(org.openrdf.model.URI id, boolean fixpoint, int phase, org.openrdf.query.algebra.TupleExpr deleteExpr, org.openrdf.query.algebra.TupleExpr insertExpr, org.openrdf.query.algebra.TupleExpr whereExpr) Creates a new rule.

Method Summary

Modifier and Type	Method and Description
int	compareTo(Rule other) Rules with the same ID are equal.
boolean	equals(Object object) Two rules are equal if they have the same ID.
static int	evaluate(Iterable<Rule> rules, QuadModel model, QuadModel deltaModel, Supplier<org.openrdf.rio.RDFHandler> deleteSink, Supplier<org.openrdf.rio.RDFHandler> insertSink)
void	evaluate(QuadModel model, QuadModel deltaModel, org.openrdf.query.algebra.StatementPattern deltaPattern, Supplier<org.openrdf.rio.RDFHandler> deleteSink, Supplier<org.openrdf.rio.RDFHandler> insertSink)
static List<Rule>	fromDLOG(Reader reader)
static List<Rule>	fromRDF(Iterable<org.openrdf.model.Statement> model) Parses all the rules contained in the supplied RDF statements.
List<String>	getCommonVariables() Returns a sorted list with the variables returned by the WHERE expression that are referenced either in the DELETE or in the INSERT expressions.
org.openrdf.query.algebra.TupleExpr	getDeleteExpr() Returns the optional DELETE expression
Set<org.openrdf.query.algebra.StatementPattern>	getDeletePatterns() Returns the statement patterns in the DELETE expression, if any.
org.openrdf.model.URI	getID() Returns the rule ID.
org.openrdf.query.algebra.TupleExpr	getInsertExpr() Returns the optional INSERT expression
Set<org.openrdf.query.algebra.StatementPattern>	getInsertPatterns() Returns the statement patterns in the INSERT expression, if any.
int	getPhase() Returns the evaluation phase this rule is associated to.
org.openrdf.query.algebra.TupleExpr	getWhereExpr() Returns the optional WHERE expression.
Set<org.openrdf.query.algebra.StatementPattern>	getWherePatterns() Returns the statement patterns in the WHERE expression, if any.
int	hashCode() The returned hash code depends exclusively on the rule ID.
boolean	isFixpoint() Returns true if the rule must be evaluated using a fixpoint semantics
boolean	isSafe() Returns true if the rule is safe, i.e., if all the variables referenced in the DELETE and INSERT expressions are present in the bindings produced by the WHERE expression.
boolean	isSimple() Returns true if the rule is simple, i.e., if the WHERE expression consists only of BGPs, FILTERs (without the EXISTS construct) and outer level BINDs.
boolean	isSpecific() Returns true if the rule matches only specific types of statements.
boolean	isStreamable() Returns true if the rule can be evaluated in a streaming way.
static List<Rule>	mergeSameWhereExpr(Iterable<Rule> rules) Merges rules with the same WHERE expression, priority and fixpoint flag.
boolean	mightActivate(org.openrdf.query.algebra.evaluation.impl.EvaluationStatistics statistics) Returns true if the rule may be activated given the dataset statistics supplied.
Rule	rewriteGlobalGM(org.openrdf.model.URI globalGraph) Rewrites the rule according to the GLOBAL graph inference mode, using the global graph URI specified.
Rule	rewriteSeparateGM() Rewrites the rule according to the SEPARATE graph inference mode.
Rule	rewriteStarGM(org.openrdf.model.URI globalGraph) Rewrites the rule according to the STAR graph inference mode, using the global graph URI supplied.
Rule	rewriteVariables(org.openrdf.query.BindingSet bindings) Rewrites the rule by replacing selected variables with constant values as dictated by the supplied bindings.
<T extends Collection<? super org.openrdf.model.Statement>> T	toRDF(T output) Emits the RDF serialization of the rule.
String	toString() The returned string has the form {@code ID (phase: N, fixpoint): DELETE ...

Methods inherited from class java.lang.Object

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

Constructor Detail

Rule

public Rule(org.openrdf.model.URI id,
            boolean fixpoint,
            int phase,
            @Nullable
            org.openrdf.query.algebra.TupleExpr deleteExpr,
            @Nullable
            org.openrdf.query.algebra.TupleExpr insertExpr,
            @Nullable
            org.openrdf.query.algebra.TupleExpr whereExpr)

Creates a new rule.

Parameters:

id - the rule ID, not null

fixpoint - true, if the rule should be evaluated with a fixpoint semantics

phase - the evaluation phase associated to this rule (defaults to zero)

deleteExpr - the optional DELETE expression; if present, must be a BGP

insertExpr - the optional INSERT expression; if present, must be a BGP

whereExpr - the optional WHERE expression (absent in case of rules asserting axiomatic quads)

Method Detail

getID

public org.openrdf.model.URI getID()

Returns the rule ID.

Returns:

the rule ID

isFixpoint

public boolean isFixpoint()

Returns true if the rule must be evaluated using a fixpoint semantics

Returns:

true, for fixpoint rules

getPhase

public int getPhase()

Returns the evaluation phase this rule is associated to. Evaluation phases with lower index are executed first.

Returns:

an integer (possibly negative) identifying the evaluation phase.

getDeleteExpr

@Nullable
public org.openrdf.query.algebra.TupleExpr getDeleteExpr()

Returns the optional DELETE expression

Returns:

the DELETE expression if present, null otherwise

getInsertExpr

@Nullable
public org.openrdf.query.algebra.TupleExpr getInsertExpr()

Returns the optional INSERT expression

Returns:

the INSERT expression if present, null otherwise

getWhereExpr

@Nullable
public org.openrdf.query.algebra.TupleExpr getWhereExpr()

Returns the optional WHERE expression.

Returns:

the WHERE expression if present; null otherwise

getDeletePatterns

public Set<org.openrdf.query.algebra.StatementPattern> getDeletePatterns()

Returns the statement patterns in the DELETE expression, if any.

Returns:

a non-null set with the statement patterns in the DELETE expression

getInsertPatterns

public Set<org.openrdf.query.algebra.StatementPattern> getInsertPatterns()

Returns the statement patterns in the INSERT expression, if any.

Returns:

a non-null set with the statement patterns in the INSERT expression

getWherePatterns

public Set<org.openrdf.query.algebra.StatementPattern> getWherePatterns()

Returns the statement patterns in the WHERE expression, if any.

Returns:

a non-null set with the statement patterns in the WHERE expression

getCommonVariables

public List<String> getCommonVariables()

Returns a sorted list with the variables returned by the WHERE expression that are referenced either in the DELETE or in the INSERT expressions.

Returns:

a sorted list of common variables between the WHERE expression and the DELETE and INSERT expressions

isSafe

public boolean isSafe()

Returns true if the rule is safe, i.e., if all the variables referenced in the DELETE and INSERT expressions are present in the bindings produced by the WHERE expression. Only safe rules can be evaluated. Non-safe rules are however allowed as they can be transformed into safe rules through variable binding (by calling method rewriteVariables(BindingSet)).

Returns:

true, if the rule is safe

isSimple

public boolean isSimple()

Returns true if the rule is simple, i.e., if the WHERE expression consists only of BGPs, FILTERs (without the EXISTS construct) and outer level BINDs. Simple rules can be evaluated more efficiently.

Returns:

true, if the rule is simple

isStreamable

public boolean isStreamable()

Returns true if the rule can be evaluated in a streaming way. A rule is streamable if: (i) it is simple (see isSimple()); (ii) its where part contains at most one statement pattern; and (iii) the delete part is missing or it contains exactly the statement pattern of the where part (which must be non empty).

Returns:

true, if the rule is streamable

isSpecific

public boolean isSpecific()

Returns true if the rule matches only specific types of statements. A rule is specific if its where part is null or it does not contain a statement pattern that could match any statement. Specific rules might be evaluated only on a subset of statements (the ones that could be matched) obtaining the same results.

Returns:

true, if the rule is specific

mightActivate

public boolean mightActivate(org.openrdf.query.algebra.evaluation.impl.EvaluationStatistics statistics)

Returns true if the rule may be activated given the dataset statistics supplied. Note that false positive answers may be returned, i.e, if the result is true it is not guaranteed that the rule will fire, whereas if the result is false the rule is guaranteed not to fire (under the assumption that statistics returned by statisitcs are 0.0 only if no triple is returned for a certain statement pattern).

Parameters:

statistics - the statistics object

Returns:

true, if the rule might fire given the supplied statistics

rewriteGlobalGM

public Rule rewriteGlobalGM(@Nullable
                            org.openrdf.model.URI globalGraph)

Rewrites the rule according to the GLOBAL graph inference mode, using the global graph URI specified. The returned rule: (i) has a new ID generated based on the ID of this rule; (ii) matches quads in any graph in the WHERE part; (iii) insert quads in the specified global graph; and (iv) deletes quads from any graph.

Parameters:

globalGraph - the URI of the global graph where to insert new quads; if null, quads will be inserted in the default graph sesame:nil

Returns:

the rewritten rule

rewriteSeparateGM

public Rule rewriteSeparateGM()

Rewrites the rule according to the SEPARATE graph inference mode. The returned rule: (i) has a new ID generated based on the ID of this rule; and (ii) operates on a per-graph basis, i.e., for each graph, the WHERE clause is applied and its results are used to evaluate the DELETE and INSERT clauses on the very same graph.

Returns:

the rewritten rule

rewriteStarGM

public Rule rewriteStarGM(@Nullable
                          org.openrdf.model.URI globalGraph)

Rewrites the rule according to the STAR graph inference mode, using the global graph URI supplied. The returned rule: (i) has a new ID generated based on the ID of this rule; (ii) operates on a per-graph basis similarly to rewriteSeparateGM(), however 'importing' (as far as matching in the WHERE clause is concerned) also quads in the global graph; and (iii) in case the WHERE clause is missing or a match is found on quads in the global graph, deletions and insertions are performed on the global graph itself (this can be useful to setup the global graph 'before' applying rules on the other graphs)

Parameters:

globalGraph - the URI of the global graph whose quads are 'imported' in other graphs; if null, the default graph sesame:nil will be used

Returns:

the rewritten rule

rewriteVariables

public Rule rewriteVariables(@Nullable
                             org.openrdf.query.BindingSet bindings)

Rewrites the rule by replacing selected variables with constant values as dictated by the supplied bindings. In case the rewriting is unnecessary this rule is returned unchanged; otherwise, a new, rewritten rule with a different ID (based on the ID of this rule) is produced.

Parameters:

bindings - the variable = value bindings to use for the rewriting; if null or empty, no rewriting will take place

Returns:

either the rewritten rule of this rule, if rewriting is unnecessary

mergeSameWhereExpr

public static List<Rule> mergeSameWhereExpr(Iterable<Rule> rules)

Merges rules with the same WHERE expression, priority and fixpoint flag. A merged rule, with a fresh ID, is produced for each cluster of rules having the same values of these attributes. The DELETE and INSERT expressions of the merged rule are obtained by concatenating the DELETE and INSERT expressions of the rules in the cluster.

Parameters:

rules - the rules to merge

Returns:

a list with the merged rules

evaluate

public void evaluate(QuadModel model,
                     @Nullable
                     QuadModel deltaModel,
                     @Nullable
                     org.openrdf.query.algebra.StatementPattern deltaPattern,
                     @Nullable
                     Supplier<org.openrdf.rio.RDFHandler> deleteSink,
                     @Nullable
                     Supplier<org.openrdf.rio.RDFHandler> insertSink)

evaluate

public static int evaluate(Iterable<Rule> rules,
                           QuadModel model,
                           @Nullable
                           QuadModel deltaModel,
                           @Nullable
                           Supplier<org.openrdf.rio.RDFHandler> deleteSink,
                           @Nullable
                           Supplier<org.openrdf.rio.RDFHandler> insertSink)

compareTo

public int compareTo(Rule other)

Rules with the same ID are equal. Otherwise, rules are sorted by phase (lower phase index comes first), fixpoint flag (false = no fixpoint comes first) and finally ID. This sorting is compatible with the order of execution of rules.

Specified by:

compareTo in interface Comparable<Rule>

equals

public boolean equals(Object object)

Two rules are equal if they have the same ID.

Overrides:

equals in class Object

hashCode

public int hashCode()

The returned hash code depends exclusively on the rule ID.

Overrides:

hashCode in class Object

toString

public String toString()

The returned string has the form ID (phase: N, fixpoint): DELETE ... INSERT ... WHERE ..., where the fixpoint, DELETE ..., INSERT ... and WHERE ... may be present or absent based on the properties of the rule.

Overrides:

toString in class Object

toRDF

public <T extends Collection<? super org.openrdf.model.Statement>> T toRDF(T output)

Emits the RDF serialization of the rule. Emitted triples are placed in the default graph.

Parameters:

output - the collection where to add emitted RDF statements, not null

Returns:

the supplied collection

fromDLOG

public static List<Rule> fromDLOG(Reader reader)
                           throws IOException

Throws:

IOException

fromRDF

public static List<Rule> fromRDF(Iterable<org.openrdf.model.Statement> model)

Parses all the rules contained in the supplied RDF statements.

Parameters:

model - the RDF statements, not null

Returns:

an unsorted list containing the parsed rules