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: Individual.java,v $
010: * Revision $Revision: 1.17 $
011: * Release status $State: Exp $
012: *
013: * Last modified on $Date: 2008/01/23 12:47:17 $
014: * by $Author: ian_dickinson $
015: *
016: * (c) Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
017: * 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 encapsulates an <i>individual</i> in an ontology, sometimes
028: * referred to as a fact or assertion, or a member of the <i>a-box</i>. In order
029: * to be recognised as an individual, rather than a generic resource,
030: * at least one <code>rdf:type</code> statement, referring to a known class,
031: * must be present in the model.
032: * </p>
033: *
034: * @author Ian Dickinson, HP Labs
035: * (<a href="mailto:Ian.Dickinson@hp.com" >email</a>)
036: * @version CVS $Id: Individual.java,v 1.17 2008/01/23 12:47:17 ian_dickinson Exp $
037: */
038: public interface Individual extends OntResource {
039: // Constants
040: //////////////////////////////////
041:
042: // External signature methods
043: //////////////////////////////////
044:
045: /**
046: * <p>Set the ontology class for this individual, replacing any
047: * existing class membership. Class membership is encoded using the
048: * <code>rdf:type</code> property. Any existing statements for the RDF type
049: * will first be removed.</p>
050: *
051: * @param cls The RDF resource denoting the new class to which this individual belongs,
052: * which will replace any existing <code>rdf:type</code> property.
053: */
054: public void setOntClass(Resource cls);
055:
056: /**
057: * <p>Add the given ontology class as one of the classes to which
058: * this individual belongs. Class membership is encoded using the
059: * <code>rdf:type</code> property. </p>
060: *
061: * @param cls An RDF resource denoting an additional class to which this individual
062: * belongs.
063: */
064: public void addOntClass(Resource cls);
065:
066: /**
067: * <p>
068: * Answer an ontology class to which this individual belongs. If the individual
069: * belongs to more than one class, which is common in ontology models using
070: * a reasoner, then the return value will be one of
071: * the possible values but <strong>it is not specified which one</strong>.
072: * In the case of multiple classes, callers <strong>should not</strong> rely on
073: * the return value being consistent, e.g. across runs, since it may
074: * depend on the underlying hash indexes in the model. </p>
075: * <p>This method considers any ontology class for the individual, not just
076: * <em>direct</em> classes. It is equivalent to <code>getOntClass(false)</code>.
077: * </p>
078: *
079: * @return A resource denoting the ontology class for this individual, or one of them if
080: * more than one is defined.
081: * @exception ConversionException if the return value is known to be an
082: * ontology class, assuming strict type checking is turned on for the underlying
083: * <code>OntModel</code>. See {@link OntModel#setStrictMode(boolean)}
084: */
085: public OntClass getOntClass();
086:
087: /**
088: * <p>
089: * Answer an ontology class to which this individual belongs. If the resource
090: * belongs to more than one class, which is common in ontology models using
091: * a reasoner, then the return value will be one of
092: * the possible values but <strong>it is not specified which one</strong>.
093: * In the case of multiple classes, callers <strong>should not</strong> rely on
094: * the return value being consistent, e.g. across runs, since it may
095: * depend on the underlying hash indexes in the model. </p>
096: *
097: * @param direct If <code>true</code>, only <em>direct</em> classes are considered.
098: * A class is a direct class of this <code>Individual</code> if and only if
099: * there is no other resource is both an <code>rdf:type</code> of this
100: * individual and a sub-class of the candidate class.
101: *
102: * @return A resource denoting the ontology class for this individual, or one of them if
103: * more than one is defined.
104: * @exception ConversionException if the return value is known to be an
105: * ontology class, assuming strict type checking is turned on for the underlying
106: * <code>OntModel</code>. See {@link OntModel#setStrictMode(boolean)}
107: */
108: public OntClass getOntClass(boolean direct);
109:
110: /**
111: * <p>
112: * Answer an iterator over the ontology classes to which this individual belongs.
113: * The members of the iterator will be {@link OntClass} objects.
114: * </p>
115: *
116: * @param direct If true, only answer those resources that are direct types
117: * of this individual, not the super-classes of the class etc.
118: * @return An iterator over the set of this individual's classes. Each member
119: * of the iteration will be an {@link OntClass}.
120: */
121: public ExtendedIterator listOntClasses(boolean direct);
122:
123: /**
124: * <p>
125: * Answer true if this individual is a member of the class denoted by the
126: * given class resource.
127: * </p>
128: *
129: * @param ontClass Denotes an ontology class to which this individual may belong
130: * @param direct If true, only consider the direct types of this individual, ignoring
131: * the super-classes of the stated types.
132: * @return True if this individual is a member of the given class, possibly taking the
133: * directness constraint into account.
134: */
135: public boolean hasOntClass(Resource ontClass, boolean direct);
136:
137: /**
138: * <p>
139: * Answer true if this individual is a member of the class denoted by the
140: * given ontology class resource. Not limited to only direct class relationships,
141: * so this is equivalent to:
142: * <code><pre>
143: * hasOntClass( ontClass, false );
144: * </pre></code>
145: * </p>
146: *
147: * @param ontClass Denotes a class to which this individual may belong
148: * @return True if this individual has the given class as one of its <code>rdf:type</code>'s.
149: */
150: public boolean hasOntClass(Resource ontClass);
151:
152: /**
153: * <p>
154: * Answer true if this individual is a member of the class denoted by the
155: * given URI.</p>
156: *
157: * @param uri Denotes the URI of a class to which this value may belong
158: * @return True if this individual has the given class as one of its <code>rdf:type</code>'s.
159: */
160: public boolean hasOntClass(String uri);
161:
162: /**
163: * <p>Attempt to remove this <code>individual</code> as a member of the
164: * given ontology class. This relationship is represented by a <code>rdf:type</code>
165: * statement in the underlying model. If this relationship was originally
166: * asserted, then removal will always succeed. However, if the <code>rdf:type</code>
167: * relationship is entailed by the action of an attached reasoner, it may not be
168: * possible to directly remove it. Callers should instead update the assertions
169: * and axioms that entail the class membership relationship, and ensure the
170: * reasoner gets chance to update the entailments.</p>
171: * <p>If this individual is not a member of the given class, the
172: * operation has no effect.</p>
173: *
174: * @param ontClass A resource denoting a class that that is to be removed from
175: * the set of classes to which this individual belongs
176: */
177: public void removeOntClass(Resource ontClass);
178:
179: }
180:
181: /*
182: (c) Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
183: All rights reserved.
184:
185: Redistribution and use in source and binary forms, with or without
186: modification, are permitted provided that the following conditions
187: are met:
188:
189: 1. Redistributions of source code must retain the above copyright
190: notice, this list of conditions and the following disclaimer.
191:
192: 2. Redistributions in binary form must reproduce the above copyright
193: notice, this list of conditions and the following disclaimer in the
194: documentation and/or other materials provided with the distribution.
195:
196: 3. The name of the author may not be used to endorse or promote products
197: derived from this software without specific prior written permission.
198:
199: THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
200: IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
201: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
202: IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
203: INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
204: NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
205: DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
206: THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
207: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
208: THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
209: */
|