KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > hp > hpl > jena > reasoner > dig > DIGReasoner


1 /*****************************************************************************
2  * Source code information
3  * -----------------------
4  * Original author Ian Dickinson, HP Labs Bristol
5  * Author email Ian.Dickinson@hp.com
6  * Package Jena 2
7  * Web http://sourceforge.net/projects/jena/
8  * Created July 19th 2003
9  * Filename $RCSfile: DIGReasoner.java,v $
10  * Revision $Revision: 1.8 $
11  * Release status $State: Exp $
12  *
13  * Last modified on $Date: 2005/02/21 12:16:24 $
14  * by $Author: andy_seaborne $
15  *
16  * (c) Copyright 2001, 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
17  * [See end of file]
18  * ****************************************************************************/
19
20 // Package
21 ///////////////
22 package com.hp.hpl.jena.reasoner.dig;
23
24
25
26 // Imports
27 ///////////////
28 import java.io.*;
29
30 import org.apache.commons.logging.LogFactory;
31
32 import com.hp.hpl.jena.graph.*;
33 import com.hp.hpl.jena.ontology.*;
34 import com.hp.hpl.jena.ontology.OntModelSpec;
35 import com.hp.hpl.jena.rdf.model.*;
36 import com.hp.hpl.jena.reasoner.*;
37 import com.hp.hpl.jena.reasoner.rulesys.Util;
38 import com.hp.hpl.jena.util.FileUtils;
39 import com.hp.hpl.jena.vocabulary.ReasonerVocabulary;
40
41
42 /**
43  * <p>
44  * This reasoner is the generator of inf-graphs that can use an external DIG inference engine
45  * to perform DL reasoning tasks.
46  * </p>
47  *
48  * @author Ian Dickinson, HP Labs (<a HREF="mailto:Ian.Dickinson@hp.com">email</a>)
49  * @version Release @release@ ($Id: DIGReasoner.java,v 1.8 2005/02/21 12:16:24 andy_seaborne Exp $)
50  */
51 public class DIGReasoner
52     implements Reasoner
53 {
54
55     // Constants
56 //////////////////////////////////
57
58     // Static variables
59 //////////////////////////////////
60
61     /** The graph capabilities of the infgraphs generated by this reasoner */
62     protected Capabilities capabilities;
63
64     // Instance variables
65 //////////////////////////////////
66
67     /** A graph that contains ontology definition data (tbox) */
68     protected Graph m_tbox;
69     
70     /** Reference to the factory that created this reasoner */
71     protected ReasonerFactory m_factory;
72     
73     /** The original configuration properties, if any */
74     protected Resource m_configuration;
75     
76     /** The URL to use to connect to the external reasoner */
77     protected String JavaDoc m_extReasonerURL = DIGConnection.DEFAULT_REASONER_URL;
78     
79     /** The profile of the ontology language we're expecting */
80     protected OntModelSpec m_ontLang = getModelSpec( ProfileRegistry.OWL_LANG );
81     
82     /** The axioms that provide additional triples based on the language we're processing */
83     protected Model m_axioms = null;
84     
85     
86     // Constructors
87 //////////////////////////////////
88
89     /**
90      * <p>Construct a DIG reasoner, that can generate inference graphs binding
91      * an external DIG inference engine (e.g. Racer) to a given source graph.<p>
92      * @param tbox Optional schema to bind to this reasoner instance. Unlike other Jena
93      * reasoners, pre-binding a tbox to a DIG reasoner does not allow any
94      * efficiencies to be exploited.
95      * @param factory The reasoner factory that created this reasoner
96      * @param configuration Optional resource to which is attached configuration
97      * parameters for this reasoner
98      */
99     public DIGReasoner( Graph tbox, ReasonerFactory factory, Resource configuration ) {
100         m_tbox = tbox;
101         m_factory = factory;
102         m_configuration = configuration;
103         
104         configure( configuration );
105     }
106     
107     
108     // External signature methods
109 //////////////////////////////////
110
111     /**
112      * <p>Bind a schema, or tbox, to this DIG reasoner. This does not have any efficiency
113      * value in DIG reasoners, since we must re-load the entire tbox into each new instance
114      * of a DIG inference graph.<p>
115      * @param tbox The graph containing the ontology (tbox) data
116      * @return A new DIG reasoner containing the tbox data
117      * @see com.hp.hpl.jena.reasoner.Reasoner#bindSchema(com.hp.hpl.jena.graph.Graph)
118      */
119     public Reasoner bindSchema( Graph tbox ) {
120         return new DIGReasoner( tbox, m_factory, m_configuration );
121     }
122
123
124     /**
125      * <p>Bind a schema, or tbox, to this DIG reasoner. This does not have any efficiency
126      * value in DIG reasoners, since we must re-load the entire tbox into each new instance
127      * of a DIG inference graph.<p>
128      * @param tbox A model wrapping the graph containing the ontology (tbox) data
129      * @return A new DIG reasoner containing the tbox data
130      * @see com.hp.hpl.jena.reasoner.Reasoner#bindSchema(com.hp.hpl.jena.graph.Graph)
131      */
132     public Reasoner bindSchema(Model tbox) {
133         return bindSchema( tbox.getGraph() );
134     }
135
136
137     /**
138      * <p>Bind the given data graph to any existing t-box schema that we have, and answer
139      * the resulting inference graph.</p>
140      * @param data A graph containing the source data
141      * @return A new inference graph that will apply the DIG reasoner to the combination
142      * of the tbox and data graphs.
143      */
144     public InfGraph bind( Graph data ) {
145         return new DIGInfGraph( data, this );
146     }
147
148
149     /**
150      * Not available.
151      * @exception UnsupportedOperationException
152      */
153     public void setDerivationLogging( boolean logOn ) {
154         throw new UnsupportedOperationException JavaDoc( "DIG reasoner does not support derivation logging" );
155     }
156
157
158     /**
159      * <p>Answer the capabilities of this reasoner.</p>
160      * @return An RDF model denoting the capabilties of the reasoner
161      */
162     public Model getReasonerCapabilities() {
163         return (m_factory == null) ? null : m_factory.getCapabilities();
164     }
165     
166
167     /**
168      * <p>Add this reasoner's description to the given configuration model.</p>
169      * @param configSpec A configuration model to add this reasoner's configuration to
170      * @param base The base URI in the given model to which we will attach the configuration
171      * of this reasoner.
172      */
173     public void addDescription( Model configSpec, Resource base ) {
174         if (m_configuration != null) {
175             StmtIterator i = m_configuration.listProperties();
176             while (i.hasNext()) {
177                 Statement st = i.nextStatement();
178                 configSpec.add(base, st.getPredicate(), st.getObject());
179             }
180         }
181     }
182
183     /**
184      * Determine whether the given property is recognized and treated specially
185      * by this reasoner. This is a convenience packaging of a special case of getCapabilities.
186      * @param property the property which we want to ask the reasoner about, given as a Node since
187      * this is part of the SPI rather than API
188      * @return true if the given property is handled specially by the reasoner.
189      */
190     public boolean supportsProperty(Property property) {
191         if (m_factory == null) return false;
192         Model caps = m_factory.getCapabilities();
193         Resource root = caps.getResource(m_factory.getURI());
194         return caps.contains(root, ReasonerVocabulary.supportsP, property);
195     }
196
197
198     /**
199      * Set a configuration parameter for the reasoner. The supported parameters
200      * are:
201      * <ul>
202      * <li>PROPderivationLogging - set to true to enable recording all rule derivations</li>
203      * <li>PROPtraceOn - set to true to enable verbose trace information to be sent to the logger INFO channel</li>
204      * </ul>
205      *
206      * @param parameter the property identifying the parameter to be changed
207      * @param value the new value for the parameter, typically this is a wrapped
208      * java object like Boolean or Integer.
209      * @throws IllegalParameterException if the parameter is unknown
210      */
211     public void setParameter(Property parameter, Object JavaDoc value) {
212         if (!doSetParameter(parameter, value)) {
213             throw new IllegalParameterException( "DIGReasoner does not recognize configuration parameter " + parameter );
214         }
215         else {
216             // Record the configuration change
217 if (m_configuration == null) {
218                 Model configModel = ModelFactory.createDefaultModel();
219                 m_configuration = configModel.createResource();
220             }
221             
222             Util.updateParameter( m_configuration, parameter, value );
223         }
224     }
225
226
227     /**
228      * <p>Configure the reasoner using the properties attached to the given config
229      * resource.</p>
230      * @param configuration A configuration resource.
231      */
232     public void configure( Resource configuration ) {
233         if (configuration != null) {
234             for (StmtIterator i = configuration.listProperties(); i.hasNext(); ) {
235                 Statement s = i.nextStatement();
236                 if (!doSetParameter( s.getPredicate(), s.getObject() )) {
237                     throw new IllegalParameterException( "DIGReasoner does not recognize configuration parameter " + s.getPredicate() );
238                 }
239             }
240         }
241     }
242     
243     
244     /**
245      * <p>Answer the URL to use when connecting to the external reasoner.</p>
246      * @return The connection URL for the external reasoner as a string
247      */
248     public String JavaDoc getReasonerURL() {
249         return m_extReasonerURL;
250     }
251     
252     
253     /**
254      * <p>Answer the model spec that corresponds to the ontology model type we'll use to
255      * access the terms of the ontology according to language.</p>
256      * @return The appropriate ont model spec
257      */
258     public OntModelSpec getOntLangModelSpec() {
259         return m_ontLang;
260     }
261     
262     
263     /**
264      * <p>Answer the schema (tbox) graph for this reasoner, or null if no schema is defined.</p>
265      * @return The schema graph, or null
266      */
267     public Graph getSchema() {
268         return m_tbox;
269     }
270     
271
272     /**
273      * <p>Answer the model that contains the given axioms for this reasoner, or null if
274      * not defined.</p>
275      * @return The axioms model
276      */
277     public Model getAxioms() {
278         return m_axioms;
279     }
280     
281     /**
282      * Return the Jena Graph Capabilties that the inference graphs generated
283      * by this reasoner are expected to conform to.
284      */
285     public Capabilities getGraphCapabilities() {
286         if (capabilities == null) {
287             capabilities = new BaseInfGraph.InfCapabilities();
288         }
289         return capabilities;
290     }
291     
292     // Internal implementation methods
293 //////////////////////////////////
294
295     /**
296      * <p>Set a configuration parameter for the reasoner. The supported parameters
297      * are:</p>
298      * <ul>
299      * <li>{@link ReasonerVocabulary#EXT_REASONER_URL} the URL to use to connect to the external reasoners</li>
300      * <li>{@link ReasonerVocabulary#EXT_REASONER_ONT_LANG} the URI of the ontology language (OWL, DAML, etc) to process</li>
301      * <li>{@link ReasonerVocabulary#EXT_REASONER_AXIOMS} the URL of the ontology axioms model</li>
302      * </ul>
303      *
304      * @param parameter the property identifying the parameter to be changed
305      * @param value the new value for the parameter, typically this is a wrapped
306      * java object like Boolean or Integer.
307      * @return false if the parameter was not known
308      */
309     protected boolean doSetParameter(Property parameter, Object JavaDoc value) {
310         if (parameter.equals(ReasonerVocabulary.EXT_REASONER_URL)) {
311             m_extReasonerURL = (value instanceof Resource) ? ((Resource) value).getURI() : value.toString();
312             return true;
313         }
314         else if (parameter.equals(ReasonerVocabulary.EXT_REASONER_ONT_LANG)) {
315             String JavaDoc lang = (value instanceof Resource) ? ((Resource) value).getURI() : value.toString();
316             m_ontLang = getModelSpec( lang );
317             return true;
318         }
319         else if (parameter.equals(ReasonerVocabulary.EXT_REASONER_AXIOMS)) {
320             String JavaDoc axURL = (value instanceof Resource) ? ((Resource) value).getURI() : value.toString();
321             m_axioms = ModelFactory.createDefaultModel();
322             
323             // if a file URL, try to load it as a stream (which means we can extract from jars etc)
324 if (axURL.startsWith( "file:")) {
325                 String JavaDoc fileName = axURL.substring( 5 );
326                 InputStream in = null;
327                 try {
328                     in = FileUtils.openResourceFileAsStream( fileName );
329                     m_axioms.read( in, axURL );
330                 }
331                 catch (FileNotFoundException e) {
332                     LogFactory.getLog( getClass() ).error( "Could not open DIG axioms " + axURL );
333                 }
334                 finally {
335                     if (in != null) {
336                         try {in.close();} catch (IOException ignore) {}
337                     }
338                 }
339             }
340             else {
341                 m_axioms.read( axURL );
342             }
343             
344             return true;
345         }
346         else {
347             return false;
348         }
349     }
350     
351     
352     /**
353      * <p>Answer the ont model spec for the given ontology language</p>
354      * @param lang The ontology language as a URI
355      * @return The correspondig ont model spec to use (should be no reasoner attached)
356      */
357     protected OntModelSpec getModelSpec( String JavaDoc lang ) {
358         if (lang.equals( ProfileRegistry.OWL_LANG ) ||
359             lang.equals( ProfileRegistry.OWL_DL_LANG ) ||
360             lang.equals( ProfileRegistry.OWL_LITE_LANG )) {
361            return OntModelSpec.OWL_MEM;
362         }
363         else if (lang.equals( ProfileRegistry.DAML_LANG )) {
364             return OntModelSpec.DAML_MEM;
365         }
366         else if (lang.equals( ProfileRegistry.RDFS_LANG )) {
367             return OntModelSpec.RDFS_MEM;
368         }
369         else {
370             throw new IllegalParameterException( "DIG reasoner did not recognise ontology language " + lang );
371         }
372     }
373     
374     
375     
376     //==============================================================================
377 // Inner class definitions
378 //==============================================================================
379
380 }
381
382
383 /*
384  * (c) Copyright 2001, 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
385  * All rights reserved.
386  *
387  * Redistribution and use in source and binary forms, with or without
388  * modification, are permitted provided that the following conditions
389  * are met:
390  * 1. Redistributions of source code must retain the above copyright
391  * notice, this list of conditions and the following disclaimer.
392  * 2. Redistributions in binary form must reproduce the above copyright
393  * notice, this list of conditions and the following disclaimer in the
394  * documentation and/or other materials provided with the distribution.
395  * 3. The name of the author may not be used to endorse or promote products
396  * derived from this software without specific prior written permission.
397  *
398  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
399  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
400  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
401  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
402  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
403  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
404  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
405  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
406  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
407  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
408  */
409
Popular Tags