DAMLModel


1   /*****************************************************************************
2    * Source code information
3    * -----------------------
4    * Original author    Ian Dickinson, HP Labs Bristol
5    * Author email       Ian.Dickinson@hp.com
6    * Package            Jena
7    * Created            5 Jan 2001
8    * Filename           $RCSfile: DAMLModel.java,v $
9    * Revision           $Revision: 1.12 $
10   * Release status     Preview-release $State: Exp $
11   *
12   * Last modified on   $Date: 2005/02/21 12:05:00 $
13   *               by   $Author: andy_seaborne $
14   *
15   * (c) Copyright 2001, 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
16   * (see footer for full conditions)
17   *****************************************************************************/
18  
19  // Package
20  ///////////////
21  package com.hp.hpl.jena.ontology.daml;
22  
23  
24  // Imports
25  ///////////////
26  import com.hp.hpl.jena.rdf.model.*;
27  import com.hp.hpl.jena.datatypes.*;
28  import com.hp.hpl.jena.datatypes.TypeMapper;
29  import com.hp.hpl.jena.ontology.OntModel;
30  import com.hp.hpl.jena.ontology.daml.impl.*;
31  import com.hp.hpl.jena.util.iterator.ExtendedIterator;
32  
33  import java.util.*;
34  
35  
36  
37  
38  /**
39   * <p>Interface that encapsulates the capability of storing and retrieving DAML
40   * ontology information from the underlying storage or persistence service. The
41   * DAML model is an extension of a single Jena RDF model, which is used to store the
42   * information from all loaded ontologies.</p>
43   *
44   * @author Ian Dickinson, HP Labs (<a HREF="mailto:Ian.Dickinson@hp.com">email</a>)
45   * @version CVS info: $Id: DAMLModel.java,v 1.12 2005/02/21 12:05:00 andy_seaborne Exp $
46   */
47  public interface DAMLModel
48      extends OntModel
49  {
50      // Constants
51      //////////////////////////////////
52  
53      // External signature methods
54      //////////////////////////////////
55  
56      /**
57       * <p>Create an (optionally anonymous) Ontology (big-'O') element, 
58       * which holds meta-information for the ontology (small-'o').  
59       * <b>N.B.</b> This does not create a new
60       * ontology, it simply makes an entry in the current model.</p>
61       *
62       * @param uri The URI for the new Ontology, or null to create an anonymous 
63       *            Ontology. Ideally provide the URL in which the Ontology is 
64       *            stored.
65       *            Conventionally, in the RDF/XML serialization, we have
66       *            <pre>
67       *             &lt;daml:Ontology rdf:about=""&gt;
68       *            </pre>
69       *            The empty URIref in the above RDF/XML is known as a
70       *            <Q>same document reference</Q> and expands to the
71       *            URL of the current file.
72       * @return A new DAMLOntology object, which is created by adding the
73       *         appropriate statements to the RDF model.
74       */
75      public DAMLOntology createDAMLOntology( String   uri );
76  
77  
78      /**
79       * <p>Create an (optionally anonymous) instance of the given class.</p>
80       *
81       * @param damlClass The class of the newly created DAMLInstance
82       * @param uri The URI for the new instance, or null to create an anonymous instance.
83       * @return A new DAMLInstance object.
84       */
85      public DAMLInstance createDAMLInstance( DAMLClass damlClass, String   uri );
86  
87  
88      /**
89       * <p>Create an anonymous data instance, which has the given datatype and value.</p>
90       * @param datatype A resource denoting the datatype of the new data instance object
91       * @param value The value of the data instance
92       * @return A new DAMLDataInstance object.
93       */
94      public DAMLDataInstance createDAMLDataInstance( Resource datatype, Object   value );
95  
96  
97      /**
98       * <p>Create an anonymous data instance, which has the given datatype and value.</p>
99       * @param datatype A resource denoting the datatype of the new data instance object
100      * @param value The value of the data instance
101      * @return A new DAMLDataInstance object.
102      */
103     public DAMLDataInstance createDAMLDataInstance( RDFDatatype datatype, Object   value );
104 
105 
106     /**
107      * <p>Create an anonymous data instance, which has the given value and an appropriate datatype.</p>
108      * @param value The value of the data instance
109      * @return A new DAMLDataInstance object.
110      */
111     public DAMLDataInstance createDAMLDataInstance( Object   value );
112         
113 
114     /**
115      * <p>Create an (optionally anonymous) DAML class.</p>
116      *
117      * @param uri The URI for the new class, or null to create an anonymous class.
118      * @return A new DAMLClass object, which is created by adding the
119      *         appropriate statements to the RDF model.
120      */
121     public DAMLClass createDAMLClass( String   uri );
122 
123 
124     /**
125      * <p>Create a DAML property. Note that it is recommended
126      * to use one of the more specific property classes from the new DAML release:
127      * see {@link #createDAMLObjectProperty} or {@link #createDAMLDatatypeProperty}.</p>
128      *
129      * @param uri The URI for the new property. May not be null.
130      * @return A new DAMLProperty object, which is created by adding the
131      *         appropriate statements to the RDF model.
132      */
133     public DAMLProperty createDAMLProperty( String   uri );
134 
135 
136     /**
137      * <p>Create a DAML object property. An object property has ontology individuals
138      * (instances) in its range, whereas a datatype property has concrete data literals
139      * in the range.</p>
140      *
141      * @param uri The URI for the new object property. May not be null.
142      * @return A new <code>DAMLObjectProperty</code> object.
143      */
144     public DAMLObjectProperty createDAMLObjectProperty( String   uri );
145 
146 
147     /**
148      * <p>Create an (optionally anonymous) DAML datatype property. A datatype property has 
149      * concrete data literals
150      * in its range, whereas an object property has ontology individuals (instances)  
151      * in the range.</p>
152      *
153      * @param uri The URI for the new datatype property. May not be null.
154      * @return A new DAMLDatatypeProperty object.
155      */
156     public DAMLDatatypeProperty createDAMLDatatypeProperty( String   uri );
157 
158 
159     /**
160      * <p>Create an empty DAML list.</p>
161      *
162      * @return A new empty DAMLList.
163      */
164     public DAMLList createDAMLList();
165 
166 
167     /**
168      * <p>Create a new DAML list containing the given elements.</p>
169      *
170      * @param elements An iterator over the elements to be added to the list
171      * @return A new empty DAMLList.
172      */
173     public DAMLList createDAMLList( Iterator elements );
174 
175 
176     /**
177      * <p>Create a new DAML list containing the given elements.</p>
178      *
179      * @param elements An array of RDFNodes that will be the elements of the list
180      * @return A new empty DAMLList.
181      */
182     public DAMLList createDAMLList( RDFNode[] elements );
183 
184 
185     /**
186      * <p>Create an (optionally anonymous) DAML Restriction.</p>
187      *
188      * @param uri The URI for the new restriction, or null to create
189      *            an anonymous restriction.
190      * @return A new DAMLRestriction object.
191      */
192     public DAMLRestriction createDAMLRestriction( String   uri );
193 
194 
195     /**
196      * <p>Create a DAML Datatype representing values from some concrete domain.</p>
197      *
198      * @param uri The URI that is both the URI of this datatype value, and the identifier
199      *             of the concrete domain type (e.g. as an XSD datatype).
200      * @return A new DAMLDatatype object.
201      */
202     public DAMLDatatype createDAMLDatatype( String   uri );
203 
204 
205     /**
206      * <p>Create a new DAML value that is a member of the given class.  The appropriate
207      * {@link DAMLCommon} sub-class will be instantiated, so, for example, if the <code>damlClass</code>
208      * is <code>daml:Restriction</code>, a {@link DAMLRestriction}
209      * object will be returned.  Note that if a URI is given, and a value with that
210      * URI already exists in the model, that instance will be returned instead of
211      * creating a new DAML value. This is necessary to maintain consistency of the model.</p>
212      *
213      * @param uri The URI of the new DAML value, or null for an anonymous value
214      * @param damlClass The class to which the new DAML value will belong
215      * @return An instance of a DAMLCommon value that corresponds to the given class.
216      */
217     public DAMLCommon createDAMLValue( String   uri, Resource damlClass );
218 
219 
220     /**
221      * <p>Answer the DAML value that corresponds to the given URI, if it exists in the
222      * model.  If the URI does not match any of the resources presently in the model,
223      * null is returned.</p>
224      *
225      * @param uri The URI of the DAML resource to look for.
226      * @return An existing DAML resource from the model, matching uri, or null if
227      *         no such resource is found.
228      */
229     public DAMLCommon getDAMLValue( String   uri );
230 
231 
232     /**
233      * <p>Answer the DAML value that corresponds to the given URI, if it exists in the
234      * model.  If the URI does not match any of the resources presently in the model,
235      * create a new DAML resource with the given URI and vocabulary, from the given
236      * DAML class.</p>
237      *
238      * @param uri The URI of the DAML resource to look for.
239      * @param damlClass The class of the new resource to create if no existing resource
240      *                  is found.
241      * @return An existing DAML resource from the model, matching uri, or a new
242      *         resource if no existing resource is found.
243      */
244     public DAMLCommon getDAMLValue( String   uri, DAMLClass damlClass );
245 
246     /**
247      * <p>Answer a resource from the current model with the given uri, viewed as a DAML Class.</p>
248      * @param uri The uri of the resource to fetch
249      * @return The class resource with the given URI, or null
250      */
251     public DAMLClass getDAMLClass( String   uri );
252     
253     /**
254      * <p>Answer a resource from the current model with the given uri, viewed as a DAML Property.</p>
255      * @param uri The uri of the resource to fetch
256      * @return The property resource with the given URI, or null
257      */
258     public DAMLProperty getDAMLProperty( String   uri );
259     
260     /**
261      * <p>Answer a resource from the current model with the given uri, viewed as a DAML Instance.</p>
262      * @param uri The uri of the resource to fetch
263      * @return The instance resource with the given URI, or null
264      */
265     public DAMLInstance getDAMLInstance( String   uri );
266     
267     /**
268      * <p>Answer an iterator over all DAML classes that are presently in the model.</p>
269      *
270      * @return An iterator over all currently defined classes (including Restrictions).
271      */
272     public ExtendedIterator listDAMLClasses();
273 
274 
275     /**
276      * <p>Answer an iterator over all DAML properties that are presently in the model.</p>
277      *
278      * @return An iterator over all currently defined properties (i.e. rdf:Property and
279      *         all sub-classes).
280      */
281     public ExtendedIterator listDAMLProperties();
282 
283 
284     /**
285      * <p>Answer an iterator over all DAML instances that are presently in the model.</p>
286      *
287      * @return An iterator over all currently defined DAML instances.
288      */
289     public ExtendedIterator listDAMLInstances();
290 
291 
292     /**
293      * <p>Answer a reference to the loader for this DAML model</p>
294      *
295      * @return a DAMLLoader reference
296      */
297     public DAMLLoader getLoader();
298 
299 
300     /**
301      * </p>Answer true if the most recent load operation was successful. If not,
302      * consult {@link DAMLLoader#getStatus} for details, and check error log.</p>
303      *
304      * @return True if the most recent model load was successful
305      */
306     public boolean getLoadSuccessful();
307 
308 
309     /**
310      * <p>Answer a reference to the XML datatype registry for this model, that can be used to
311      * map between XML data marked up using XML Schema data descriptions, and Java objects.
312      * This method has changed since Jena1, and now uses the much more clearly defined mechanism
313      * for datatypes that has been specified for RDF.  This updated specification is represented
314      * in Jena2 via the <code>com.hp.hpl.jena.datatypes</code> package.
315      * </p>
316      * <p>
317      * Note that the type mapper returned is the shared, global singleton instance of the type mapper.
318      * </p>
319      *
320      * @return An XML datatype mapper
321      */
322     public TypeMapper getDatatypeRegistry();
323 
324 
325     /**
326      * <p>Read the ontology indicated by the given uri.  Note that, depending on the settings in the
327      * embedded {@link DAMLLoader}, ontology import statements embedded in this document will be
328      * processed and the ontologies fetched and loaded.</p>
329      *
330      * @param uri The URI identifying an ontology to be added.
331      * @param base The base URI for any relative names that are loaded from the source document
332      * @param lang Denotes the language the statements are represented in.
333      * @return self.
334      * @see Model#read( String, String )
335      */
336     public Model read( String   uri, String   base, String   lang );
337 
338 
339     /**
340      * <p>Flag to control whether accessing the DAML store will take into account equivalence classes for
341      * properties and resources, using <code>daml:equivalentTo</code> and similar
342      * statements.  In Jena 2, equivalence processing is delegated to the inference
343      * engine that is used to wrap the graph.  Therefore, setting a flag at this API level
344      * is not useful, and this method is therefore deprecated.</p>
345      *
346      * @param useEquivalence If true, accessing properties and resources will check for
347      *                       equivalent values, at a cost of reduced performance.
348      * @deprecated Not useful in Jena2, since equivalence processing is handled by the inference graph.
349      */
350     public void setUseEquivalence( boolean useEquivalence );
351 
352 
353     /**
354      * <p>Answer true if the model will consider equivalence classes when accessing
355      * properties and resources.  See {@link #setUseEquivalence} for details.
356      * In Jena 2, equivalence processing is delegated to the inference
357      * engine that is used to wrap the graph.  Therefore, setting a flag at this API level
358      * is not useful, and this method is therefore deprecated.</p>
359      *
360      * @return True if equivalence classes are being considered.
361      * @deprecated Not useful in Jena2, since equivalence processing is handled by the inference graph.
362      */
363     public boolean getUseEquivalence();
364 }
365 
366 
367 /*
368     (c) Copyright 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
369     All rights reserved.
370 
371     Redistribution and use in source and binary forms, with or without
372     modification, are permitted provided that the following conditions
373     are met:
374 
375     1. Redistributions of source code must retain the above copyright
376        notice, this list of conditions and the following disclaimer.
377 
378     2. Redistributions in binary form must reproduce the above copyright
379        notice, this list of conditions and the following disclaimer in the
380        documentation and/or other materials provided with the distribution.
381 
382     3. The name of the author may not be used to endorse or promote products
383        derived from this software without specific prior written permission.
384 
385     THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
386     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
387     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
388     IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
389     INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
390     NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
391     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
392     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
393     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
394     THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
395 */
396
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags