001: /******************************************************************
002: * File: InfModel.java
003: * Created by: Dave Reynolds
004: * Created on: 08-May-2003
005: *
006: * (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
007: * [See end of file]
008: * $Id: InfModel.java,v 1.13 2008/01/02 12:05:46 andy_seaborne Exp $
009: *****************************************************************/package com.hp.hpl.jena.rdf.model;
010:
011: import com.hp.hpl.jena.reasoner.Reasoner;
012: import com.hp.hpl.jena.reasoner.ValidityReport;
013: import com.hp.hpl.jena.reasoner.rulesys.FBRuleReasoner;
014:
015: import java.util.Iterator;
016:
017: /**
018: * An extension to the normal Model interface that supports access to any
019: * underlying inference capability.
020: * <p>In Jena the primary use of inference is
021: * to generate additional entailments from a set of RDF data. These entailments
022: * just appear as additional RDF data in the inferred model and are accessed
023: * through the normal API. For example, if an inference engine can determine
024: * the class of a resource "foo" is "fooClass" then all Model API calls such
025: * as listStatements and getProperty should act as if the triple:
026: * <pre>
027: * foo rdf:type fooClass .
028: * </pre>
029: * were in the data. </p>
030: *
031: * <p>A few reasoner services cannot be made directly available in this way
032: * and the InfGraph extension gives access to these - specifically access to
033: * validation/consistency checking, derivation traces and find-with-posits.</p>
034: *
035: * <p>Note that this interface, and especially the interface onto ValidityReports
036: * and Derivations are not yet stable.</p>
037: *
038: * @author <a href="mailto:der@hplb.hpl.hp.com">Dave Reynolds</a>
039: * @version $Revision: 1.13 $ on $Date: 2008/01/02 12:05:46 $
040: */
041: public interface InfModel extends Model {
042:
043: /**
044: * Return the raw RDF model being processed (i.e. the argument
045: * to the Reasonder.bind call that created this InfModel).
046: */
047: public Model getRawModel();
048:
049: /**
050: * Return the Reasoner which is being used to answer queries to this graph.
051: */
052: public Reasoner getReasoner();
053:
054: /**
055: * Cause the inference model to reconsult the underlying data to take
056: * into account changes. Normally changes are made through the InfModel's add and
057: * remove calls are will be handled appropriately. However, in some cases changes
058: * are made "behind the InfModels's back" and this forces a full reconsult of
059: * the changed data.
060: */
061: public void rebind();
062:
063: /**
064: * Perform any initial processing and caching. This call is optional. Most
065: * engines either have negligable set up work or will perform an implicit
066: * "prepare" if necessary. The call is provided for those occasions where
067: * substantial preparation work is possible (e.g. running a forward chaining
068: * rule system) and where an application might wish greater control over when
069: * this prepration is done rather than just leaving to be done at first query time.
070: */
071: public void prepare();
072:
073: /**
074: * Reset any internal caches. Some systems, such as the tabled backchainer,
075: * retain information after each query. A reset will wipe this information preventing
076: * unbounded memory use at the expense of more expensive future queries. A reset
077: * does not cause the raw data to be reconsulted and so is less expensive than a rebind.
078: */
079: public void reset();
080:
081: /**
082: * Test the consistency of the underlying data. This normally tests
083: * the validity of the bound instance data against the bound
084: * schema data.
085: * <p>Logically inconsistent models will be indicated by a ValidityReport which
086: * reports isValid() as false. Additional non-fatal problems, such as uninstantiatable classes,
087: * may be reported as warnings.
088: * @return a ValidityReport structure
089: */
090: public ValidityReport validate();
091:
092: /** Find all the statements matching a pattern.
093: * <p>Return an iterator over all the statements in a model
094: * that match a pattern. The statements selected are those
095: * whose subject matches the <code>subject</code> argument,
096: * whose predicate matches the <code>predicate</code> argument
097: * and whose object matchesthe <code>object</code> argument.
098: * If an argument is <code>null</code> it matches anything.</p>
099: * <p>
100: * The s/p/o terms may refer to resources which are temporarily defined in the "posit" model.
101: * This allows one, for example, to query what resources are of type CE where CE is a
102: * class expression rather than a named class - put CE in the posit arg.</p>
103: *
104: * @return an iterator over the subjects
105: * @param subject The subject sought
106: * @param predicate The predicate sought
107: * @param object The value sought
108: */
109: public StmtIterator listStatements(Resource subject,
110: Property predicate, RDFNode object, Model posit);
111:
112: /**
113: * Switch on/off drivation logging. If this is switched on then every time an inference
114: * is a made that fact is recorded and the resulting record can be access through a later
115: * getDerivation call. This may consume a lot of space!
116: */
117: public void setDerivationLogging(boolean logOn);
118:
119: /**
120: * Return the derivation of the given statement (which should be the result of
121: * some previous list operation).
122: * Not all reasoneers will support derivations.
123: * @return an iterator over Derivation records or null if there is no derivation information
124: * available for this triple.
125: * @see com.hp.hpl.jena.reasoner.Derivation Derviation
126: */
127: public Iterator getDerivation(Statement statement);
128:
129: /**
130: * Returns a derivations model. The rule reasoners typically create a
131: * graph containing those triples added to the base graph due to rule firings.
132: * In some applications it can useful to be able to access those deductions
133: * directly, without seeing the raw data which triggered them. In particular,
134: * this allows the forward rules to be used as if they were rewrite transformation
135: * rules.
136: * @return the deductions model, if relevant for this class of inference
137: * engine or null if not.
138: */
139: public Model getDeductionsModel();
140:
141: }
142:
143: /*
144: (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
145: All rights reserved.
146:
147: Redistribution and use in source and binary forms, with or without
148: modification, are permitted provided that the following conditions
149: are met:
150:
151: 1. Redistributions of source code must retain the above copyright
152: notice, this list of conditions and the following disclaimer.
153:
154: 2. Redistributions in binary form must reproduce the above copyright
155: notice, this list of conditions and the following disclaimer in the
156: documentation and/or other materials provided with the distribution.
157:
158: 3. The name of the author may not be used to endorse or promote products
159: derived from this software without specific prior written permission.
160:
161: THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
162: IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
163: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
164: IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
165: INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
166: NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
167: DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
168: THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
169: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
170: THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
171: */
|