InfModel


1   /******************************************************************
2    * File:        InfModel.java
3    * Created by:  Dave Reynolds
4    * Created on:  08-May-2003
5    * 
6    * (c) Copyright 2003, 2004, 2005 Hewlett-Packard Development Company, LP
7    * [See end of file]
8    * $Id: InfModel.java,v 1.9 2005/02/21 12:14:01 andy_seaborne Exp $
9    *****************************************************************/
10  package com.hp.hpl.jena.rdf.model;
11  
12  import com.hp.hpl.jena.reasoner.Reasoner;
13  import com.hp.hpl.jena.reasoner.ValidityReport;
14  import java.util.Iterator  ;
15  
16  /**
17   * An extension to the normal Model interface that supports access to any
18   * underlying inference capability. 
19   * <p>In Jena the primary use of inference is
20   * to generate additional entailments from a set of RDF data. These entailments
21   * just appear as additional RDF data in the inferred model and are accessed
22   * through the normal API. For example, if an inference engine can determine
23   * the class of a resource "foo" is "fooClass" then all Model API calls such
24   * as listStatements and getProperty should act as if the triple:
25   * <pre>
26   * foo rdf:type fooClass .
27   * </pre>
28   * were in the data. </p>
29   * 
30   * <p>A few reasoner services cannot be made directly available in this way
31   * and the InfGraph extension gives access to these - specifically access to 
32   * validation/consistency checking, derivation traces and find-with-posits.</p>
33   * 
34   * <p>Note that this interface, and especially the interface onto ValidityReports
35   * and Derivations are not yet stable.</p>
36   * 
37   * @author <a HREF="mailto:der@hplb.hpl.hp.com">Dave Reynolds</a>
38   * @version $Revision: 1.9 $ on $Date: 2005/02/21 12:14:01 $
39   */
40  public interface InfModel extends Model {
41  
42      /**
43       * Return the raw RDF model being processed (i.e. the argument
44       * to the Reasonder.bind call that created this InfModel).
45       */
46      public Model getRawModel();
47      
48      /**
49       * Return the Reasoner which is being used to answer queries to this graph.
50       */
51      public Reasoner getReasoner();
52  
53      /**
54       * Cause the inference model  to reconsult the underlying data to take
55       * into account changes. Normally changes are made through the InfModel's add and
56       * remove calls are will be handled appropriately. However, in some cases changes
57       * are made "behind the InfModels's back" and this forces a full reconsult of
58       * the changed data. 
59       */
60      public void rebind();
61      
62      /**
63       * Perform any initial processing and caching. This call is optional. Most
64       * engines either have negligable set up work or will perform an implicit
65       * "prepare" if necessary. The call is provided for those occasions where
66       * substantial preparation work is possible (e.g. running a forward chaining
67       * rule system) and where an application might wish greater control over when
68       * this prepration is done rather than just leaving to be done at first query time.
69       */
70      public void prepare();
71      
72      /**
73       * Reset any internal caches. Some systems, such as the tabled backchainer, 
74       * retain information after each query. A reset will wipe this information preventing
75       * unbounded memory use at the expense of more expensive future queries. A reset
76       * does not cause the raw data to be reconsulted and so is less expensive than a rebind.
77       */
78      public void reset();
79      
80      /**
81       * Test the consistency of the underlying data. This normally tests
82       * the validity of the bound instance data against the bound
83       * schema data. 
84       * <p>Logically inconsistent models will be indicated by a ValidityReport which
85       * reports isValid() as false. Additional non-fatal problems, such as uninstantiatable classes,
86       * may be reported as warnings.
87       * @return a ValidityReport structure
88       */
89      public ValidityReport validate();    
90      
91      /** Find all the statements matching a pattern.
92       * <p>Return an iterator over all the statements in a model
93       *  that match a pattern.  The statements selected are those
94       *  whose subject matches the <code>subject</code> argument,
95       *  whose predicate matches the <code>predicate</code> argument
96       *  and whose object matchesthe <code>object</code> argument.
97       *  If an argument is <code>null</code> it matches anything.</p>
98       * <p>
99       * The s/p/o terms may refer to resources which are temporarily defined in the "posit" model.
100      * This allows one, for example, to query what resources are of type CE where CE is a
101      * class expression rather than a named class - put CE in the posit arg.</p>
102      * 
103      * @return an iterator over the subjects
104      * @param subject   The subject sought
105      * @param predicate The predicate sought
106      * @param object    The value sought
107      */ 
108     public StmtIterator listStatements( Resource subject, Property predicate, RDFNode object, Model posit );
109     
110     /**
111      * Switch on/off drivation logging. If this is switched on then every time an inference
112      * is a made that fact is recorded and the resulting record can be access through a later
113      * getDerivation call. This may consume a lot of space!
114      */
115     public void setDerivationLogging(boolean logOn);
116    
117     /**
118      * Return the derivation of the given statement (which should be the result of
119      * some previous list operation).
120      * Not all reasoneers will support derivations.
121      * @return an iterator over Derivation records or null if there is no derivation information
122      * available for this triple.
123      * @see com.hp.hpl.jena.reasoner.Derivation Derviation
124      */
125     public Iterator   getDerivation(Statement statement);    
126     
127     /**
128      * Returns a derivations model. The rule reasoners typically create a 
129      * graph containing those triples added to the base graph due to rule firings.
130      * In some applications it can useful to be able to access those deductions
131      * directly, without seeing the raw data which triggered them. In particular,
132      * this allows the forward rules to be used as if they were rewrite transformation
133      * rules.
134      * @return the deductions model, if relevant for this class of inference
135      * engine or null if not.
136      */
137     public Model getDeductionsModel(); 
138 
139 }
140 
141 
142 /*
143     (c) Copyright 2003, 2004, 2005 Hewlett-Packard Development Company, LP
144     All rights reserved.
145 
146     Redistribution and use in source and binary forms, with or without
147     modification, are permitted provided that the following conditions
148     are met:
149 
150     1. Redistributions of source code must retain the above copyright
151        notice, this list of conditions and the following disclaimer.
152 
153     2. Redistributions in binary form must reproduce the above copyright
154        notice, this list of conditions and the following disclaimer in the
155        documentation and/or other materials provided with the distribution.
156 
157     3. The name of the author may not be used to endorse or promote products
158        derived from this software without specific prior written permission.
159 
160     THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
161     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
162     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
163     IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
164     INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
165     NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
166     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
167     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
168     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
169     THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
170 */
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags