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

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

All Implemented Interfaces:

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

Direct Known Subclasses:

FBRuleInfGraph, RETERuleInfGraph

public class BasicForwardRuleInfGraph
extends BaseInfGraph
implements ForwardRuleInfGraphI

An inference graph interface that runs a set of forward chaining rules to conclusion on each added triple and stores the entire result set.

This implementation has a horribly inefficient rule chainer built in. Once we have this working generalize this to an interface than can call out to a rule engine and build a real rule engine (e.g. Rete style).

Version:

$Revision: 1.4 $ on $Date: 2009/10/06 07:59:55 $

Author:

Dave Reynolds

Nested Class Summary

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

BaseInfGraph.InfCapabilities, BaseInfGraph.InfFindSafeCapabilities, BaseInfGraph.InfTransactionHandler

Field Summary

boolean

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

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

BasicForwardRuleInfGraph(Reasoner reasoner, Graph schema)
Constructor.

BasicForwardRuleInfGraph(Reasoner reasoner, java.util.List<Rule> rules, Graph schema)
Constructor.

BasicForwardRuleInfGraph(Reasoner reasoner, java.util.List<Rule> rules, Graph schema, Graph data)
Constructor.

BasicForwardRuleInfGraph(Reasoner reasoner, java.util.List<Rule> rules, Graph schema, ReificationStyle style)

Method Summary

void	addBRule(Rule brule) Adds a new Backward rule as a rules of a forward rule process.
void	addDeduction(Triple t) Add a new deduction to the deductions graph.
void	close() Free all resources, any further use of this Graph is an error.
Reifier	constructReifier() Inference graphs share the reifiers of their underlying raw graphs.
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>	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.
Graph	getCurrentDeductionsGraph() Return the Graph containing all the static deductions available so far.
Graph	getDeductionsGraph() Return the Graph containing all the static deductions available so far.
java.util.Iterator<Derivation>	getDerivation(Triple t) Return the derivation of at triple.
long	getNRulesFired() Return the number of rules fired since this rule engine instance was created and initialized
Graph	getSchemaGraph() Return the schema graph, if any, bound into this inference graph.
com.hp.hpl.jena.util.iterator.ExtendedIterator<Triple>	graphBaseFind(Node subject, Node property, Node object) Returns an iterator over Triples.
int	graphBaseSize() Return the number of triples in the inferred graph
void	logDerivation(Triple t, Derivation derivation) Log a dervivation record against the given triple.
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	rebind() Cause the inference graph to reconsult the underlying graph to take into account changes.
void	rebind(Graph data) Replace the underlying data graph for this inference graph and start any inferences over again.
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	setRuleStore(java.lang.Object ruleStore) Attach a compiled rule set to this inference graph.
void	setTraceOn(boolean state) Set the state of the trace flag.
boolean	shouldLogDerivations() Return true if derivation logging is enabled.
boolean	shouldTrace() Return true if tracing should be acted on - i.e.
void	silentAdd(Triple t) Assert a new triple in the deduction graph, bypassing any processing machinery.

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

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

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.InfGraph

find, getGlobalProperty, getRawGraph, getReasoner, reset, testGlobalProperty, validate

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

filterFunctors

public boolean filterFunctors

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

Constructor Detail

BasicForwardRuleInfGraph

public BasicForwardRuleInfGraph(Reasoner reasoner,
                                Graph schema)

Constructor. Creates a new inference graph to which a (compiled) rule set and a data graph can be attached. This separation of binding is useful to allow any configuration parameters (such as logging) to be set before the data is added. Note that until the data is added using rebind then any operations like add, remove, find will result in errors.

Parameters:

reasoner - the parent reasoner

schema - the (optional) schema data which is being processed

BasicForwardRuleInfGraph

public BasicForwardRuleInfGraph(Reasoner reasoner,
                                java.util.List<Rule> rules,
                                Graph schema)

Constructor. Creates a new inference graph based on the given rule set. No data graph is attached at this stage. This is to allow any configuration parameters (such as logging) to be set before the data is added. Note that until the data is added using rebind then any operations like add, remove, find will result in errors.

Parameters:

reasoner - the parent reasoner

rules - the list of rules to use this time

schema - the (optional) schema or preload data which is being processed

BasicForwardRuleInfGraph

public BasicForwardRuleInfGraph(Reasoner reasoner,
                                java.util.List<Rule> rules,
                                Graph schema,
                                ReificationStyle style)

BasicForwardRuleInfGraph

public BasicForwardRuleInfGraph(Reasoner reasoner,
                                java.util.List<Rule> rules,
                                Graph schema,
                                Graph data)

