OntClass


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            10 Feb 2003
9    * Filename           $RCSfile: OntClass.java,v $
10   * Revision           $Revision: 1.25 $
11   * Release status     $State: Exp $
12   *
13   * Last modified on   $Date: 2005/04/11 16:41:41 $
14   *               by   $Author: ian_dickinson $
15   *
16   * (c) Copyright 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
17   * (see footer for full conditions)
18   * ****************************************************************************/
19  
20  // Package
21  ///////////////
22  package com.hp.hpl.jena.ontology;
23  
24  
25  
26  
27  // Imports
28  ///////////////
29  import com.hp.hpl.jena.rdf.model.*;
30  import com.hp.hpl.jena.util.iterator.ExtendedIterator;
31  
32  
33  /**
34   * <p>
35   * Interface that represents an ontology node characterising a class description.
36   * </p>
37   *
38   * @author Ian Dickinson, HP Labs
39   *         (<a  HREF="mailto:Ian.Dickinson@hp.com" >email</a>)
40   * @version CVS $Id: OntClass.java,v 1.25 2005/04/11 16:41:41 ian_dickinson Exp $
41   */
42  public interface OntClass
43      extends OntResource
44  {
45      // Constants
46      //////////////////////////////////
47  
48  
49      // External signature methods
50      //////////////////////////////////
51  
52      // Enumerated class constructor
53  
54      // subClassOf
55  
56      /**
57       * <p>Assert that this class is sub-class of the given class. Any existing
58       * statements for <code>subClassOf</code> will be removed.</p>
59       * @param cls The class that this class is a sub-class of
60       * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
61       */
62      public void setSuperClass( Resource cls );
63  
64      /**
65       * <p>Add a super-class of this class.</p>
66       * @param cls A class that is a super-class of this class.
67       * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
68       */
69      public void addSuperClass( Resource cls );
70  
71      /**
72       * <p>Answer a class that is the super-class of this class. If there is
73       * more than one such class, an arbitrary selection is made. If there
74       * is no such super-class, return null.</p>
75       * @return A super-class of this class or null
76       * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()}
77       * property is not supported in the current language profile.
78       */
79      public OntClass getSuperClass();
80  
81      /**
82       * <p>Answer an iterator over all of the classes that are declared to be super-classes of
83       * this class. Each element of the iterator will be an {@link OntClass}.</p>
84       * @return An iterator over the super-classes of this class.
85       * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
86       */
87      public ExtendedIterator listSuperClasses();
88  
89      /**
90       * <p>Answer an iterator over all of the classes that are declared to be super-classes of
91       * this class. Each element of the iterator will be an {@link OntClass}.
92       * See {@link #listSubClasses( boolean )} for a full explanation of the <em>direct</em>
93       * parameter.
94       * </p>
95       *
96       * @param direct If true, only answer the direcly adjacent classes in the
97       * super-class relation: i&#046;e&#046; eliminate any class for which there is a longer route
98       * to reach that child under the super-class relation.
99       * @return an iterator over the resources representing this class's sub-classes.
100      * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
101      */
102     public ExtendedIterator listSuperClasses( boolean direct );
103 
104     /**
105      * <p>Answer true if the given class is a super-class of this class.</p>
106      * @param cls A class to test.
107      * @return True if the given class is a super-class of this class.
108      * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
109      */
110     public boolean hasSuperClass( Resource cls );
111 
112     /**
113      * <p>Answer true if this class has any super-class in the model. Note that
114      * when using a reasoner, all OWL classes have owl:Thing as a super-class.</p>
115      * @return True if this class has any known super-class.
116      * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
117      */
118     public boolean hasSuperClass();
119 
120     /**
121      * <p>Answer true if the given class is a super-class of this class.
122      * See {@link #listSubClasses( boolean )} for a full explanation of the <em>direct</em>
123      * parameter.
124      * </p>
125      * @param cls A class to test.
126      * @param direct If true, only search the classes that are directly adjacent to this
127      * class in the class hierarchy.
128      * @return True if the given class is a super-class of this class.
129      * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
130      */
131     public boolean hasSuperClass( Resource cls, boolean direct );
132 
133     /**
134      * <p>Remove the given class from the super-classes of this class.  If this statement
135      * is not true of the current model, nothing happens.</p>
136      * @param cls A class to be removed from the super-classes of this class
137      * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} class is not supported in the current language profile.
138      */
139     public void removeSuperClass( Resource cls);
140 
141 
142     /**
143      * <p>Assert that this class is super-class of the given class. Any existing
144      * statements for <code>subClassOf</code> on <code>prop</code> will be removed.</p>
145      * @param cls The class that is a sub-class of this class
146      * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
147      */
148     public void setSubClass( Resource cls );
149 
150     /**
151      * <p>Add a sub-class of this class.</p>
152      * @param cls A class that is a sub-class of this class.
153      * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
154      */
155     public void addSubClass( Resource cls );
156 
157     /**
158      * <p>Answer a class that is the sub-class of this class. If there is
159      * more than one such class, an arbitrary selection is made. If
160      * there is no such class, return null.</p>
161      * @return A sub-class of this class or null
162      * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()}
163      * property is not supported in the current language profile.
164      */
165     public OntClass getSubClass();
166 
167     /**
168      * <p>Answer an iterator over all of the classes that are declared to be sub-classes of
169      * this class. Each element of the iterator will be an {@link OntClass}.</p>
170      * @return An iterator over the sub-classes of this class.
171      * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
172      */
173     public ExtendedIterator listSubClasses();
174 
175     /**
176      * <p>
177      * Answer an iterator over the classes that are declared to be sub-classes of
178      * this class. Each element of the iterator will be an {@link OntClass}. The
179      * distinguishing extra parameter for this method is the flag <code>direct</code>
180      * that allows some selectivity over the classes that appear in the iterator.
181      * Consider the following scenario:
182      * <code><pre>
183      *   :B rdfs:subClassOf :A.
184      *   :C rdfs:subClassOf :A.
185      *   :D rdfs:subClassof :C.
186      * </pre></code>
187      * (so A has two sub-classes, B and C, and C has sub-class D).  In a raw model, with
188      * no inference support, listing the sub-classes of A will answer B and C.  In an
189      * inferencing model, <code>rdfs:subClassOf</code> is known to be transitive, so
190      * the sub-classes iterator will include D.  The <code>direct</code> sub-classes
191      * are those members of the closure of the subClassOf relation, restricted to classes that
192      * cannot be reached by a longer route, i.e. the ones that are <em>directly</em> adjacent
193      * to the given root.  Thus, the direct sub-classes of A are B and C only, and not D -
194      * even in an inferencing graph.  Note that this is not the same as the entailments
195      * from the raw graph. Suppose we add to this example:
196      * <code><pre>
197      *   :D rdfs:subClassof :A.
198      * </pre></code>
199      * Now, in the raw graph, A has sub-class C.  But the direct sub-classes of A remain
200      * B and C, since there is a longer path A-C-D that means that D is not a direct sub-class
201      * of A.  The assertion in the raw graph that A has sub-class D is essentially redundant,
202      * since this can be inferred from the closure of the graph.
203      * </p>
204      * <p>
205      * <strong>Note:</strong> This is is a change from the behaviour of Jena 1, which took a
206      * parameter <code>closed</code> to compute the closure over transitivity and equivalence
207      * of sub-classes.  The closure capability in Jena2 is determined by the inference engine
208      * that is wrapped with the ontology model.  The direct parameter is provided to allow,
209      * for exmaple, a level-by-level traversal of the class hierarchy, starting at some given
210      * root. Observe that in Jena 1, passing <code>true</code> will tend to increase the number of
211      * results returned; in Jena 2 passing <code>true</code> will tend to reduce the number
212      * of results.
213      * </p>
214      *
215      * @param direct If true, only answer the direcly adjacent classes in the
216      * sub-class relation: i&#046;e&#046; eliminate any class for which there is a longer route
217      * to reach that child under the sub-class relation.
218      * @return an iterator over the resources representing this class's sub-classes
219      * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
220      */
221     public ExtendedIterator listSubClasses( boolean direct );
222 
223     /**
224      * <p>Answer true if the given class is a sub-class of this class.</p>
225      * @param cls A class to test.
226      * @return True if the given class is a sub-class of this class.
227      * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
228      */
229     public boolean hasSubClass( Resource cls );
230 
231     /**
232      * <p>Answer true if this class has any sub-class in the model. Note that
233      * when using a reasoner, all OWL classes have owl:Nothing as a sub-class.</p>
234      * @return True if this class has any known sub-class.
235      * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
236      */
237     public boolean hasSubClass();
238 
239     /**
240      * <p>Answer true if the given class is a sub-class of this class.
241      * See {@link #listSubClasses( boolean )} for a full explanation of the <em>direct</em>
242      * parameter.
243      * </p>
244      * @param cls A class to test.
245      * @param direct If true, only search the classes that are directly adjacent to this
246      * class in the class hierarchy.
247      * @return True if the given class is a sub-class of this class.
248      * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
249      */
250     public boolean hasSubClass( Resource cls, boolean direct );
251 
252     /**
253      * <p>Remove the given class from the sub-classes of this class.  If this statement
254      * is not true of the current model, nothing happens.</p>
255      * @param cls A class to be removed from the sub-classes of this class
256      * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} class is not supported in the current language profile.
257      */
258     public void removeSubClass( Resource cls );
259 
260 
261     // equivalentClass
262 
263     /**
264      * <p>Assert that the given class is equivalent to this class. Any existing
265      * statements for <code>equivalentClass</code> will be removed.</p>
266      * @param cls The class that this class is a equivalent to.
267      * @exception OntProfileException If the {@link Profile#EQUIVALENT_CLASS()} property is not supported in the current language profile.
268      */
269     public void setEquivalentClass( Resource cls );
270 
271     /**
272      * <p>Add a class that is equivalent to this class.</p>
273      * @param cls A class that is equivalent to this class.
274      * @exception OntProfileException If the {@link Profile#EQUIVALENT_CLASS()} property is not supported in the current language profile.
275      */
276     public void addEquivalentClass( Resource cls );
277 
278     /**
279      * <p>Answer a class that is equivalent to this class. If there is
280      * more than one such class, an arbitrary selection is made.</p>
281      * @return A class equivalent to this class
282      * @exception OntProfileException If the {@link Profile#EQUIVALENT_CLASS()} property is not supported in the current language profile.
283      */
284     public OntClass getEquivalentClass();
285 
286     /**
287      * <p>Answer an iterator over all of the classes that are declared to be equivalent classes to
288      * this class. Each element of the iterator will be an {@link OntClass}.</p>
289      * @return An iterator over the classes equivalent to this class.
290      * @exception OntProfileException If the {@link Profile#EQUIVALENT_CLASS()} property is not supported in the current language profile.
291      */
292     public ExtendedIterator listEquivalentClasses();
293 
294     /**
295      * <p>Answer true if the given class is equivalent to this class.</p>
296      * @param cls A class to test for
297      * @return True if the given property is equivalent to this class.
298      * @exception OntProfileException If the {@link Profile#EQUIVALENT_CLASS()} property is not supported in the current language profile.
299      */
300     public boolean hasEquivalentClass( Resource cls );
301 
302     /**
303      * <p>Remove the statement that this class and the given class are
304      * equivalent.  If this statement
305      * is not true of the current model, nothing happens.</p>
306      * @param cls A class that may be declared to be equivalent to this class, and which is no longer equivalent
307      * @exception OntProfileException If the {@link Profile#EQUIVALENT_CLASS()()} property is not supported in the current language profile.
308      */
309     public void removeEquivalentClass( Resource cls );
310 
311 
312     // disjointWith
313 
314     /**
315      * <p>Assert that this class is disjoint with the given class. Any existing
316      * statements for <code>disjointWith</code> will be removed.</p>
317      * @param cls The property that this class is disjoint with.
318      * @exception OntProfileException If the {@link Profile#DISJOINT_WITH()} property is not supported in the current language profile.
319      */
320     public void setDisjointWith( Resource cls );
321 
322     /**
323      * <p>Add a class that this class is disjoint with.</p>
324      * @param cls A class that has no instances in common with this class.
325      * @exception OntProfileException If the {@link Profile#DISJOINT_WITH()} property is not supported in the current language profile.
326      */
327     public void addDisjointWith( Resource cls );
328 
329     /**
330      * <p>Answer a class with which this class is disjoint. If there is
331      * more than one such class, an arbitrary selection is made.</p>
332      * @return A class disjoint with this class
333      * @exception OntProfileException If the {@link Profile#DISJOINT_WITH()} property is not supported in the current language profile.
334      */
335     public OntClass getDisjointWith();
336 
337     /**
338      * <p>Answer an iterator over all of the classes that this class is declared to be disjoint with.
339      * Each element of the iterator will be an {@link OntClass}.</p>
340      * @return An iterator over the classes disjoint with this class.
341      * @exception OntProfileException If the {@link Profile#DISJOINT_WITH()} property is not supported in the current language profile.
342      */
343     public ExtendedIterator listDisjointWith();
344 
345     /**
346      * <p>Answer true if this class is disjoint with the given class.</p>
347      * @param cls A class to test
348      * @return True if the this class is disjoint with the the given class.
349      * @exception OntProfileException If the {@link Profile#DISJOINT_WITH()} property is not supported in the current language profile.
350      */
351     public boolean isDisjointWith( Resource cls );
352 
353     /**
354      * <p>Remove the statement that this class and the given class are
355      * disjoint.  If this statement
356      * is not true of the current model, nothing happens.</p>
357      * @param cls A class that may be declared to be disjoint with this class, and which is no longer disjoint
358      * @exception OntProfileException If the {@link Profile#DISJOINT_WITH()()()} property is not supported in the current language profile.
359      */
360     public void removeDisjointWith( Resource cls );
361 
362 
363     // other utility methods
364 
365     /**
366      * <p>Answer an iteration of the properties associated with a frame-like
367      * view of this class. Note that many cases of determining whether a
368      * property is associated with a class depends on RDFS or OWL reasoning.
369      * This method may therefore return complete results only in models that
370      * have an attached reasoner.
371      * See the
372      * <a HREF="../../../../../../how-to/rdf-frames.html">RDF frames how-to</a>
373      * for full details.<p>
374      * @return An iteration of the properties that are associated with this class
375      * by their domain.
376      */
377     public ExtendedIterator listDeclaredProperties();
378 
379 
380     /**
381      * <p>Answer an iteration of the properties associated with a frame-like
382      * view of this class. Note that many cases of determining whether a
383      * property is associated with a class depends on RDFS or OWL reasoning.
384      * This method may therefore return complete results only in models that
385      * have an attached reasoner. See the
386      * <a HREF="../../../../../../how-to/rdf-frames.html">RDF frames how-to</a>
387      * for full details.<p>
388      * @param direct If true, restrict the properties returned to those directly
389      * associated with this class.
390      * @return An iteration of the properties that are associated with this class
391      * by their domain.
392      */
393     public ExtendedIterator listDeclaredProperties( boolean direct );
394 
395 
396     /**
397      * <p>Answer true if the given property is one of the declared properties
398      * of this class. For details, see {@link #listDeclaredProperties(boolean)}.</p>
399      * @param p A property to test
400      * @param direct If true, only direct associations between classes and properties
401      * are considered
402      * @return True if <code>p</code> is one of the declared properties of
403      * this class
404      */
405     public boolean hasDeclaredProperty( Property p, boolean direct );
406 
407 
408     /**
409      * <p>Answer an iterator over the individuals in the model that have this
410      * class among their types.<p>
411      *
412      * @return An iterator over those instances that have this class as one of
413      *         the classes to which they belong
414      */
415     public ExtendedIterator listInstances();
416 
417 
418     /**
419      * <p>Answer a new individual that has this class as its <code>rdf:type</code></p>
420      * @return A new anonymous individual that is an instance of this class
421      */
422     public Individual createIndividual();
423 
424 
425     /**
426      * <p>Answer a new individual that has this class as its <code>rdf:type</code></p>
427      * @param uri The URI of the new individual
428      * @return A new named individual that is an instance of this class
429      */
430     public Individual createIndividual( String   uri );
431 
432 
433     /**
434      * <p>Answer true if this class is one of the roots of the local class hierarchy.
435      * This will be true if either (i) this class has <code>owl:Thing</code>
436      * (or <code>daml:Thing</code>) as a direct super-class, or (ii) it has
437      * no declared super-classes (including anonymous class expressions).</p>
438      * @return True if this class is the root of the class hierarchy in the
439      * model it is attached to
440      */
441     public boolean isHierarchyRoot();
442 
443 
444     // access to facets
445 
446     /**
447      * <p>Answer a view of this class as an enumerated class</p>
448      * @return This class, but viewed as an EnumeratedClass facet
449      * @exception ConversionException if the class cannot be converted to an enumerated class
450      * given the lanuage profile and the current state of the underlying model.
451      */
452     public EnumeratedClass asEnumeratedClass();
453 
454     /**
455      * <p>Answer a view of this class as a union class</p>
456      * @return This class, but viewed as a UnionClass facet
457      * @exception ConversionException if the class cannot be converted to a union class
458      * given the lanuage profile and the current state of the underlying model.
459      */
460     public UnionClass asUnionClass();
461 
462     /**
463      * <p>Answer a view of this class as an intersection class</p>
464      * @return This class, but viewed as an IntersectionClass facet
465      * @exception ConversionException if the class cannot be converted to an intersection class
466      * given the lanuage profile and the current state of the underlying model.
467      */
468     public IntersectionClass asIntersectionClass();
469 
470     /**
471      * <p>Answer a view of this class as a complement class</p>
472      * @return This class, but viewed as a ComplementClass facet
473      * @exception ConversionException if the class cannot be converted to a complement class
474      * given the lanuage profile and the current state of the underlying model.
475      */
476     public ComplementClass asComplementClass();
477 
478     /**
479      * <p>Answer a view of this class as a restriction class expression</p>
480      * @return This class, but viewed as a Restriction facet
481      * @exception ConversionException if the class cannot be converted to a restriction
482      * given the lanuage profile and the current state of the underlying model.
483      */
484     public Restriction asRestriction();
485 
486     // sub-type testing
487 
488     /**
489      * <p>Answer true if this class is an enumerated class expression</p>
490      * @return True if this is an enumerated class expression
491      */
492     public boolean isEnumeratedClass();
493 
494     /**
495      * <p>Answer true if this class is a union class expression</p>
496      * @return True if this is a union class expression
497      */
498     public boolean isUnionClass();
499 
500     /**
501      * <p>Answer true if this class is an intersection class expression</p>
502      * @return True if this is an intersection class expression
503      */
504     public boolean isIntersectionClass();
505 
506     /**
507      * <p>Answer true if this class is a complement class expression</p>
508      * @return True if this is a complement class expression
509      */
510     public boolean isComplementClass();
511 
512     /**
513      * <p>Answer true if this class is a property restriction</p>
514      * @return True if this is a restriction
515      */
516     public boolean isRestriction();
517 
518 
519     // conversion operations
520 
521     /**
522      * <p>Answer a view of this class as an enumeration of the given individuals.</p>
523      * @param individuals A list of the individuals that will comprise the permitted values of this
524      * class converted to an enumeration
525      * @return This ontology class, converted to an enumeration of the given individuals
526      */
527     public EnumeratedClass convertToEnumeratedClass( RDFList individuals );
528 
529     /**
530      * <p>Answer a view of this class as an intersection of the given classes.</p>
531      * @param classes A list of the classes that will comprise the operands of the intersection
532      * @return This ontology class, converted to an intersection of the given classes
533      */
534     public IntersectionClass convertToIntersectionClass( RDFList classes );
535 
536     /**
537      * <p>Answer a view of this class as a union of the given classes.</p>
538      * @param classes A list of the classes that will comprise the operands of the union
539      * @return This ontology class, converted to an union of the given classes
540      */
541     public UnionClass convertToUnionClass( RDFList classes );
542 
543     /**
544      * <p>Answer a view of this class as an complement of the given class.</p>
545      * @param cls An ontology classs that will be operand of the complement
546      * @return This ontology class, converted to an complement of the given class
547      */
548     public ComplementClass convertToComplementClass( Resource cls );
549 
550     /**
551      * <p>Answer a view of this class as an resriction on the given property.</p>
552      * @param prop A property this is the subject of a property restriction class expression
553      * @return This ontology class, converted to a restriction on the given property
554      */
555     public Restriction convertToRestriction( Property prop );
556 
557 
558 }
559 
560 
561 /*
562     (c) Copyright 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
563     All rights reserved.
564 
565     Redistribution and use in source and binary forms, with or without
566     modification, are permitted provided that the following conditions
567     are met:
568 
569     1. Redistributions of source code must retain the above copyright
570        notice, this list of conditions and the following disclaimer.
571 
572     2. Redistributions in binary form must reproduce the above copyright
573        notice, this list of conditions and the following disclaimer in the
574        documentation and/or other materials provided with the distribution.
575 
576     3. The name of the author may not be used to endorse or promote products
577        derived from this software without specific prior written permission.
578 
579     THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
580     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
581     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
582     IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
583     INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
584     NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
585     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
586     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
587     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
588     THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
589 */
590 
591
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags