Java > Open Source Codes > com > hp > hpl > jena > ontology > daml > impl > DAMLModelImpl


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: DAMLModelImpl.java,v $
9  * Revision $Revision: 1.17 $
10  * Release status Preview-release $State: Exp $
11  *
12  * Last modified on $Date: 2005/02/23 16:59:26 $
13  * by $Author: ian_dickinson $
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.impl;
22
23
24 // Imports
25 ///////////////
26 import java.net.*;
27 import java.io.*;
28 import java.util.*;
29
30 import com.hp.hpl.jena.rdf.model.*;
31 import com.hp.hpl.jena.shared.JenaException;
32 import com.hp.hpl.jena.util.iterator.*;
33 import com.hp.hpl.jena.datatypes.*;
34 import com.hp.hpl.jena.datatypes.TypeMapper;
35 import com.hp.hpl.jena.graph.Node;
36 import com.hp.hpl.jena.ontology.daml.*;
37 import com.hp.hpl.jena.ontology.*;
38 import com.hp.hpl.jena.ontology.impl.*;
39 import com.hp.hpl.jena.vocabulary.*;
40
41
42
43 /**
44  * <p>
45  * Implementation for the DAML model interface, which is a specialisation of a Jena
46  * RDF store for the application of storing and manipulating DAML objects. The
47  * specialisations include storing a set of DAML wrapper objects that provide a
48  * convenience interface to the underlying RDF statements, and providing a set of
49  * indexes for efficiently retrieving these objects.
50  * </p>
51  *
52  * @author Ian Dickinson, HP Labs (<a HREF="mailto:Ian.Dickinson@hp.com">email</a>)
53  * @version CVS info: $Id: DAMLModelImpl.java,v 1.17 2005/02/23 16:59:26 ian_dickinson Exp $
54  */
55 public class DAMLModelImpl
56     extends OntModelImpl
57     implements DAMLModel
58 {
59     // Constants
60 //////////////////////////////////
61
62
63     // Static variables
64 //////////////////////////////////
65
66     /** Encodes which Java class to instantiate for a given DAML class */
67     protected static Object [][] DAML_CLASS_TABLE = new Object [][] {
68         // DAML class instance Corresponding java class
69 { DAML_OIL.Class, DAMLClassImpl.class },
70         { RDFS.Class, DAMLClassImpl.class },
71
72         { DAML_OIL.Restriction, DAMLRestrictionImpl.class },
73
74         { DAML_OIL.List, DAMLListImpl.class },
75
76         { DAML_OIL.Ontology, DAMLOntologyImpl.class },
77
78         { DAML_OIL.Property, DAMLPropertyImpl.class },
79         { RDF.Property, DAMLPropertyImpl.class },
80
81         { DAML_OIL.DatatypeProperty, DAMLDatatypePropertyImpl.class },
82         { DAML_OIL.ObjectProperty, DAMLObjectPropertyImpl.class },
83
84         { DAML_OIL.UniqueProperty, DAMLPropertyImpl.class },
85         { DAML_OIL.TransitiveProperty, DAMLObjectPropertyImpl.class },
86         { DAML_OIL.UnambiguousProperty, DAMLObjectPropertyImpl.class }
87     };
88
89
90     // Instance variables
91 //////////////////////////////////
92
93     /** The loader that will load DAML source documents for this store */
94     private DAMLLoader m_loader = new DAMLLoader( this );
95
96
97
98     // Constructors
99 //////////////////////////////////
100
101     /**
102      * Constructor, initialises internal data structures.
103      */
104     public DAMLModelImpl( OntModelSpec spec, Model m ) {
105         super( spec, m );
106
107         // create well-known values
108 initStore();
109     }
110
111
112
113     // External signature methods
114 //////////////////////////////////
115
116     /**
117      * <p>Create an (optionally anonymous) Ontology (big-'O') element,
118      * which holds meta-information for the ontology (small-'o').
119      * <b>N.B.</b> This does not create a new
120      * ontology, it simply makes an entry in the current model.</p>
121      *
122      * @param uri The URI for the new Ontology, or null to create an anonymous
123      * Ontology. Ideally provide the URL in which the Ontology is
124      * stored.
125      * Conventionally, in the RDF/XML serialization, we have
126      * <pre>
127      * &lt;daml:Ontology rdf:about=""&gt;
128      * </pre>
129      * The empty URIref in the above RDF/XML is known as a
130      * <Q>same document reference</Q> and expands to the
131      * URL of the current file.
132      * @return A new DAMLOntology object, which is created by adding the
133      * appropriate statements to the RDF model.
134      */
135     public DAMLOntology createDAMLOntology( String uri ) {
136         return (DAMLOntology) createOntResource( DAMLOntology.class, getProfile().ONTOLOGY(), uri );
137     }
138
139
140     /**
141      * <p>Create an (optionally anonymous) instance of the given class.</p>
142      *
143      * @param damlClass The class of the newly created DAMLInstance
144      * @param uri The URI for the new instance, or null to create an anonymous instance.
145      * @return A new DAMLInstance object.
146      */
147     public DAMLInstance createDAMLInstance( DAMLClass damlClass, String uri ) {
148         return (DAMLInstance) createOntResource( DAMLInstance.class, damlClass, uri );
149     }
150
151
152     /**
153      * <p>Create an anonymous data instance, which has the given datatype and value.</p>
154      * @param datatype A resource denoting the datatype of the new data instance object
155      * @param value The value of the data instance
156      * @return A new DAMLDataInstance object.
157      */
158     public DAMLDataInstance createDAMLDataInstance( Resource datatype, Object value ) {
159         return createDAMLDataInstance( TypeMapper.getInstance().getTypeByName( datatype.getURI() ), value );
160     }
161
162
163     /**
164      * <p>Create an anonymous data instance, which has the given datatype and value.</p>
165      * @param datatype A resource denoting the datatype of the new data instance object
166      * @param value The value of the data instance
167      * @return A new DAMLDataInstance object.
168      */
169     public DAMLDataInstance createDAMLDataInstance( RDFDatatype datatype, Object value ) {
170         Resource bNode = createResource( getResource( datatype.getURI() ) );
171         bNode.addProperty( RDF.value, createTypedLiteral( value, datatype ) );
172         return (DAMLDataInstance) bNode.as( DAMLDataInstance.class );
173     }
174
175
176     /**
177      * <p>Create an anonymous data instance, which has the given value and an appropriate datatype.</p>
178      * @param value The value of the data instance
179      * @return A new DAMLDataInstance object.
180      */
181     public DAMLDataInstance createDAMLDataInstance( Object value ) {
182         RDFDatatype datatype = TypeMapper.getInstance().getTypeByValue( value );
183         if (datatype == null) {
184             throw new JenaException( "Could not determine an appropriate datatype for value " + value );
185         }
186         else {
187             return createDAMLDataInstance( datatype, value );
188         }
189     }
190
191
192     /**
193      * <p>Create an (optionally anonymous) DAML class.</p>
194      *
195      * @param uri The URI for the new class, or null to create an anonymous class.
196      * @return A new DAMLClass object, which is created by adding the
197      * appropriate statements to the RDF model.
198      */
199     public DAMLClass createDAMLClass( String uri ) {
200         return (DAMLClass) createOntResource( DAMLClass.class, getProfile().CLASS(), uri );
201     }
202
203
204     /**
205      * <p>Create a DAML property. Note that it is recommended
206      * to use one of the more specific property classes from the new DAML release:
207      * see {@link #createDAMLObjectProperty} or {@link #createDAMLDatatypeProperty}.</p>
208      *
209      * @param uri The URI for the new property. May not be null.
210      * @return A new DAMLProperty object, which is created by adding the
211      * appropriate statements to the RDF model.
212      */
213     public DAMLProperty createDAMLProperty( String uri ) {
214         return (DAMLProperty) createOntResource( DAMLProperty.class, getProfile().PROPERTY(), uri );
215     }
216
217
218     /**
219      * <p>Create a DAML object property. An object property has ontology individuals
220      * (instances) in its range, whereas a datatype property has concrete data literals
221      * in the range.</p>
222      *
223      * @param uri The URI for the new object property. May not be null.
224      * @return A new <code>DAMLObjectProperty</code> object.
225      */
226     public DAMLObjectProperty createDAMLObjectProperty( String uri ) {
227         return (DAMLObjectProperty) createOntResource( DAMLObjectProperty.class, getProfile().OBJECT_PROPERTY(), uri );
228     }
229
230
231     /**
232      * <p>Create an (optionally anonymous) DAML datatype property. A datatype property has
233      * concrete data literals
234      * in its range, whereas an object property has ontology individuals (instances)
235      * in the range.</p>
236      *
237      * @param uri The URI for the new datatype property. May not be null.
238      * @return A new DAMLDatatypeProperty object.
239      */
240     public DAMLDatatypeProperty createDAMLDatatypeProperty( String uri ) {
241         return (DAMLDatatypeProperty) createOntResource( DAMLDatatypeProperty.class, getProfile().DATATYPE_PROPERTY(), uri );
242     }
243
244     /**
245      * <p>Create an empty DAML list.</p>
246      *
247      * @return A new empty DAMLList.
248      */
249     public DAMLList createDAMLList() {
250         return (DAMLList) getResource( DAML_OIL.nil.getURI() ).as( DAMLList.class );
251     }
252
253
254     /**
255      * <p>Create a new DAML list containing the given elements.</p>
256      *
257      * @param elements An iterator over the elements to be added to the list
258      * @return A new empty DAMLList.
259      */
260     public DAMLList createDAMLList( Iterator elements ) {
261         DAMLList l = createDAMLList();
262         if (elements.hasNext()) {
263             // put the first element on the list
264 RDFNode n = (RDFNode) elements.next();
265             l = (DAMLList) l.cons( n );
266             
267             // now add the remaining elements to the end of the list
268 while (elements.hasNext()) {
269                 l.add( (RDFNode) elements.next() );
270             }
271         }
272         
273         return l;
274     }
275
276
277     /**
278      * <p>Create a new DAML list containing the given elements.</p>
279      *
280      * @param elements An array of RDFNodes that will be the elements of the list
281      * @return A new empty DAMLList.
282      */
283     public DAMLList createDAMLList( RDFNode[] elements ) {
284         return createDAMLList( Arrays.asList( elements ).iterator() );
285     }
286
287
288     /**
289      * <p>Create an (optionally anonymous) DAML Restriction.</p>
290      *
291      * @param uri The URI for the new restriction, or null to create
292      * an anonymous restriction.
293      * @return A new DAMLRestriction object.
294      */
295     public DAMLRestriction createDAMLRestriction( String uri ) {
296         return (DAMLRestriction) createOntResource( DAMLRestriction.class, getProfile().RESTRICTION(), uri );
297     }
298
299
300     /**
301      * <p>Create a DAML Datatype representing values from some concrete domain.</p>
302      *
303      * @param uri The URI that is both the URI of this datatype value, and the identifier
304      * of the concrete domain type (e.g. as an XSD datatype).
305      * @return A new DAMLDatatype object.
306      */
307     public DAMLDatatype createDAMLDatatype( String uri ) {
308         Resource dt = getResource( uri );
309         dt.addProperty( RDF.type, DAML_OIL.Datatype );
310         return (DAMLDatatype) dt.as( DAMLDatatype.class );
311     }
312
313
314     /**
315      * <p>Create a new DAML value that is a member of the given class. The appropriate
316      * {@link DAMLCommon} sub-class will be instantiated, so, for example, if the <code>damlClass</code>
317      * is {@link DAML_OIL#Restriction}, a {@link DAMLRestriction}
318      * object will be returned. Note that if a URI is given, and a value with that
319      * URI already exists in the model, that instance will be returned instead of
320      * creating a new DAML value. This is necessary to maintain consistency of the model.</p>
321      *
322      * @param uri The URI of the new DAML value, or null for an anonymous value
323      * @param damlClass The class to which the new DAML value will belong
324      * @return An instance of a DAMLCommon value that corresponds to the given class.
325      */
326     public DAMLCommon createDAMLValue( String uri, Resource damlClass ) {
327         Class javaClass = DAMLInstance.class;
328         
329         // see if we can match the DAML class to a known type
330 for (int i = 0; i < DAML_CLASS_TABLE.length; i++) {
331             if (DAML_CLASS_TABLE[i][0].equals( damlClass )) {
332                 javaClass = (Class ) DAML_CLASS_TABLE[i][1];
333                 break;
334             }
335         }
336
337         return (DAMLCommon) createOntResource( javaClass, damlClass, uri );
338     }
339
340
341     /**
342      * <p>Answer the DAML value that corresponds to the given URI, if it exists in the
343      * model. If the URI does not match any of the resources presently in the model,
344      * null is returned.</p>
345      *
346      * @param uri The URI of the DAML resource to look for.
347      * @return An existing DAML resource from the model, matching uri, or null if
348      * no such resource is found.
349      */
350     public DAMLCommon getDAMLValue( String uri ) {
351         Node n = Node.createURI( uri );
352         if (getGraph().queryHandler().containsNode( n )) {
353             return (DAMLCommon) ((Resource) asRDFNode( n )).as( DAMLCommon.class );
354         }
355         else {
356             return null;
357         }
358     }
359
360
361     /**
362      * <p>Answer the DAML value that corresponds to the given URI, if it exists in the
363      * model. If the URI does not match any of the resources presently in the model,
364      * create a new DAML resource with the given URI and vocabulary, from the given
365      * DAML class.</p>
366      *
367      * @param uri The URI of the DAML resource to look for.
368      * @param damlClass The class of the new resource to create if no existing resource
369      * is found.
370      * @return An existing DAML resource from the model, matching uri, or a new
371      * resource if no existing resource is found.
372      */
373     public DAMLCommon getDAMLValue( String uri, DAMLClass damlClass ) {
374         DAMLCommon res = getDAMLValue( uri );
375
376         return (res == null && damlClass != null) ? createDAMLValue( uri, damlClass ) : res;
377     }
378
379
380     /**
381      * <p>Answer an iterator over all DAML classes that are presently in the model.</p>
382      *
383      * @return An iterator over all currently defined classes (including Restrictions).
384      */
385     public ExtendedIterator listDAMLClasses() {
386         return UniqueExtendedIterator.create( findByTypeAs( getProfile().CLASS(), null, DAMLClass.class ) );
387     }
388
389
390     /**
391      * <p>Answer an iterator over all DAML properties that are presently in the model.</p>
392      *
393      * @return An iterator over all currently defined properties (i.e. rdf:Property and
394      * all sub-classes).
395      */
396     public ExtendedIterator listDAMLProperties() {
397         return UniqueExtendedIterator.create( findByTypeAs( getProfile().PROPERTY(), null, DAMLProperty.class ) );
398     }
399
400
401     /**
402      * <p>Answer an iterator over all DAML instances that are presently in the model.</p>
403      *
404      * @return An iterator over all currently defined DAML instances.
405      */
406     public ExtendedIterator listDAMLInstances() {
407         return UniqueExtendedIterator.create( listIndividuals().mapWith( new Map1() {
408                         public Object map1(Object x){ return ((Resource) x).as( DAMLInstance.class );} } ) );
409     }
410
411
412     /**
413      * <p>Answer a resource from the current model with the given uri, viewed as a DAML Class.</p>
414      * @param uri The uri of the resource to fetch
415      * @return The class resource with the given URI, or null
416      */
417     public DAMLClass getDAMLClass( String uri ) {
418         Node n = Node.createURI( uri );
419         if (getGraph().queryHandler().containsNode( n )) {
420             return (DAMLClass) ((Resource) asRDFNode( n )).as( DAMLClass.class );
421         }
422         else {
423             return null;
424         }
425     }
426     
427     /**
428      * <p>Answer a resource from the current model with the given uri, viewed as a DAML Property.</p>
429      * @param uri The uri of the resource to fetch
430      * @return The property resource with the given URI, or null
431      */
432     public DAMLProperty getDAMLProperty( String uri ) {
433         Node n = Node.createURI( uri );
434         if (getGraph().queryHandler().containsNode( n )) {
435             return (DAMLProperty) ((Resource) asRDFNode( n )).as( DAMLProperty.class );
436         }
437         else {
438             return null;
439         }
440     }
441     
442     /**
443      * <p>Answer a resource from the current model with the given uri, viewed as a DAML Instance.</p>
444      * @param uri The uri of the resource to fetch
445      * @return The instance resource with the given URI, or null
446      */
447     public DAMLInstance getDAMLInstance( String uri ) {
448         Node n = Node.createURI( uri );
449         if (getGraph().queryHandler().containsNode( n )) {
450             return (DAMLInstance) ((Resource) asRDFNode( n )).as( DAMLInstance.class );
451         }
452         else {
453             return null;
454         }
455     }
456     
457
458     /**
459      * <p>Read the ontology indicated by the given uri. Note that, depending on the settings in the
460      * embedded {@link DAMLLoader}, ontology import statements embedded in this document will be
461      * processed and the ontologies fetched and loaded.</p>
462      *
463      * @param uri The URI identifying an ontology to be added.
464      * @param base The base URI for any relative names that are loaded from the source document
465      * @param lang Denotes the language the statements are represented in.
466      * @return self.
467      * @see Model#read( String, String )
468      */
469     public Model read( String uri, String base, String lang ) {
470         try {
471             URL url = new URL( uri );
472             return read( url.openStream(), base, lang );
473         }
474         catch (IOException e) {
475             throw new OntologyException( "I/O error while reading from uri " + uri );
476         }
477     }
478
479
480     /**
481      * <p>Answer a reference to the loader for this DAML model</p>
482      *
483      * @return a DAMLLoader reference
484      */
485     public DAMLLoader getLoader() {
486         return m_loader;
487     }
488
489
490     /**
491      * </p>Answer true if the most recent load operation was successful. If not,
492      * consult {@link DAMLLoader#getStatus} for details, and check error log.</p>
493      *
494      * @return True if the most recent model load was successful
495      */
496     public boolean getLoadSuccessful() {
497         return getLoader().getStatus() == DAMLLoader.STATUS_OK;
498     }
499
500
501     /**
502      * <p>Answer a reference to the XML datatype registry for this model, that can be used to
503      * map between XML data marked up using XML Schema data descriptions, and Java objects.
504      * This method has changed since Jena1, and now uses the much more clearly defined mechanism
505      * for datatypes that has been specified for RDF. This updated specification is represented
506      * in Jena2 via the <code>com.hp.hpl.jena.datatypes</code> package.
507      * </p>
508      *
509      * @return An XML datatype mapper
510      */
511     public TypeMapper getDatatypeRegistry() {
512         return TypeMapper.getInstance();
513     }
514
515
516     /**
517      * <p>Flag to control whether accessing the DAML store will take into account equivalence classes for
518      * properties and resources, using <code>daml:equivalentTo</code> and similar
519      * statements. In Jena 2, equivalence processing is delegated to the inference
520      * engine that is used to wrap the graph. Therefore, setting a flag at this API level
521      * is not useful, and this method is therefore deprecated.</p>
522      *
523      * @param useEquivalence If true, accessing properties and resources will check for
524      * equivalent values, at a cost of reduced performance.
525      * @deprecated Not useful in Jena2, since equivalence processing is handled by the inference graph.
526      */
527     public void setUseEquivalence( boolean useEquivalence ) {
528     }
529
530
531     /**
532      * <p>Answer true if the model will consider equivalence classes when accessing
533      * properties and resources. See {@link #setUseEquivalence} for details.
534      * In Jena 2, equivalence processing is delegated to the inference
535      * engine that is used to wrap the graph. Therefore, setting a flag at this API level
536      * is not useful, and this method is therefore deprecated.</p>
537      *
538      * @return True if equivalence classes are being considered.
539      * @deprecated Not useful in Jena2, since equivalence processing is handled by the inference graph.
540      */
541     public boolean getUseEquivalence() {
542         return true;
543     }
544
545
546
547
548     // Internal implementation methods
549 //////////////////////////////////
550
551     /**
552      * Initialise the store with well-known values.
553      */
554     protected void initStore() {
555     }
556
557
558     /**
559      * Answer true if the model contains the given resource.
560      *
561      * @param uri The string URI of the resource to test
562      * @return True if the resource appears in any subject, predicate or object position in the model.
563      */
564     protected boolean containsResource( String uri ) {
565         return containsResource( getResource( uri ) );
566     }
567
568
569
570     //==============================================================================
571 // Inner class definitions
572 //==============================================================================
573
574
575 }
576
577
578 /*
579     (c) Copyright 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
580     All rights reserved.
581
582     Redistribution and use in source and binary forms, with or without
583     modification, are permitted provided that the following conditions
584     are met:
585
586     1. Redistributions of source code must retain the above copyright
587        notice, this list of conditions and the following disclaimer.
588
589     2. Redistributions in binary form must reproduce the above copyright
590        notice, this list of conditions and the following disclaimer in the
591        documentation and/or other materials provided with the distribution.
592
593     3. The name of the author may not be used to endorse or promote products
594        derived from this software without specific prior written permission.
595
596     THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
597     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
598     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
599     IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
600     INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
601     NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
602     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
603     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
604     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
605     THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
606 */
607

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags