com.hp.hpl.jena.reasoner.rulesys
Class FBRuleInfGraph

java.lang.Object
  com.hp.hpl.jena.graph.impl.GraphBase
      com.hp.hpl.jena.reasoner.BaseInfGraph
          com.hp.hpl.jena.reasoner.rulesys.BasicForwardRuleInfGraph
              com.hp.hpl.jena.reasoner.rulesys.FBRuleInfGraph

All Implemented Interfaces:

Graph, GraphAdd, com.hp.hpl.jena.graph.impl.GraphWithPerform, InfGraph, BackwardRuleInfGraphI, ForwardRuleInfGraphI, SilentAddI

Direct Known Subclasses:

RDFSRuleInfGraph

public class FBRuleInfGraph
extends BasicForwardRuleInfGraph
implements BackwardRuleInfGraphI

An inference graph that uses a mixture of forward and backward chaining rules. The forward rules can create direct deductions from the source data and schema and can also create backward rules. A query is answered by consulting the union of the raw data, the forward derived results and any relevant backward rules (whose answers are tabled for future reference).

Version:

$Revision: 1.5 $ on $Date: 2010-11-12 12:21:00 $

Author:

Dave Reynolds

Nested Class Summary

static class

FBRuleInfGraph.RuleStore Structure used to wrap up pre-processed/compiled rule sets.

Nested classes/interfaces inherited from class com.hp.hpl.jena.reasoner.BaseInfGraph

BaseInfGraph.InfCapabilities, BaseInfGraph.InfFindSafeCapabilities, BaseInfGraph.InfTransactionHandler

Field Summary

static boolean

useRETE Static switch from Basic to RETE implementation of the forward component

Fields inherited from class com.hp.hpl.jena.reasoner.rulesys.BasicForwardRuleInfGraph

filterFunctors

Fields inherited from class com.hp.hpl.jena.graph.impl.GraphBase

TOSTRING_TRIPLE_BASE, TOSTRING_TRIPLE_LIMIT

Fields inherited from interface com.hp.hpl.jena.graph.Graph

emptyGraph

Constructor Summary

FBRuleInfGraph(Reasoner reasoner, Graph schema)
Constructor.

FBRuleInfGraph(Reasoner reasoner, List<Rule> rules, Graph schema)
Constructor.

FBRuleInfGraph(Reasoner reasoner, List<Rule> rules, Graph schema, Graph data)
Constructor.

FBRuleInfGraph(Reasoner reasoner, List<Rule> rules, Graph schema, ReificationStyle style)

Method Summary

boolean	accept(Object tin) Post-filter query results to hide unwanted triples from the glare of publicity.
void	addBRule(Rule brule) Adds a new Backward rule as a rusult of a forward rule process.
void	addBRules(List<Rule> rules) Adds a set of new Backward rules
void	addDeduction(Triple t) Add a new deduction to the deductions graph.
void	addPreprocessingHook(RulePreprocessHook hook) Add a new preprocessing hook defining an operation that should be run when the preparation phase is underway.
void	addRuleDuringPrepare(Rule rule) Add a new rule to the rule set.
ValidityReport.Report	checkLiteral(Node prop, Triple triple) Check a given literal value for a property against the set of known range constraints for it.
void	close() Free all resources, any further use of this Graph is an error.
void	deleteBRule(Rule brule) Deletes a new Backward rule as a rules of a forward rule process.
com.hp.hpl.jena.util.iterator.ExtendedIterator<Triple>	find(TriplePattern pattern) Basic pattern lookup interface.
com.hp.hpl.jena.util.iterator.ExtendedIterator<Triple>	findDataMatches(Node subject, Node predicate, Node object) Search the combination of data and deductions graphs for the given triple pattern.
com.hp.hpl.jena.util.iterator.ExtendedIterator<Triple>	findDataMatches(TriplePattern pattern) Search the combination of data and deductions graphs for the given triple pattern.
com.hp.hpl.jena.util.iterator.ExtendedIterator<Triple>	findFull(TriplePattern pattern) Internal variant of find which omits the filters which block illegal RDF data.
com.hp.hpl.jena.util.iterator.ExtendedIterator<Triple>	findWithContinuation(TriplePattern pattern, Finder continuation) Extended find interface used in situations where the implementator may or may not be able to answer the complete query.
List<Rule>	getBRules() Return an ordered list of all registered backward rules.
long	getNRulesFired() Return the number of rules fired since this rule engine instance was created and initialized.
List<Rule>	getRules() Return the originally supplied set of rules, may be a mix of forward and backward rules.
Node	getTemp(Node instance, Node prop, Node pclass) Retrieve or create a bNode representing an inferred property value.
com.hp.hpl.jena.util.iterator.ExtendedIterator<Triple>	graphBaseFind(Node subject, Node property, Node object) Returns an iterator over Triples.
void	hideNode(Node n) Called to flag that a node should be hidden from external queries.
void	performAdd(Triple t) Add one triple to the data graph, run any rules triggered by the new data item, recursively adding any generated triples.
void	performDelete(Triple t) Removes the triple t (if possible) from the set belonging to this graph.
void	prepare() Perform any initial processing and caching.
void	printLPProfile() Print a profile of LP rules used since the last reset.
boolean	processBuiltin(ClauseEntry clause, Rule rule, BindingEnvironment env) Process a call to a builtin predicate
void	rebind() Cause the inference graph to reconsult the underlying graph to take into account changes.
void	rebindAll() Cause the inference graph to reconsult both the underlying graph and the reasoner ruleset, permits the forward rule set to be dynamically changed.
void	reset() Flush out all cached results.
void	resetLPProfile(boolean enable) Reset the LP engine profile.
void	setDatatypeRangeValidation(boolean on) Switch on/off datatype range validation
void	setDerivationLogging(boolean recordDerivations) Set to true to enable derivation caching
void	setTabled(Node predicate) Set a predicate to be tabled/memoized by the LP engine.
void	setTraceOn(boolean state) Set the state of the trace flag.
void	setUseTGCCache() Instantiate the optional caches for the subclass/suproperty lattices.
ValidityReport	validate() Test the consistency of the bound data.

