001: /******************************************************************
002: * File: Reasoner.java
003: * Created by: Dave Reynolds
004: * Created on: 09-Jan-2003
005: *
006: * (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
007: * [See end of file]
008: * $Id: Reasoner.java,v 1.20 2008/01/02 12:07:00 andy_seaborne Exp $
009: *****************************************************************/package com.hp.hpl.jena.reasoner;
010:
011: import com.hp.hpl.jena.graph.Capabilities;
012: import com.hp.hpl.jena.graph.Graph;
013: import com.hp.hpl.jena.rdf.model.*;
014:
015: /**
016: * The minimal interface to which all reasoners (or reasoner adaptors) conform.
017: * This only supports attaching the reasoner to a set of RDF graphs
018: * which represent the rules or ontologies and instance data. The actual
019: * reasoner requests are made through the InfGraph which is generated once
020: * the reasoner has been bound to a set of RDF data.
021: *
022: * @author <a href="mailto:der@hplb.hpl.hp.com">Dave Reynolds</a>
023: * @version $Revision: 1.20 $ on $Date: 2008/01/02 12:07:00 $
024: */
025: public interface Reasoner {
026:
027: /**
028: * This is most commonly used to attach an ontology (a set of tbox
029: * axioms in description logics jargon) to a reasoner. A certain amount
030: * of precomputation may be done at this time (e.g. constructing the
031: * class lattice). When the reasoner is later applied some instance data
032: * these cached precomputations may be reused.
033: * <p>In fact this call may be more general than the above
034: * description suggests. Firstly, a reasoner that supports arbitrary rules
035: * rather than ontologies may use the same method to bind the reasoner
036: * to the specific rule set (encoded in RDF). Secondly, even in the ontology
037: * case a given reasoner may not require a strict separation of tbox and
038: * abox - it may allow instance data in the tbox and terminology axioms in
039: * the abox. </p>
040: * <p>A reasoner is free to simply note this set of RDF and merge with any
041: * future RDF rather than do processing at this time. </p>
042: * @param tbox the ontology axioms or rule set encoded in RDF
043: * @return a reasoner instace which can be used to process a data graph
044: * @throws ReasonerException if the reasoner cannot be
045: * bound to a rule set in this way, for example if the underlying engine
046: * can only accept a single rule set in this way and one rule set has
047: * already been bound in of if the ruleset is illformed.
048: */
049: public Reasoner bindSchema(Graph tbox) throws ReasonerException;
050:
051: /**
052: * This is most commonly used to attach an ontology (a set of tbox
053: * axioms in description logics jargon) to a reasoner. A certain amount
054: * of precomputation may be done at this time (e.g. constructing the
055: * class lattice). When the reasoner is later applied some instance data
056: * these cached precomputations may be reused.
057: * <p>In fact this call may be more general than the above
058: * description suggests. Firstly, a reasoner that supports arbitrary rules
059: * rather than ontologies may use the same method to bind the reasoner
060: * to the specific rule set (encoded in RDF). Secondly, even in the ontology
061: * case a given reasoner may not require a strict separation of tbox and
062: * abox - it may allow instance data in the tbox and terminology axioms in
063: * the abox. </p>
064: * <p>A reasoner is free to simply note this set of RDF and merge with any
065: * future RDF rather than do processing at this time. </p>
066: * @param tbox the ontology axioms or rule set encoded in RDF
067: * @return a reasoner instace which can be used to process a data graph
068: * @throws ReasonerException if the reasoner cannot be
069: * bound to a rule set in this way, for example if the underlying engine
070: * can only accept a single rule set in this way and one rule set has
071: * already been bound in of if the ruleset is illformed.
072: */
073: public Reasoner bindSchema(Model tbox) throws ReasonerException;
074:
075: /**
076: * Attach the reasoner to a set of RDF data to process.
077: * The reasoner may already have been bound to specific rules or ontology
078: * axioms (encoded in RDF) through earlier bindRuleset calls.
079: * @param data the RDF data to be processed, some reasoners may restrict
080: * the range of RDF which is legal here (e.g. syntactic restrictions in OWL).
081: * @return an inference graph through which the data+reasoner can be queried.
082: * @throws ReasonerException if the data is ill-formed according to the
083: * constraints imposed by this reasoner.
084: */
085: public InfGraph bind(Graph data) throws ReasonerException;
086:
087: /**
088: * Switch on/off drivation logging.
089: * If set to true then the InfGraph created from the bind operation will start
090: * life with recording of derivations switched on. This is currently only of relevance
091: * to rule-based reasoners.
092: * <p>
093: * Default - false.
094: */
095: public void setDerivationLogging(boolean logOn);
096:
097: /**
098: * Set a configuration parameter for the reasoner. Parameters can identified
099: * by URI and can also be set when the Reasoner instance is created by specifying a
100: * configuration in RDF.
101: *
102: * @param parameterUri the property identifying the parameter to be changed
103: * @param value the new value for the parameter, typically this is a wrapped
104: * java object like Boolean or Integer.
105: */
106: public void setParameter(Property parameterUri, Object value);
107:
108: /**
109: * Return a description of the capabilities of this reasoner encoded in
110: * RDF. These capabilities may be static or may depend on configuration
111: * information supplied at construction time. May be null if there are
112: * no useful capabilities registered.
113: */
114: public Model getReasonerCapabilities();
115:
116: /**
117: * Add a configuration description for this reasoner into a partial
118: * configuration specification model.
119: * @param configSpec a Model into which the configuration information should be placed
120: * @param base the Resource to which the configuration parameters should be added.
121: */
122: public void addDescription(Model configSpec, Resource base);
123:
124: /**
125: * Determine whether the given property is recognized and treated specially
126: * by this reasoner. This is a convenience packaging of a special case of getCapabilities.
127: * @param property the property which we want to ask the reasoner about
128: * @return true if the given property is handled specially by the reasoner.
129: */
130: public boolean supportsProperty(Property property);
131:
132: /**
133: * Return the Jena Graph Capabilties that the inference graphs generated
134: * by this reasoner are expected to conform to.
135: */
136: public Capabilities getGraphCapabilities();
137: }
138:
139: /*
140: (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
141: All rights reserved.
142:
143: Redistribution and use in source and binary forms, with or without
144: modification, are permitted provided that the following conditions
145: are met:
146:
147: 1. Redistributions of source code must retain the above copyright
148: notice, this list of conditions and the following disclaimer.
149:
150: 2. Redistributions in binary form must reproduce the above copyright
151: notice, this list of conditions and the following disclaimer in the
152: documentation and/or other materials provided with the distribution.
153:
154: 3. The name of the author may not be used to endorse or promote products
155: derived from this software without specific prior written permission.
156:
157: THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
158: IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
159: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
160: IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
161: INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
162: NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
163: DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
164: THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
165: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
166: THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
167: */
|