org.apache.marmotta.kiwi.reasoner.engine

Class ReasoningEngine

java.lang.Object

org.apache.marmotta.kiwi.reasoner.engine.ReasoningEngine

All Implemented Interfaces:

TransactionListener

public class ReasoningEngine
extends Object
implements TransactionListener

This class implements the evaluation of reasoning programs on the triple store. It has two different modes:

• incremental reasoning: when new triples are added or old triples are removed, the inferred information is updated accordingly
• full reasoning: (re-)runs the reasoning process over all triples currently contained in the triple store

Since reasoning can require some time, the actual execution of incremental reasonong is implemented in a producer-consumer style. When new transaction data is available, it is added to a queue. A separate reasoning thread then takes new transaction data and processes the rules asynchronously.

The reasoning engine uses its own connection to the database to carry out reasoning tasks.

TODO: we need to clarify conceptually whether it would be correct to run several reasoner threads in parallel. In theory, reasoning here is strictly monotonic so there should not be a problem. In practice, we might miss certain triples because the order of transactions might be messed up. Maybe it makes more sense to parallelize the execution or rules instead.

User: Sebastian Schaffert (sschaffert@apache.org)

Field Summary

Fields

Modifier and Type	Field and Description
protected static com.google.common.base.Equivalence<org.openrdf.model.Statement>	equivalence

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ReasoningEngine()
	ReasoningEngine(KiWiReasoningPersistence persistence, TransactionalSail store, ReasoningConfiguration config)

Method Summary

Methods

Modifier and Type	Method and Description
void	afterCommit(TransactionData data) Incrementally apply the updates that are contained in the transaction data to the reasoning programs that are in the system.
void	beforeCommit(TransactionData data) Called before a transaction commits.
protected void	endTask() Stop the currently active reasoning task.
protected Set<Justification>	getBaseJustifications(KiWiReasoningConnection connection, Set<Justification> justifications) For all justifications contained in the set passed as argument, create corresponding base justifications, i.e.
protected Collection<Justification>	getJustifications(KiWiReasoningConnection connection, KiWiTriple t, Set<Justification> transactionJustifications) Return the justifications for the triple passed as argument.
boolean	isRunning() Return true in case the reasoner is currently executing, false otherwise.
void	loadPrograms()
protected static QueryResult	matches(Pattern pattern, KiWiTriple triple)
void	notifyAddRule(Rule rule) In case a new rule has been added to one of the reasoning programs, process only this rule addition incrementally.
void	notifyRemoveRules() In case an existing rule has been removed from one of the reasoning programs, remove all triples that are based on this rule by consulting the justifications that use this rule.
void	programChanged(Program program)
void	reRunPrograms() Clean all inferred triples and re-run all reasoning rules.
void	rollback(TransactionData data) Called when a transaction rolls back.
void	shutdown()
void	shutdown(boolean force)
protected void	startTask(String name, String taskGroup) Start a new reasoner task to collect status messages.
protected void	updateTaskMaxProgress(int progress) Set the maximum steps needed in the task progress (if any)
protected void	updateTaskProgress(int progress) Update the task progress (if any)
protected void	updateTaskStatus(String message) Update the status of the reasoner task with the given message.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

equivalence

protected static com.google.common.base.Equivalence<org.openrdf.model.Statement> equivalence

Constructor Detail

ReasoningEngine

protected ReasoningEngine()

ReasoningEngine

public ReasoningEngine(KiWiReasoningPersistence persistence,
               TransactionalSail store,
               ReasoningConfiguration config)

Method Detail

loadPrograms

public void loadPrograms()

programChanged

public void programChanged(Program program)

notifyAddRule

public void notifyAddRule(Rule rule)

In case a new rule has been added to one of the reasoning programs, process only this rule addition incrementally. Since the reasoner is strictly monotonic, this is sufficient.

Parameters:

rule -

notifyRemoveRules

public void notifyRemoveRules()

In case an existing rule has been removed from one of the reasoning programs, remove all triples that are based on this rule by consulting the justifications that use this rule. Since the reasoner is strictly monotonic, this is sufficient to get the correct set of materialized triples.

afterCommit

public void afterCommit(TransactionData data)

Incrementally apply the updates that are contained in the transaction data to the reasoning programs that are in the system.

Called after a transaction has committed. The transaction data will contain all changes done in the transaction since the last commit. This method should be used in case the transaction listener aims to perform additional activities in a new transaction or outside the transaction management, e.g. notifying a server on the network, adding data to a cache, or similar.

Specified by:

afterCommit in interface TransactionListener

Parameters:

data -

beforeCommit

public void beforeCommit(TransactionData data)

Called before a transaction commits. The transaction data will contain all changes done in the transaction since the last commit. This method should be used in case the transaction listener aims to perform additional activities in the same transaction, like inserting or updating database tables.

Specified by:

beforeCommit in interface TransactionListener

Parameters:

data -

rollback

public void rollback(TransactionData data)

Called when a transaction rolls back.

Specified by:

rollback in interface TransactionListener

startTask

protected void startTask(String name,
             String taskGroup)

Start a new reasoner task to collect status messages. Informational purposes only.

Parameters:

name -

endTask

protected void endTask()

Stop the currently active reasoning task. Informational purposes only.

updateTaskStatus

protected void updateTaskStatus(String message)

Update the status of the reasoner task with the given message. This will simply send all update messages to registered status listeners.

Parameters:

message -

updateTaskProgress

protected void updateTaskProgress(int progress)

Update the task progress (if any)

Parameters:

progress -

updateTaskMaxProgress

protected void updateTaskMaxProgress(int progress)

Set the maximum steps needed in the task progress (if any)

Parameters:

progress -

reRunPrograms

public void reRunPrograms()

Clean all inferred triples and re-run all reasoning rules.

getJustifications

protected Collection<Justification> getJustifications(KiWiReasoningConnection connection,
                                          KiWiTriple t,
                                          Set<Justification> transactionJustifications)
                                               throws SQLException

Return the justifications for the triple passed as argument.

Parameters:

t -

Returns:

Throws:

SQLException

getBaseJustifications

protected Set<Justification> getBaseJustifications(KiWiReasoningConnection connection,
                                       Set<Justification> justifications)
                                            throws SQLException,
                                                   ReasoningException

For all justifications contained in the set passed as argument, create corresponding base justifications, i.e. justifications that only contain base triples and no inferred triples.

Parameters:

justifications -

Returns:

Throws:

SQLException

ReasoningException

matches

protected static QueryResult matches(Pattern pattern,
                  KiWiTriple triple)

isRunning

public boolean isRunning()

Return true in case the reasoner is currently executing, false otherwise.

Returns:

shutdown

public void shutdown()

shutdown

public void shutdown(boolean force)