Methods inherited from class com.hp.hpl.jena.reasoner.rulesys.BasicForwardRuleInfGraph

constructReifier, getCurrentDeductionsGraph, getDeductionsGraph, getDerivation, getSchemaGraph, graphBaseSize, logDerivation, rebind, setFunctorFiltering, setRuleStore, shouldLogDerivations, shouldTrace, silentAdd

Methods inherited from class com.hp.hpl.jena.reasoner.BaseInfGraph

cloneWithPremises, find, getBulkUpdateHandler, getCapabilities, getGlobalProperty, getPrefixMapping, getRawGraph, getReasoner, getTransactionHandler, getVersion, graphBaseFind, isEmpty, isPrepared, testGlobalProperty

Methods inherited from class com.hp.hpl.jena.graph.impl.GraphBase

add, contains, contains, delete, dependsOn, find, find, forTestingOnly_graphBaseFind, getEventManager, getReifier, getStatisticsHandler, isClosed, isIsomorphicWith, notifyAdd, notifyDelete, queryHandler, size, toString, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.hp.hpl.jena.reasoner.rulesys.BackwardRuleInfGraphI

getVersion, logDerivation

Methods inherited from interface com.hp.hpl.jena.reasoner.rulesys.SilentAddI

silentAdd

Methods inherited from interface com.hp.hpl.jena.reasoner.InfGraph

find, getDeductionsGraph, getDerivation, getGlobalProperty, getRawGraph, getReasoner, rebind, testGlobalProperty

Methods inherited from interface com.hp.hpl.jena.graph.Graph

contains, contains, delete, dependsOn, find, find, getBulkUpdateHandler, getCapabilities, getEventManager, getPrefixMapping, getReifier, getStatisticsHandler, getTransactionHandler, isClosed, isEmpty, isIsomorphicWith, queryHandler, size

Methods inherited from interface com.hp.hpl.jena.graph.GraphAdd

add

Field Detail

useRETE

public static boolean useRETE

Static switch from Basic to RETE implementation of the forward component

Constructor Detail

FBRuleInfGraph

public FBRuleInfGraph(Reasoner reasoner,
                      Graph schema)

Constructor.

Parameters:

reasoner - the reasoner which created this inf graph instance

schema - the (optional) schema graph to be included

FBRuleInfGraph

public FBRuleInfGraph(Reasoner reasoner,
                      List<Rule> rules,
                      Graph schema)

Constructor.

Parameters:

reasoner - the reasoner which created this inf graph instance

rules - the rules to process

schema - the (optional) schema graph to be included

FBRuleInfGraph

public FBRuleInfGraph(Reasoner reasoner,
                      List<Rule> rules,
                      Graph schema,
                      ReificationStyle style)

FBRuleInfGraph

public FBRuleInfGraph(Reasoner reasoner,
                      List<Rule> rules,
                      Graph schema,
                      Graph data)

Constructor.

Parameters:

reasoner - the reasoner which created this inf graph instance

rules - the rules to process

schema - the (optional) schema graph to be included

