001: /*****************************************************************************
002: * Source code information
003: * -----------------------
004: * Original author Ian Dickinson, HP Labs Bristol
005: * Author email Ian.Dickinson@hp.com
006: * Package Jena 2
007: * Web http://sourceforge.net/projects/jena/
008: * Created 10 Feb 2003
009: * Filename $RCSfile: OntClass.java,v $
010: * Revision $Revision: 1.30 $
011: * Release status $State: Exp $
012: *
013: * Last modified on $Date: 2008/01/02 12:06:41 $
014: * by $Author: andy_seaborne $
015: *
016: * (c) Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
017: * (see footer for full conditions)
018: * ****************************************************************************/package com.hp.hpl.jena.ontology;
019:
020: // Imports
021: ///////////////
022: import com.hp.hpl.jena.rdf.model.*;
023: import com.hp.hpl.jena.util.iterator.ExtendedIterator;
024:
025: /**
026: * <p>
027: * Interface that represents an ontology node characterising a class description.
028: * </p>
029: *
030: * @author Ian Dickinson, HP Labs
031: * (<a href="mailto:Ian.Dickinson@hp.com" >email</a>)
032: * @version CVS $Id: OntClass.java,v 1.30 2008/01/02 12:06:41 andy_seaborne Exp $
033: */
034: public interface OntClass extends OntResource {
035: // Constants
036: //////////////////////////////////
037:
038: // External signature methods
039: //////////////////////////////////
040:
041: // Enumerated class constructor
042:
043: // subClassOf
044:
045: /**
046: * <p>Assert that this class is sub-class of the given class. Any existing
047: * statements for <code>subClassOf</code> will be removed.</p>
048: * @param cls The class that this class is a sub-class of
049: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
050: */
051: public void setSuperClass(Resource cls);
052:
053: /**
054: * <p>Add a super-class of this class.</p>
055: * @param cls A class that is a super-class of this class.
056: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
057: */
058: public void addSuperClass(Resource cls);
059:
060: /**
061: * <p>Answer a class that is the super-class of this class. If there is
062: * more than one such class, an arbitrary selection is made. If there
063: * is no such super-class, return null.</p>
064: * @return A super-class of this class or null
065: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()}
066: * property is not supported in the current language profile.
067: */
068: public OntClass getSuperClass();
069:
070: /**
071: * <p>Answer an iterator over all of the classes that are super-classes of
072: * this class. Each element of the iterator will be an {@link OntClass}.</p>
073: * @return An iterator over the super-classes of this class.
074: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
075: */
076: public ExtendedIterator listSuperClasses();
077:
078: /**
079: * <p>Answer an iterator over all of the classes that are super-classes of
080: * this class. Each element of the iterator will be an {@link OntClass}.
081: * See {@link #listSubClasses( boolean )} for a full explanation of the <em>direct</em>
082: * parameter.
083: * </p>
084: *
085: * @param direct If true, only answer the directly adjacent classes in the
086: * super-class relation: i.e. eliminate any class for which there is a longer route
087: * to reach that child under the super-class relation.
088: * @return an iterator over the resources representing this class's sub-classes.
089: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
090: */
091: public ExtendedIterator listSuperClasses(boolean direct);
092:
093: /**
094: * <p>Answer true if the given class is a super-class of this class.</p>
095: * @param cls A class to test.
096: * @return True if the given class is a super-class of this class.
097: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
098: */
099: public boolean hasSuperClass(Resource cls);
100:
101: /**
102: * <p>Answer true if this class has any super-class in the model. Note that
103: * when using a reasoner, all OWL classes have owl:Thing as a super-class.</p>
104: * @return True if this class has any known super-class.
105: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
106: */
107: public boolean hasSuperClass();
108:
109: /**
110: * <p>Answer true if the given class is a super-class of this class.
111: * See {@link #listSubClasses( boolean )} for a full explanation of the <em>direct</em>
112: * parameter.
113: * </p>
114: * @param cls A class to test.
115: * @param direct If true, only search the classes that are directly adjacent to this
116: * class in the class hierarchy.
117: * @return True if the given class is a super-class of this class.
118: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
119: */
120: public boolean hasSuperClass(Resource cls, boolean direct);
121:
122: /**
123: * <p>Remove the given class from the super-classes of this class. If this statement
124: * is not true of the current model, nothing happens.</p>
125: * @param cls A class to be removed from the super-classes of this class
126: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} class is not supported in the current language profile.
127: */
128: public void removeSuperClass(Resource cls);
129:
130: /**
131: * <p>Assert that this class is super-class of the given class. Any existing
132: * statements for <code>subClassOf</code> on <code>prop</code> will be removed.</p>
133: * @param cls The class that is a sub-class of this class
134: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
135: */
136: public void setSubClass(Resource cls);
137:
138: /**
139: * <p>Add a sub-class of this class.</p>
140: * @param cls A class that is a sub-class of this class.
141: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
142: */
143: public void addSubClass(Resource cls);
144:
145: /**
146: * <p>Answer a class that is the sub-class of this class. If there is
147: * more than one such class, an arbitrary selection is made. If
148: * there is no such class, return null.</p>
149: * @return A sub-class of this class or null
150: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()}
151: * property is not supported in the current language profile.
152: */
153: public OntClass getSubClass();
154:
155: /**
156: * <p>Answer an iterator over all of the classes that are declared to be sub-classes of
157: * this class. Each element of the iterator will be an {@link OntClass}.</p>
158: * @return An iterator over the sub-classes of this class.
159: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
160: */
161: public ExtendedIterator listSubClasses();
162:
163: /**
164: * <p>
165: * Answer an iterator over the classes that are declared to be sub-classes of
166: * this class. Each element of the iterator will be an {@link OntClass}. The
167: * distinguishing extra parameter for this method is the flag <code>direct</code>
168: * that allows some selectivity over the classes that appear in the iterator.
169: * Consider the following scenario:
170: * <code><pre>
171: * :B rdfs:subClassOf :A.
172: * :C rdfs:subClassOf :A.
173: * :D rdfs:subClassof :C.
174: * </pre></code>
175: * (so A has two sub-classes, B and C, and C has sub-class D). In a raw model, with
176: * no inference support, listing the sub-classes of A will answer B and C. In an
177: * inferencing model, <code>rdfs:subClassOf</code> is known to be transitive, so
178: * the sub-classes iterator will include D. The <code>direct</code> sub-classes
179: * are those members of the closure of the subClassOf relation, restricted to classes that
180: * cannot be reached by a longer route, i.e. the ones that are <em>directly</em> adjacent
181: * to the given root. Thus, the direct sub-classes of A are B and C only, and not D -
182: * even in an inferencing graph. Note that this is not the same as the entailments
183: * from the raw graph. Suppose we add to this example:
184: * <code><pre>
185: * :D rdfs:subClassof :A.
186: * </pre></code>
187: * Now, in the raw graph, A has sub-class C. But the direct sub-classes of A remain
188: * B and C, since there is a longer path A-C-D that means that D is not a direct sub-class
189: * of A. The assertion in the raw graph that A has sub-class D is essentially redundant,
190: * since this can be inferred from the closure of the graph.
191: * </p>
192: * <p>
193: * <strong>Note:</strong> This is is a change from the behaviour of Jena 1, which took a
194: * parameter <code>closed</code> to compute the closure over transitivity and equivalence
195: * of sub-classes. The closure capability in Jena2 is determined by the inference engine
196: * that is wrapped with the ontology model. The direct parameter is provided to allow,
197: * for example, a level-by-level traversal of the class hierarchy, starting at some given
198: * root. Observe that in Jena 1, passing <code>true</code> will tend to increase the number of
199: * results returned; in Jena 2 passing <code>true</code> will tend to reduce the number
200: * of results.
201: * </p>
202: *
203: * @param direct If true, only answer the directly adjacent classes in the
204: * sub-class relation: i.e. eliminate any class for which there is a longer route
205: * to reach that child under the sub-class relation.
206: * @return an iterator over the resources representing this class's sub-classes
207: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
208: */
209: public ExtendedIterator listSubClasses(boolean direct);
210:
211: /**
212: * <p>Answer true if the given class is a sub-class of this class.</p>
213: * @param cls A class to test.
214: * @return True if the given class is a sub-class of this class.
215: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
216: */
217: public boolean hasSubClass(Resource cls);
218:
219: /**
220: * <p>Answer true if this class has any sub-class in the model. Note that
221: * when using a reasoner, all OWL classes have owl:Nothing as a sub-class.</p>
222: * @return True if this class has any known sub-class.
223: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
224: */
225: public boolean hasSubClass();
226:
227: /**
228: * <p>Answer true if the given class is a sub-class of this class.
229: * See {@link #listSubClasses( boolean )} for a full explanation of the <em>direct</em>
230: * parameter.
231: * </p>
232: * @param cls A class to test.
233: * @param direct If true, only search the classes that are directly adjacent to this
234: * class in the class hierarchy.
235: * @return True if the given class is a sub-class of this class.
236: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} property is not supported in the current language profile.
237: */
238: public boolean hasSubClass(Resource cls, boolean direct);
239:
240: /**
241: * <p>Remove the given class from the sub-classes of this class. If this statement
242: * is not true of the current model, nothing happens.</p>
243: * @param cls A class to be removed from the sub-classes of this class
244: * @exception OntProfileException If the {@link Profile#SUB_CLASS_OF()} class is not supported in the current language profile.
245: */
246: public void removeSubClass(Resource cls);
247:
248: // equivalentClass
249:
250: /**
251: * <p>Assert that the given class is equivalent to this class. Any existing
252: * statements for <code>equivalentClass</code> will be removed.</p>
253: * @param cls The class that this class is a equivalent to.
254: * @exception OntProfileException If the {@link Profile#EQUIVALENT_CLASS()} property is not supported in the current language profile.
255: */
256: public void setEquivalentClass(Resource cls);
257:
258: /**
259: * <p>Add a class that is equivalent to this class.</p>
260: * @param cls A class that is equivalent to this class.
261: * @exception OntProfileException If the {@link Profile#EQUIVALENT_CLASS()} property is not supported in the current language profile.
262: */
263: public void addEquivalentClass(Resource cls);
264:
265: /**
266: * <p>Answer a class that is equivalent to this class. If there is
267: * more than one such class, an arbitrary selection is made.</p>
268: * @return A class equivalent to this class
269: * @exception OntProfileException If the {@link Profile#EQUIVALENT_CLASS()} property is not supported in the current language profile.
270: */
271: public OntClass getEquivalentClass();
272:
273: /**
274: * <p>Answer an iterator over all of the classes that are declared to be equivalent classes to
275: * this class. Each element of the iterator will be an {@link OntClass}.</p>
276: * @return An iterator over the classes equivalent to this class.
277: * @exception OntProfileException If the {@link Profile#EQUIVALENT_CLASS()} property is not supported in the current language profile.
278: */
279: public ExtendedIterator listEquivalentClasses();
280:
281: /**
282: * <p>Answer true if the given class is equivalent to this class.</p>
283: * @param cls A class to test for
284: * @return True if the given property is equivalent to this class.
285: * @exception OntProfileException If the {@link Profile#EQUIVALENT_CLASS()} property is not supported in the current language profile.
286: */
287: public boolean hasEquivalentClass(Resource cls);
288:
289: /**
290: * <p>Remove the statement that this class and the given class are
291: * equivalent. If this statement
292: * is not true of the current model, nothing happens.</p>
293: * @param cls A class that may be declared to be equivalent to this class, and which is no longer equivalent
294: * @exception OntProfileException If the {@link Profile#EQUIVALENT_CLASS()()} property is not supported in the current language profile.
295: */
296: public void removeEquivalentClass(Resource cls);
297:
298: // disjointWith
299:
300: /**
301: * <p>Assert that this class is disjoint with the given class. Any existing
302: * statements for <code>disjointWith</code> will be removed.</p>
303: * @param cls The property that this class is disjoint with.
304: * @exception OntProfileException If the {@link Profile#DISJOINT_WITH()} property is not supported in the current language profile.
305: */
306: public void setDisjointWith(Resource cls);
307:
308: /**
309: * <p>Add a class that this class is disjoint with.</p>
310: * @param cls A class that has no instances in common with this class.
311: * @exception OntProfileException If the {@link Profile#DISJOINT_WITH()} property is not supported in the current language profile.
312: */
313: public void addDisjointWith(Resource cls);
314:
315: /**
316: * <p>Answer a class with which this class is disjoint. If there is
317: * more than one such class, an arbitrary selection is made.</p>
318: * @return A class disjoint with this class
319: * @exception OntProfileException If the {@link Profile#DISJOINT_WITH()} property is not supported in the current language profile.
320: */
321: public OntClass getDisjointWith();
322:
323: /**
324: * <p>Answer an iterator over all of the classes that this class is declared to be disjoint with.
325: * Each element of the iterator will be an {@link OntClass}.</p>
326: * @return An iterator over the classes disjoint with this class.
327: * @exception OntProfileException If the {@link Profile#DISJOINT_WITH()} property is not supported in the current language profile.
328: */
329: public ExtendedIterator listDisjointWith();
330:
331: /**
332: * <p>Answer true if this class is disjoint with the given class.</p>
333: * @param cls A class to test
334: * @return True if the this class is disjoint with the the given class.
335: * @exception OntProfileException If the {@link Profile#DISJOINT_WITH()} property is not supported in the current language profile.
336: */
337: public boolean isDisjointWith(Resource cls);
338:
339: /**
340: * <p>Remove the statement that this class and the given class are
341: * disjoint. If this statement
342: * is not true of the current model, nothing happens.</p>
343: * @param cls A class that may be declared to be disjoint with this class, and which is no longer disjoint
344: * @exception OntProfileException If the {@link Profile#DISJOINT_WITH()()()} property is not supported in the current language profile.
345: */
346: public void removeDisjointWith(Resource cls);
347:
348: // other utility methods
349:
350: /**
351: * <p>Answer an iteration of the properties associated with a frame-like
352: * view of this class. Note that many cases of determining whether a
353: * property is associated with a class depends on RDFS or OWL reasoning.
354: * This method may therefore return complete results only in models that
355: * have an attached reasoner.
356: * See the
357: * <a href="../../../../../../how-to/rdf-frames.html">RDF frames how-to</a>
358: * for full details.<p>
359: * @return An iteration of the properties that are associated with this class
360: * by their domain.
361: */
362: public ExtendedIterator listDeclaredProperties();
363:
364: /**
365: * <p>Answer an iteration of the properties associated with a frame-like
366: * view of this class. Note that many cases of determining whether a
367: * property is associated with a class depends on RDFS or OWL reasoning.
368: * This method may therefore return complete results only in models that
369: * have an attached reasoner. See the
370: * <a href="../../../../../../how-to/rdf-frames.html">RDF frames how-to</a>
371: * for full details.<p>
372: * @param direct If true, restrict the properties returned to those directly
373: * associated with this class.
374: * @return An iteration of the properties that are associated with this class
375: * by their domain.
376: */
377: public ExtendedIterator listDeclaredProperties(boolean direct);
378:
379: /**
380: * <p>Answer true if the given property is one of the declared properties
381: * of this class. For details, see {@link #listDeclaredProperties(boolean)}.</p>
382: * @param p A property to test
383: * @param direct If true, only direct associations between classes and properties
384: * are considered
385: * @return True if <code>p</code> is one of the declared properties of
386: * this class
387: */
388: public boolean hasDeclaredProperty(Property p, boolean direct);
389:
390: /**
391: * <p>Answer an iterator over the individuals in the model that have this
392: * class among their types. Equivalent to {@link #listInstances(boolean)}
393: * with an argument <code>false</code>.<p>
394: *
395: * @return An iterator over those instances that have this class as one of
396: * the classes to which they belong
397: */
398: public ExtendedIterator listInstances();
399:
400: /**
401: * <p>Answer an iterator over the individuals in the model that have this
402: * class among their types, optionally excluding sub-classes of this class.<p>
403: *
404: * @param direct If true, only direct instances are counted (i.e. not instances
405: * of sub-classes of this class)
406: * @return An iterator over those instances that have this class as one of
407: * the classes to which they belong
408: */
409: public ExtendedIterator listInstances(boolean direct);
410:
411: /**
412: * <p>Answer a new individual that has this class as its <code>rdf:type</code></p>
413: * @return A new anonymous individual that is an instance of this class
414: */
415: public Individual createIndividual();
416:
417: /**
418: * <p>Answer a new individual that has this class as its <code>rdf:type</code></p>
419: * @param uri The URI of the new individual
420: * @return A new named individual that is an instance of this class
421: */
422: public Individual createIndividual(String uri);
423:
424: /**
425: * <p>Remove the given individual from the set of instances that are members of
426: * this class. This is effectively equivalent to the {@link Individual#removeOntClass} method,
427: * but invoked via the class resource rather than via the individual resource.</p>
428: * @param individual A resource denoting an individual that is no longer to be a member
429: * of this class
430: */
431: public void dropIndividual(Resource individual);
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: // access to facets
444:
445: /**
446: * <p>Answer a view of this class as an enumerated class</p>
447: * @return This class, but viewed as an EnumeratedClass facet
448: * @exception ConversionException if the class cannot be converted to an enumerated class
449: * given the language profile and the current state of the underlying model.
450: */
451: public EnumeratedClass asEnumeratedClass();
452:
453: /**
454: * <p>Answer a view of this class as a union class</p>
455: * @return This class, but viewed as a UnionClass facet
456: * @exception ConversionException if the class cannot be converted to a union class
457: * given the language profile and the current state of the underlying model.
458: */
459: public UnionClass asUnionClass();
460:
461: /**
462: * <p>Answer a view of this class as an intersection class</p>
463: * @return This class, but viewed as an IntersectionClass facet
464: * @exception ConversionException if the class cannot be converted to an intersection class
465: * given the language profile and the current state of the underlying model.
466: */
467: public IntersectionClass asIntersectionClass();
468:
469: /**
470: * <p>Answer a view of this class as a complement class</p>
471: * @return This class, but viewed as a ComplementClass facet
472: * @exception ConversionException if the class cannot be converted to a complement class
473: * given the language profile and the current state of the underlying model.
474: */
475: public ComplementClass asComplementClass();
476:
477: /**
478: * <p>Answer a view of this class as a restriction class expression</p>
479: * @return This class, but viewed as a Restriction facet
480: * @exception ConversionException if the class cannot be converted to a restriction
481: * given the language profile and the current state of the underlying model.
482: */
483: public Restriction asRestriction();
484:
485: // sub-type testing
486:
487: /**
488: * <p>Answer true if this class is an enumerated class expression</p>
489: * @return True if this is an enumerated class expression
490: */
491: public boolean isEnumeratedClass();
492:
493: /**
494: * <p>Answer true if this class is a union class expression</p>
495: * @return True if this is a union class expression
496: */
497: public boolean isUnionClass();
498:
499: /**
500: * <p>Answer true if this class is an intersection class expression</p>
501: * @return True if this is an intersection class expression
502: */
503: public boolean isIntersectionClass();
504:
505: /**
506: * <p>Answer true if this class is a complement class expression</p>
507: * @return True if this is a complement class expression
508: */
509: public boolean isComplementClass();
510:
511: /**
512: * <p>Answer true if this class is a property restriction</p>
513: * @return True if this is a restriction
514: */
515: public boolean isRestriction();
516:
517: // conversion operations
518:
519: /**
520: * <p>Answer a view of this class as an enumeration of the given individuals.</p>
521: * @param individuals A list of the individuals that will comprise the permitted values of this
522: * class converted to an enumeration
523: * @return This ontology class, converted to an enumeration of the given individuals
524: */
525: public EnumeratedClass convertToEnumeratedClass(RDFList individuals);
526:
527: /**
528: * <p>Answer a view of this class as an intersection of the given classes.</p>
529: * @param classes A list of the classes that will comprise the operands of the intersection
530: * @return This ontology class, converted to an intersection of the given classes
531: */
532: public IntersectionClass convertToIntersectionClass(RDFList classes);
533:
534: /**
535: * <p>Answer a view of this class as a union of the given classes.</p>
536: * @param classes A list of the classes that will comprise the operands of the union
537: * @return This ontology class, converted to an union of the given classes
538: */
539: public UnionClass convertToUnionClass(RDFList classes);
540:
541: /**
542: * <p>Answer a view of this class as an complement of the given class.</p>
543: * @param cls An ontology class that will be operand of the complement
544: * @return This ontology class, converted to an complement of the given class
545: */
546: public ComplementClass convertToComplementClass(Resource cls);
547:
548: /**
549: * <p>Answer a view of this class as an restriction on the given property.</p>
550: * @param prop A property this is the subject of a property restriction class expression
551: * @return This ontology class, converted to a restriction on the given property
552: */
553: public Restriction convertToRestriction(Property prop);
554:
555: }
556:
557: /*
558: (c) Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
559: All rights reserved.
560:
561: Redistribution and use in source and binary forms, with or without
562: modification, are permitted provided that the following conditions
563: are met:
564:
565: 1. Redistributions of source code must retain the above copyright
566: notice, this list of conditions and the following disclaimer.
567:
568: 2. Redistributions in binary form must reproduce the above copyright
569: notice, this list of conditions and the following disclaimer in the
570: documentation and/or other materials provided with the distribution.
571:
572: 3. The name of the author may not be used to endorse or promote products
573: derived from this software without specific prior written permission.
574:
575: THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
576: IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
577: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
578: IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
579: INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
580: NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
581: DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
582: THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
583: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
584: THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
585: */
|