/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.jena.reasoner;
import org.apache.jena.graph.Capabilities ;
import org.apache.jena.graph.Graph ;
import org.apache.jena.rdf.model.* ;
/**
* The minimal interface to which all reasoners (or reasoner adaptors) conform.
* This only supports attaching the reasoner to a set of RDF graphs
* which represent the rules or ontologies and instance data. The actual
* reasoner requests are made through the InfGraph which is generated once
* the reasoner has been bound to a set of RDF data.
*/
public interface Reasoner {
/**
* This is most commonly used to attach an ontology (a set of tbox
* axioms in description logics jargon) to a reasoner. A certain amount
* of precomputation may be done at this time (e.g. constructing the
* class lattice). When the reasoner is later applied some instance data
* these cached precomputations may be reused.
* <p>In fact this call may be more general than the above
* description suggests. Firstly, a reasoner that supports arbitrary rules
* rather than ontologies may use the same method to bind the reasoner
* to the specific rule set (encoded in RDF). Secondly, even in the ontology
* case a given reasoner may not require a strict separation of tbox and
* abox - it may allow instance data in the tbox and terminology axioms in
* the abox. </p>
* <p>A reasoner is free to simply note this set of RDF and merge with any
* future RDF rather than do processing at this time. </p>
* @param tbox the ontology axioms or rule set encoded in RDF
* @return a reasoner instace which can be used to process a data graph
* @throws ReasonerException if the reasoner cannot be
* bound to a rule set in this way, for example if the underlying engine
* can only accept a single rule set in this way and one rule set has
* already been bound in of if the ruleset is illformed.
*/
public Reasoner bindSchema(Graph tbox) throws ReasonerException;
/**
* This is most commonly used to attach an ontology (a set of tbox
* axioms in description logics jargon) to a reasoner. A certain amount
* of precomputation may be done at this time (e.g. constructing the
* class lattice). When the reasoner is later applied some instance data
* these cached precomputations may be reused.
* <p>In fact this call may be more general than the above
* description suggests. Firstly, a reasoner that supports arbitrary rules
* rather than ontologies may use the same method to bind the reasoner
* to the specific rule set (encoded in RDF). Secondly, even in the ontology
* case a given reasoner may not require a strict separation of tbox and
* abox - it may allow instance data in the tbox and terminology axioms in
* the abox. </p>
* <p>A reasoner is free to simply note this set of RDF and merge with any
* future RDF rather than do processing at this time. </p>
* @param tbox the ontology axioms or rule set encoded in RDF
* @return a reasoner instace which can be used to process a data graph
* @throws ReasonerException if the reasoner cannot be
* bound to a rule set in this way, for example if the underlying engine
* can only accept a single rule set in this way and one rule set has
* already been bound in of if the ruleset is illformed.
*/
public Reasoner bindSchema(Model tbox) throws ReasonerException;
/**
* Attach the reasoner to a set of RDF data to process.
* The reasoner may already have been bound to specific rules or ontology
* axioms (encoded in RDF) through earlier bindRuleset calls.
* @param data the RDF data to be processed, some reasoners may restrict
* the range of RDF which is legal here (e.g. syntactic restrictions in OWL).
* @return an inference graph through which the data+reasoner can be queried.
* @throws ReasonerException if the data is ill-formed according to the
* constraints imposed by this reasoner.
*/
public InfGraph bind(Graph data) throws ReasonerException;
/**
* Switch on/off drivation logging.
* If set to true then the InfGraph created from the bind operation will start
* life with recording of derivations switched on. This is currently only of relevance
* to rule-based reasoners.
* <p>
* Default - false.
*/
public void setDerivationLogging(boolean logOn);
/**
* Set a configuration parameter for the reasoner. Parameters can identified
* by URI and can also be set when the Reasoner instance is created by specifying a
* configuration in RDF.
*
* @param parameterUri the property identifying the parameter to be changed
* @param value the new value for the parameter, typically this is a wrapped
* java object like Boolean or Integer.
*/
public void setParameter(Property parameterUri, Object value);
/**
* Return a description of the capabilities of this reasoner encoded in
* RDF. These capabilities may be static or may depend on configuration
* information supplied at construction time. May be null if there are
* no useful capabilities registered.
*/
public Model getReasonerCapabilities();
/**
* Add a configuration description for this reasoner into a partial
* configuration specification model.
* @param configSpec a Model into which the configuration information should be placed
* @param base the Resource to which the configuration parameters should be added.
*/
public void addDescription(Model configSpec, Resource base);
/**
* Determine whether the given property is recognized and treated specially
* by this reasoner. This is a convenience packaging of a special case of getCapabilities.
* @param property the property which we want to ask the reasoner about
* @return true if the given property is handled specially by the reasoner.
*/
public boolean supportsProperty(Property property);
/**
* Return the Jena Graph Capabilties that the inference graphs generated
* by this reasoner are expected to conform to.
*/
public Capabilities getGraphCapabilities();
}