Constructor. Creates a new inference graph based on the given rule set then processes the initial data graph. No precomputed deductions are loaded.

Parameters:

reasoner - the parent reasoner

rules - the list of rules to use this time

schema - the (optional) schema or preload data which is being processed

data - the data graph to be processed

Method Detail

setRuleStore

public void setRuleStore(java.lang.Object ruleStore)

Attach a compiled rule set to this inference graph.

Parameters:

ruleStore - a compiled set of rules (i.e. the result of an FRuleEngine.compile).

rebind

public void rebind(Graph data)

Replace the underlying data graph for this inference graph and start any inferences over again. This is primarily using in setting up ontology imports processing to allow an imports multiunion graph to be inserted between the inference graph and the raw data, before processing.

Specified by:

rebind in interface InfGraph

Overrides:

rebind in class BaseInfGraph

Parameters:

data - the new raw data graph

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 BaseInfGraph

getSchemaGraph

public Graph getSchemaGraph()

Return the schema graph, if any, bound into this inference graph.

Specified by:

getSchemaGraph in class BaseInfGraph

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 BaseInfGraph

addDeduction

public void addDeduction(Triple t)

Add a new deduction to the deductions graph.

Specified by:

addDeduction in interface ForwardRuleInfGraphI

setFunctorFiltering

public void setFunctorFiltering(boolean param)

Set to true to cause functor-valued literals to be dropped from rule output. Default is true.

Specified by:

setFunctorFiltering in interface ForwardRuleInfGraphI

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.

Specified by:

findWithContinuation in class BaseInfGraph

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.

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 BaseInfGraph

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 BaseInfGraph

Parameters:

pattern - a TriplePattern to be matched against the data

Returns:

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

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 BaseInfGraph

graphBaseSize

public int graphBaseSize()

Return the number of triples in the inferred graph

Overrides:

graphBaseSize in class BaseInfGraph

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

addBRule

public void addBRule(Rule brule)

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

Specified by:

addBRule in interface ForwardRuleInfGraphI

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

getDeductionsGraph

public Graph getDeductionsGraph()

Return the Graph containing all the static deductions available so far. Will force a prepare.

Specified by:

getDeductionsGraph in interface InfGraph

Specified by:

getDeductionsGraph in interface ForwardRuleInfGraphI

Overrides:

getDeductionsGraph in class BaseInfGraph

Returns:

the deductions graph, if relevant for this class of inference engine or null if not.

getCurrentDeductionsGraph

public Graph getCurrentDeductionsGraph()

Return the Graph containing all the static deductions available so far. Does not trigger a prepare action. Returns a SafeWrapper and so can be used for update (thus triggering listeners) but not for access to generalized triples

Specified by:

getCurrentDeductionsGraph in interface ForwardRuleInfGraphI

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

logDerivation

public void logDerivation(Triple t,
                          Derivation derivation)

Log a dervivation record against the given triple.

Specified by:

logDerivation in interface ForwardRuleInfGraphI

silentAdd

public void silentAdd(Triple t)

Assert a new triple in the deduction graph, bypassing any processing machinery.

Specified by:

silentAdd in interface SilentAddI

setDerivationLogging

public void setDerivationLogging(boolean recordDerivations)

Set to true to enable derivation caching

Specified by:

setDerivationLogging in interface InfGraph

Overrides:

setDerivationLogging in class BaseInfGraph

shouldLogDerivations

public boolean shouldLogDerivations()

Return true if derivation logging is enabled.

Specified by:

shouldLogDerivations in interface ForwardRuleInfGraphI

getDerivation

public java.util.Iterator<Derivation> getDerivation(Triple t)

Return the derivation of at triple. The derivation is a List of DerivationRecords

Specified by:

getDerivation in interface InfGraph

Overrides:

getDerivation in class BaseInfGraph

Returns:

an iterator over Derivation records or null if there is no derivation information available for this triple.

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.

shouldTrace

public boolean shouldTrace()

Return true if tracing should be acted on - i.e. if traceOn is true and we are past the bootstrap phase.

Specified by:

shouldTrace in interface ForwardRuleInfGraphI

getNRulesFired

public long getNRulesFired()

Return the number of rules fired since this rule engine instance was created and initialized

constructReifier

public Reifier constructReifier()

Description copied from class: BaseInfGraph

Inference graphs share the reifiers of their underlying raw graphs. This may be too simplistic - they won't see quads flying past. TODO write a test case that reveals this.

Overrides:

constructReifier in class BaseInfGraph

See Also:

Graph.getReifier()