data - the data graph to be processed

Method Detail

setUseTGCCache

public void setUseTGCCache()

Instantiate the optional caches for the subclass/suproperty lattices. Unless this call is made the TGC caching will not be used.

findDataMatches

public com.hp.hpl.jena.util.iterator.ExtendedIterator<Triple> findDataMatches(Node subject,
                                                                              Node predicate,
                                                                              Node object)

Search the combination of data and deductions graphs for the given triple pattern. This may different from the normal find operation in the base of hybrid reasoners where we are side-stepping the backward deduction step.

Specified by:

findDataMatches in interface ForwardRuleInfGraphI

Overrides:

findDataMatches in class BasicForwardRuleInfGraph

findDataMatches

public com.hp.hpl.jena.util.iterator.ExtendedIterator<Triple> findDataMatches(TriplePattern pattern)

Search the combination of data and deductions graphs for the given triple pattern. This may different from the normal find operation in the base of hybrid reasoners where we are side-stepping the backward deduction step.

Specified by:

findDataMatches in interface BackwardRuleInfGraphI

processBuiltin

public boolean processBuiltin(ClauseEntry clause,
                              Rule rule,
                              BindingEnvironment env)

Process a call to a builtin predicate

Specified by:

processBuiltin in interface BackwardRuleInfGraphI

Parameters:

clause - the Functor representing the call

env - the BindingEnvironment for this call

rule - the rule which is invoking this call

Returns:

true if the predicate succeeds

addBRule

public void addBRule(Rule brule)

Adds a new Backward rule as a rusult of a forward rule process. Only some infgraphs support this.

Specified by:

addBRule in interface ForwardRuleInfGraphI

Overrides:

addBRule in class BasicForwardRuleInfGraph

deleteBRule

public void deleteBRule(Rule brule)

Deletes a new Backward rule as a rules of a forward rule process. Only some infgraphs support this.

Specified by:

deleteBRule in interface ForwardRuleInfGraphI

Overrides:

deleteBRule in class BasicForwardRuleInfGraph

addBRules

public void addBRules(List<Rule> rules)

Adds a set of new Backward rules

getBRules

public List<Rule> getBRules()

Return an ordered list of all registered backward rules. Includes those generated by forward productions.

getRules

public List<Rule> getRules()

Return the originally supplied set of rules, may be a mix of forward and backward rules.

setTabled

public void setTabled(Node predicate)

Set a predicate to be tabled/memoized by the LP engine.

addDeduction

public void addDeduction(Triple t)

Add a new deduction to the deductions graph.

Specified by:

addDeduction in interface ForwardRuleInfGraphI

Overrides:

addDeduction in class BasicForwardRuleInfGraph

getTemp

public Node getTemp(Node instance,
                    Node prop,
                    Node pclass)

Retrieve or create a bNode representing an inferred property value.

Specified by:

getTemp in interface BackwardRuleInfGraphI

Parameters:

instance - the base instance node to which the property applies

prop - the property node whose value is being inferred

pclass - the (optional, can be null) class for the inferred value.

Returns:

the bNode representing the property value

addRuleDuringPrepare

public void addRuleDuringPrepare(Rule rule)

Add a new rule to the rule set. This should only be used by implementations of RuleProprocessHook (which are called during rule system preparation phase). If called at other times the rule won't be correctly transferred into the underlying engines.

addPreprocessingHook

public void addPreprocessingHook(RulePreprocessHook hook)

Add a new preprocessing hook defining an operation that should be run when the preparation phase is underway.

prepare

public void prepare()

Perform any initial processing and caching. This call is optional. Most engines either have negligable set up work or will perform an implicit "prepare" if necessary. The call is provided for those occasions where substantial preparation work is possible (e.g. running a forward chaining rule system) and where an application might wish greater control over when this prepration is done.

Specified by:

prepare in interface InfGraph

Overrides:

prepare in class BasicForwardRuleInfGraph

rebind

public void rebind()

Cause the inference graph to reconsult the underlying graph to take into account changes. Normally changes are made through the InfGraph's add and remove calls are will be handled appropriately. However, in some cases changes are made "behind the InfGraph's back" and this forces a full reconsult of the changed data.

Specified by:

rebind in interface InfGraph

Overrides:

rebind in class BasicForwardRuleInfGraph

rebindAll

public void rebindAll()

Cause the inference graph to reconsult both the underlying graph and the reasoner ruleset, permits the forward rule set to be dynamically changed. Causes the entire rule engine to be rebuilt from the current ruleset and reinitialized against the current data. Not needed for normal cases.

setTraceOn

public void setTraceOn(boolean state)

Set the state of the trace flag. If set to true then rule firings are logged out to the Log at "INFO" level.

Overrides:

setTraceOn in class BasicForwardRuleInfGraph

setDerivationLogging

public void setDerivationLogging(boolean recordDerivations)

Set to true to enable derivation caching

Specified by:

setDerivationLogging in interface InfGraph

Overrides:

setDerivationLogging in class BasicForwardRuleInfGraph

getNRulesFired

public long getNRulesFired()

Return the number of rules fired since this rule engine instance was created and initialized. The current implementation only counts forward rules and does not track dynamic backward rules needed for specific queries.

Overrides:

getNRulesFired in class BasicForwardRuleInfGraph

findWithContinuation

public com.hp.hpl.jena.util.iterator.ExtendedIterator<Triple> findWithContinuation(TriplePattern pattern,
                                                                                   Finder continuation)

Extended find interface used in situations where the implementator may or may not be able to answer the complete query. It will attempt to answer the pattern but if its answers are not known to be complete then it will also pass the request on to the nested Finder to append more results.

Overrides:

findWithContinuation in class BasicForwardRuleInfGraph

Parameters:

pattern - a TriplePattern to be matched against the data

continuation - either a Finder or a normal Graph which will be asked for additional match results if the implementor may not have completely satisfied the query.

findFull

public com.hp.hpl.jena.util.iterator.ExtendedIterator<Triple> findFull(TriplePattern pattern)

Internal variant of find which omits the filters which block illegal RDF data.

Parameters:

pattern - a TriplePattern to be matched against the data

graphBaseFind

public com.hp.hpl.jena.util.iterator.ExtendedIterator<Triple> graphBaseFind(Node subject,
                                                                            Node property,
                                                                            Node object)

Returns an iterator over Triples. This implementation assumes that the underlying findWithContinuation will have also consulted the raw data.

Overrides:

graphBaseFind in class BasicForwardRuleInfGraph

find

public com.hp.hpl.jena.util.iterator.ExtendedIterator<Triple> find(TriplePattern pattern)

Basic pattern lookup interface. This implementation assumes that the underlying findWithContinuation will have also consulted the raw data.

Overrides:

find in class BasicForwardRuleInfGraph

Parameters:

pattern - a TriplePattern to be matched against the data

Returns:

a ExtendedIterator over all Triples in the data set that match the pattern

reset

public void reset()

Flush out all cached results. Future queries have to start from scratch.

Specified by:

reset in interface InfGraph

Overrides:

reset in class BaseInfGraph

performAdd

public void performAdd(Triple t)

Add one triple to the data graph, run any rules triggered by the new data item, recursively adding any generated triples.

Specified by:

performAdd in interface com.hp.hpl.jena.graph.impl.GraphWithPerform

Overrides:

performAdd in class BasicForwardRuleInfGraph

performDelete

public void performDelete(Triple t)

Removes the triple t (if possible) from the set belonging to this graph.

Specified by:

performDelete in interface com.hp.hpl.jena.graph.impl.GraphWithPerform

Overrides:

performDelete in class BasicForwardRuleInfGraph

close

public void close()

Free all resources, any further use of this Graph is an error.

Specified by:

close in interface Graph

Overrides:

close in class BasicForwardRuleInfGraph

validate

public ValidityReport validate()

Test the consistency of the bound data. This normally tests the validity of the bound instance data against the bound schema data.

Specified by:

validate in interface InfGraph

Overrides:

validate in class BaseInfGraph

Returns:

a ValidityReport structure

setDatatypeRangeValidation

public void setDatatypeRangeValidation(boolean on)

Switch on/off datatype range validation

checkLiteral

public ValidityReport.Report checkLiteral(Node prop,
                                          Triple triple)

Check a given literal value for a property against the set of known range constraints for it.

Parameters:

prop - the property node whose range is under scrutiny

triple - the statement whose object value is to be checked.

Returns:

null if the range is legal, otherwise a ValidityReport.Report which describes the problem.

hideNode

public void hideNode(Node n)

Called to flag that a node should be hidden from external queries.

resetLPProfile

public void resetLPProfile(boolean enable)

Reset the LP engine profile.

Parameters:

enable - it true then profiling will continue with a new empty profile table, if false profiling will stop all current data lost.

printLPProfile

public void printLPProfile()

Print a profile of LP rules used since the last reset.

accept

public boolean accept(Object tin)

Post-filter query results to hide unwanted triples from the glare of publicity. Unwanted triples are triples with Functor literals and triples with hidden nodes as subject or object.