OInstance.java
001 /*
002  *  OInstance.java
003  *
004  *  Niraj Aswani, 09/March/07
005  *
006  *  $Id: OInstance.java 15004 2012-01-11 06:00:14Z markagreenwood $
007  */
008 package gate.creole.ontology;
009 
010 import java.util.List;
011 import java.util.Set;
012 
013 /**
014  * OInstance (Ontology Instance) represents an instance in the
015  * ontology/knowledge base. The interface provides various methods,
016  * including and not limited to, obtain a list of classes the instance
017  * belongs to, and various methods to add various property values on it.
018  
019  @author Niraj Aswani
020  @author Johann Petrak
021  
022  */
023 public interface OInstance extends OResource {
024   /**
025    * Gets the set of classes this instance belongs to.
026    
027    @param closure either OntologyConstants.DIRECT_CLOSURE or
028    *          OntologyConstants.TRANSITIVE_CLOSURE.
029    @return a set of {@link OClass} objects.
030    */
031   @Deprecated
032   public Set<OClass> getOClasses(byte closure);
033 
034   public Set<OClass> getOClasses(OConstants.Closure closure);
035 
036   /**
037    * Make this individual an instance of another class. This does nothing
038    * if the individual is already an instance of the given class. Note
039    * that this cann lead to inconsistencies, e.g. if this class is disjunct
040    * with a class of which the individual is already an instance.
041    *
042    @param theClass - the OClass object for the class of which the individual
043    * should be an instance.
044    */
045   public void addOClass(OClass theClass);
046 
047   /**
048    * Checks whether the instance is an instance of the provided class.
049    
050    @param aClass
051    @param closure either OntologyConstants.DIRECT_CLOSURE or
052    *          OntologyConstants.TRANSITIVE_CLOSURE.
053    @return true, if the instance is indded an instance of the provided
054    *         class, otherwise - false.
055    */
056   @Deprecated
057   public boolean isInstanceOf(OClass aClass, byte closure);
058 
059   public boolean isInstanceOf(OClass aClass, OConstants.Closure closure);
060 
061   /**
062    * Sets the instance being different from the provided instance.
063    */
064   public void setDifferentFrom(OInstance theInstance);
065 
066   /**
067    * Returns a set of {@link OInstance} objects which are explicitly
068    * specified as being different from the current instance.
069    
070    @return a Set of OInstances
071    */
072   public Set<OInstance> getDifferentInstances();
073 
074   /**
075    * Checks whether the instance is different from the given instance
076    
077    @param theInstance
078    */
079   public boolean isDifferentFrom(OInstance theInstance);
080 
081   /**
082    * Sets the instance being same as the provided instance.
083    
084    @param theIndividual
085    */
086   public void setSameInstanceAs(OInstance theIndividual);
087 
088   /**
089    * Returns a set of {@link OInstance} objects which are explicitly
090    * specified as being same as the current instance.
091    */
092   public Set<OInstance> getSameInstance();
093 
094   /**
095    * Checks whether the instance is same as the given instance
096    */
097   public boolean isSameInstanceAs(OInstance theInstance);
098 
099   // ******************
100   // RDF Properties
101   // *****************
102 
103   /**
104    * Adds the value for the given RDFProperty.
105    @throws InvalidValueException This exception is thrown when a value
106    *           is not compatible with the specified property's range.
107    @deprecated this throws an exception in the new implementation
108    */
109   @Deprecated
110   public void addRDFPropertyValue(RDFProperty aProperty, OResource value)
111           throws InvalidValueException;
112 
113   /**
114    * Remove the provided value for the given property.
115    @deprecated
116    */
117   @Deprecated
118   public void removeRDFPropertyValue(RDFProperty aProperty, OResource value);
119 
120   /**
121    * Gets a list of values for the given Property.
122    
123    @param aProperty
124    @return {@link List} of {@link OResource}.
125    @deprecated 
126    */
127   @Deprecated
128   public List<OResource> getRDFPropertyValues(RDFProperty aProperty);
129 
130   public List<OValue> getRDFPropertyOValues(RDFProperty aProperty);
131 
132   /**
133    * This method returns the RDF properties set on this resource.
134    */
135   public Set<RDFProperty> getSetRDFProperties();
136 
137   /**
138    * Checks if the resource has the provided annotation property set on it with the specified value.
139    @deprecated
140    */
141   @Deprecated
142   public boolean hasRDFPropertyWithValue(RDFProperty aProperty, OResource aResource);
143 
144   
145   /**
146    * Removes all property values set for the current property.
147    @deprecated 
148    */
149   @Deprecated
150   public void removeRDFPropertyValues(RDFProperty aProperty);
151 
152   // ******************
153   // DataType Properties
154   // *****************
155 
156   /**
157    * Adds the value for the given Property.
158    @throws InvalidValueException This exception is thrown when a value
159    *           is not compatible with the specified property's range.
160    */
161   public void addDatatypePropertyValue(DatatypeProperty aProperty, Literal value)
162           throws InvalidValueException;
163 
164   /**
165    * Remove the provided value for the given property.
166    */
167   public void removeDatatypePropertyValue(DatatypeProperty aProperty,
168           Literal value);
169 
170   /**
171    * Gets a list of values for the given Property.
172    @return {@link List} of {@link Literal}.
173    */
174   public List<Literal> getDatatypePropertyValues(DatatypeProperty aProperty);
175 
176   /**
177    * Removes all property values set for the current property.
178    */
179   public void removeDatatypePropertyValues(DatatypeProperty aProperty);
180 
181   // ******************
182   // Object, Symmetric and Transitive Properties
183   // *****************
184 
185   /**
186    * Adds the value for the given property (Object, Symmetric and
187    * Transitive).
188    @throws InvalidValueException This exception is thrown when a value
189    *           is not compatible with the specified property's range.
190    */
191   public void addObjectPropertyValue(ObjectProperty aProperty, OInstance value)
192           throws InvalidValueException;
193 
194   /**
195    * Remove the provided value for the given property (Object, Symmetric
196    * and Transitive).
197    */
198   public void removeObjectPropertyValue(ObjectProperty aProperty,
199           OInstance value);
200 
201   /**
202    * Gets a list of values for the given Property (Object, Symmetric and
203    * Transitive).
204    @return {@link List} of {@link OInstance}.
205    */
206   public List<OInstance> getObjectPropertyValues(ObjectProperty aProperty);
207 
208   /**
209    * Removes all property values set for the current property (Object,
210    * Symmetric and Transitive).
211    */
212   public void removeObjectPropertyValues(ObjectProperty aProperty);
213 
214   /**
215    * This method returns the datatype properties set on this resource.
216    */
217   public Set<DatatypeProperty> getSetDatatypeProperties();
218   
219   
220   /**
221    * This method returns the object properties set on this resource.
222    */
223   public Set<ObjectProperty> getSetObjectProperties();
224   
225   
226   /**
227    * Checks if the resource has the provided datatype property set on it with the specified value.
228    */
229   public boolean hasDatatypePropertyWithValue(DatatypeProperty aProperty, Literal aValue);
230   
231   /**
232    * Checks if the resource has the provided object property set on it with the specified value.
233    */
234   public boolean hasObjectPropertyWithValue(ObjectProperty aProperty, OInstance aValue);
235 
236   public OURI getOURI();
237 }