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

java.lang.Object
  extended by com.hp.hpl.jena.graph.impl.GraphBase
      extended by com.hp.hpl.jena.reasoner.BaseInfGraph
          extended by com.hp.hpl.jena.reasoner.rulesys.BasicForwardRuleInfGraph
              extended by com.hp.hpl.jena.reasoner.rulesys.FBRuleInfGraph
All Implemented Interfaces:
Graph, GraphAdd, com.hp.hpl.jena.graph.impl.GraphWithPerform, InfGraph, BackwardRuleInfGraphI, ForwardRuleInfGraphI, SilentAddI, Filter
Direct Known Subclasses:
RDFSRuleInfGraph

public class FBRuleInfGraph
extends BasicForwardRuleInfGraph
implements BackwardRuleInfGraphI, Filter

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.46 $ on $Date: 2004/12/07 09:56:28 $
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
 
Field Summary
 boolean filterFunctors
          Flag, if true then find results will be filtered to remove functors and illegal RDF
static boolean useRETE
          Static switch from Basic to RETE implementation of the forward component
 
Fields inherited from interface com.hp.hpl.jena.graph.Graph
emptyGraph
 
Fields inherited from interface com.hp.hpl.jena.util.iterator.Filter
any
 
Constructor Summary
FBRuleInfGraph(Reasoner reasoner, Graph schema)
          Constructor.
FBRuleInfGraph(Reasoner reasoner, List rules, Graph schema)
          Constructor.
FBRuleInfGraph(Reasoner reasoner, List rules, Graph schema, Graph data)
          Constructor.
 
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 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.
 InfGraph cloneWithPremises(Graph premises)
          Return a new inference graph which is a clone of the current graph together with an additional set of data premises.
 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.
 ExtendedIterator find(TriplePattern pattern)
          Basic pattern lookup interface.
 ExtendedIterator findDataMatches(Node subject, Node predicate, Node object)
          Search the combination of data and deductions graphs for the given triple pattern.
 ExtendedIterator findDataMatches(TriplePattern pattern)
          Search the combination of data and deductions graphs for the given triple pattern.
 ExtendedIterator findFull(TriplePattern pattern)
          Internal variant of find which omits the filters which block illegal RDF data.
 ExtendedIterator 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 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 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.
 ExtendedIterator 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 reset()
          Flush out all cached results.
 void resetLPProfile(boolean enable)
          Reset the LP engine profile.
 void setDerivationLogging(boolean recordDerivations)
          Set to true to enable derivation caching
 void setFunctorFiltering(boolean param)
          Set to true to cause functor-valued literals to be dropped from rule output.
 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
getDeductionsGraph, getDerivation, getSchemaGraph, graphBaseSize, logDerivation, rebind, setRuleStore, shouldLogDerivations, shouldTrace, silentAdd
 
Methods inherited from class com.hp.hpl.jena.reasoner.BaseInfGraph
find, getBulkUpdateHandler, getCapabilities, getGlobalProperty, getPrefixMapping, getRawGraph, getReasoner, getReifier, graphBaseFind, isEmpty, testGlobalProperty
 
Methods inherited from class com.hp.hpl.jena.graph.impl.GraphBase
add, contains, contains, delete, dependsOn, find, find, getEventManager, getTransactionHandler, 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
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, getTransactionHandler, 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


filterFunctors

public boolean filterFunctors
Flag, if true then find results will be filtered to remove functors and illegal RDF

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 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 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 ExtendedIterator 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 ExtendedIterator 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 rules)
Adds a set of new Backward rules


getBRules

public List getBRules()
Return an ordered list of all registered backward rules. Includes those generated by forward productions.


getRules

public List 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

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

setFunctorFiltering

public void setFunctorFiltering(boolean param)
Set to true to cause functor-valued literals to be dropped from rule output. Default is true.


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 ExtendedIterator 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 ExtendedIterator 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 ExtendedIterator 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 ExtendedIterator 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

cloneWithPremises

public InfGraph cloneWithPremises(Graph premises)
Return a new inference graph which is a clone of the current graph together with an additional set of data premises. Attempts to the replace the default brute force implementation by one that can reuse some of the existing deductions.

Overrides:
cloneWithPremises in class BaseInfGraph

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

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.

Specified by:
accept in interface Filter
Parameters:
tin - The object to accept or reject.
Returns:
true if the object is wanted.


Copyright © 2000, 2001, 2002, 2003, 2004 Hewlett-Packard Development Company, LP