001: /******************************************************************
002: * File: InfGraph.java
003: * Created by: Dave Reynolds
004: * Created on: 10-Jan-2003
005: *
006: * (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
007: * [See end of file]
008: * $Id: InfGraph.java,v 1.14 2008/01/02 12:07:00 andy_seaborne Exp $
009: *****************************************************************/package com.hp.hpl.jena.reasoner;
010:
011: import com.hp.hpl.jena.graph.Graph;
012: import com.hp.hpl.jena.graph.Node;
013: import com.hp.hpl.jena.graph.Triple;
014: import com.hp.hpl.jena.util.iterator.ExtendedIterator;
015: import java.util.Iterator;
016:
017: /**
018: * Extends the Graph interface to give additional means to query an inferred
019: * graph. Many entailments from the raw data are made to appear as if they
020: * are extract triples in the inferred graph and so appear through the
021: * normal Graph.find interface.
022: *
023: * However, here are two extensions required. Firstly, the ability to
024: * ask about global properties of the whole graph (e.g. consistency). Secondly,
025: * the ability to temporarily construct expressions (encoded in RDF) which
026: * form more complex queries.
027: *
028: * @author <a href="mailto:der@hplb.hpl.hp.com">Dave Reynolds</a>
029: * @version $Revision: 1.14 $ on $Date: 2008/01/02 12:07:00 $
030: */
031: public interface InfGraph extends Graph {
032:
033: /**
034: * Return the raw RDF data Graph being processed (i.e. the argument
035: * to the Reasonder.bind call that created this InfGraph).
036: */
037: public Graph getRawGraph();
038:
039: /**
040: * Return the Reasoner which is being used to answer queries to this graph.
041: */
042: public Reasoner getReasoner();
043:
044: /**
045: * Replace the underlying data graph for this inference graph and start any
046: * inferences over again. This is primarily using in setting up ontology imports
047: * processing to allow an imports multiunion graph to be inserted between the
048: * inference graph and the raw data, before processing.
049: * @param data the new raw data graph
050: */
051: public void rebind(Graph data);
052:
053: /**
054: * Cause the inference graph to reconsult the underlying graph to take
055: * into account changes. Normally changes are made through the InfGraph's add and
056: * remove calls are will be handled appropriately. However, in some cases changes
057: * are made "behind the InfGraph's back" and this forces a full reconsult of
058: * the changed data.
059: */
060: public void rebind();
061:
062: /**
063: * Perform any initial processing and caching. This call is optional. Most
064: * engines either have negligable set up work or will perform an implicit
065: * "prepare" if necessary. The call is provided for those occasions where
066: * substantial preparation work is possible (e.g. running a forward chaining
067: * rule system) and where an application might wish greater control over when
068: * this prepration is done.
069: */
070: public void prepare();
071:
072: /**
073: * Reset any internal caches. Some systems, such as the tabled backchainer,
074: * retain information after each query. A reset will wipe this information preventing
075: * unbounded memory use at the expense of more expensive future queries. A reset
076: * does not cause the raw data to be reconsulted and so is less expensive than a rebind.
077: */
078: public void reset();
079:
080: /**
081: * Test a global boolean property of the graph. This might included
082: * properties like consistency, OWLSyntacticValidity etc.
083: * It remains to be seen what level of generality is needed here. We could
084: * replace this by a small number of specific tests for common concepts.
085: * @param property the URI of the property to be tested
086: * @return a Node giving the value of the global property, this may
087: * be a boolean literal, some other literal value (e.g. a size).
088: */
089: public Node getGlobalProperty(Node property);
090:
091: /**
092: * A convenience version of getGlobalProperty which can only return
093: * a boolean result.
094: */
095: public boolean testGlobalProperty(Node property);
096:
097: /**
098: * Test the consistency of the bound data. This normally tests
099: * the validity of the bound instance data against the bound
100: * schema data.
101: * @return a ValidityReport structure
102: */
103: public ValidityReport validate();
104:
105: /**
106: * An extension of the Graph.find interface which allows the caller to
107: * encode complex expressions in RDF and then refer to those expressions
108: * within the query triple. For example, one might encode a class expression
109: * and then ask if there are any instances of this class expression in the
110: * InfGraph.
111: * @param subject the subject Node of the query triple, may be a Node in
112: * the graph or a node in the parameter micro-graph or null
113: * @param property the property to be retrieved or null
114: * @param object the object Node of the query triple, may be a Node in
115: * the graph or a node in the parameter micro-graph.
116: * @param param a small graph encoding an expression which the subject and/or
117: * object nodes refer.
118: */
119: public ExtendedIterator find(Node subject, Node property,
120: 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, 2006, 2007, 2008 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: */
|