InfGraph


1   /******************************************************************
2    * File:        InfGraph.java
3    * Created by:  Dave Reynolds
4    * Created on:  10-Jan-2003
5    * 
6    * (c) Copyright 2003, 2004, 2005 Hewlett-Packard Development Company, LP
7    * [See end of file]
8    * $Id: InfGraph.java,v 1.11 2005/02/21 12:16:14 andy_seaborne Exp $
9    *****************************************************************/
10  package com.hp.hpl.jena.reasoner;
11  
12  import com.hp.hpl.jena.graph.Graph;
13  import com.hp.hpl.jena.graph.Node;
14  import com.hp.hpl.jena.graph.Triple;
15  import com.hp.hpl.jena.util.iterator.ExtendedIterator;
16  import java.util.Iterator  ;
17  
18  /**
19   * Extends the Graph interface to give additional means to query an inferred
20   * graph. Many entailments from the raw data are made to appear as if they
21   * are extract triples in the inferred graph and so appear through the
22   * normal Graph.find interface. 
23   * 
24   * However, here are two extensions required. Firstly, the ability to
25   * ask about global properties of the whole graph (e.g. consistency). Secondly,
26   * the ability to temporarily construct expressions (encoded in RDF) which 
27   * form more complex queries.
28   * 
29   * @author <a HREF="mailto:der@hplb.hpl.hp.com">Dave Reynolds</a>
30   * @version $Revision: 1.11 $ on $Date: 2005/02/21 12:16:14 $
31   */
32  public interface InfGraph extends Graph {
33  
34      /**
35       * Return the raw RDF data Graph being processed (i.e. the argument
36       * to the Reasonder.bind call that created this InfGraph).
37       */
38      public Graph getRawGraph();
39      
40      /**
41       * Return the Reasoner which is being used to answer queries to this graph.
42       */
43      public Reasoner getReasoner();
44  
45      /**
46       * Replace the underlying data graph for this inference graph and start any
47       * inferences over again. This is primarily using in setting up ontology imports
48       * processing to allow an imports multiunion graph to be inserted between the
49       * inference graph and the raw data, before processing.
50       * @param data the new raw data graph
51       */
52      public void rebind(Graph data);
53      
54      /**
55       * Cause the inference graph to reconsult the underlying graph to take
56       * into account changes. Normally changes are made through the InfGraph's add and
57       * remove calls are will be handled appropriately. However, in some cases changes
58       * are made "behind the InfGraph's back" and this forces a full reconsult of
59       * the changed data. 
60       */
61      public void rebind();
62      
63      /**
64       * Perform any initial processing and caching. This call is optional. Most
65       * engines either have negligable set up work or will perform an implicit
66       * "prepare" if necessary. The call is provided for those occasions where
67       * substantial preparation work is possible (e.g. running a forward chaining
68       * rule system) and where an application might wish greater control over when
69       * this prepration is done.
70       */
71      public void prepare();
72      
73      /**
74       * Reset any internal caches. Some systems, such as the tabled backchainer, 
75       * retain information after each query. A reset will wipe this information preventing
76       * unbounded memory use at the expense of more expensive future queries. A reset
77       * does not cause the raw data to be reconsulted and so is less expensive than a rebind.
78       */
79      public void reset();
80      
81      /**
82       * Test a global boolean property of the graph. This might included
83       * properties like consistency, OWLSyntacticValidity etc.
84       * It remains to be seen what level of generality is needed here. We could
85       * replace this by a small number of specific tests for common concepts.
86       * @param property the URI of the property to be tested 
87       * @return a Node giving the value of the global property, this may 
88       * be a boolean literal, some other literal value (e.g. a size).
89       */    
90      public Node getGlobalProperty(Node property);
91      
92      /**
93       * A convenience version of getGlobalProperty which can only return
94       * a boolean result.
95       */
96      public boolean testGlobalProperty(Node property);
97      
98      /**
99       * Test the consistency of the bound data. This normally tests
100      * the validity of the bound instance data against the bound
101      * schema data. 
102      * @return a ValidityReport structure
103      */
104     public ValidityReport validate();
105     
106     /**
107      * An extension of the Graph.find interface which allows the caller to 
108      * encode complex expressions in RDF and then refer to those expressions
109      * within the query triple. For example, one might encode a class expression
110      * and then ask if there are any instances of this class expression in the
111      * InfGraph.
112      * @param subject the subject Node of the query triple, may be a Node in 
113      * the graph or a node in the parameter micro-graph or null
114      * @param property the property to be retrieved or null
115      * @param object the object Node of the query triple, may be a Node in 
116      * the graph or a node in the parameter micro-graph.    
117      * @param param a small graph encoding an expression which the subject and/or
118      * object nodes refer.
119      */
120     public ExtendedIterator find(Node subject, Node property, Node object, Graph param);
121     
122     /**
123      * Switch on/off drivation logging
124      */
125     public void setDerivationLogging(boolean logOn);
126    
127     /**
128      * Return the derivation of the given triple (which is the result of
129      * some previous find operation).
130      * Not all reasoneers will support derivations.
131      * @return an iterator over Derivation records or null if there is no derivation information
132      * available for this triple.
133      */
134     public Iterator getDerivation(Triple triple);
135     
136     /**
137      * Returns a derivations graph. The rule reasoners typically create a 
138      * graph containing those triples added to the base graph due to rule firings.
139      * In some applications it can useful to be able to access those deductions
140      * directly, without seeing the raw data which triggered them. In particular,
141      * this allows the forward rules to be used as if they were rewrite transformation
142      * rules.
143      * @return the deductions graph, if relevant for this class of inference
144      * engine or null if not.
145      */
146     public Graph getDeductionsGraph(); 
147 }
148 
149 /*
150     (c) Copyright 2003, 2004, 2005 Hewlett-Packard Development Company, LP
151     All rights reserved.
152 
153     Redistribution and use in source and binary forms, with or without
154     modification, are permitted provided that the following conditions
155     are met:
156 
157     1. Redistributions of source code must retain the above copyright
158        notice, this list of conditions and the following disclaimer.
159 
160     2. Redistributions in binary form must reproduce the above copyright
161        notice, this list of conditions and the following disclaimer in the
162        documentation and/or other materials provided with the distribution.
163 
164     3. The name of the author may not be used to endorse or promote products
165        derived from this software without specific prior written permission.
166 
167     THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
168     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
169     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
170     IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
171     INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
172     NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
173     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
174     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
175     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
176     THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
177 */
178 
179
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags