Ontology.java
0001 /*
0002  *  Ontology.java
0003  *
0004  *  Niraj Aswani, 09/March/07
0005  *
0006  *  $Id: Ontology.java 17530 2014-03-04 15:57:43Z markagreenwood $
0007  */
0008 package gate.creole.ontology;
0009 
0010 import gate.LanguageResource;
0011 import gate.creole.ontology.OConstants.OntologyFormat;
0012 import gate.creole.ontology.OConstants.QueryLanguage;
0013 
0014 import gate.util.ClosableIterator;
0015 import java.io.File;
0016 import java.io.IOException;
0017 import java.io.InputStream;
0018 import java.io.OutputStream;
0019 import java.io.Reader;
0020 import java.io.Writer;
0021 import java.net.URL;
0022 import java.util.List;
0023 import java.util.Map;
0024 import java.util.Set;
0025 
0026 /**
0027  * Interface for ontology language resources.
0028  * A client program may only use the methods defined in this interface
0029  * to manipulate ontologies and must never use any methods from the
0030  * implementing package.
0031  <p>
0032  * All ontology language resources must be created using the
0033  {@link gate.Factory#createResource(String, gate.FeatureMap) Factory.createResource} method.
0034  <p>
0035  * See the documentation for the implementing plugins for details on
0036  * how to create ontology language resources programmatically.
0037  <p>
0038  * Unless stated otherwise, this documentation describes 
0039  * the behavior of the methods as implemented in the
0040  * ontology API implementation plugin,
0041  * <a href="../../../../../plugins/Ontology/doc/javadoc/index.html" target="_parent">Ontology</a>
0042  <p>
0043  * The backwards-compatibility plugin
0044  * a href="../../../../../plugins/Ontology/doc/javadoc/index.html" target="_parent">Ontology_OWLIM2</a>
0045  * implements all of the deprecated methods and classes but none of the
0046  * new methods that were added to the API in version 5.1.  Some but not all depracated
0047  * methods are also implemented in the new plugin <code>Ontology</code>
0048  <p>
0049  * The use of deprecated methods should be avoided and replaced by
0050  * other methods as soon as possible as the backwards-compatibility
0051  * plugin may get removed in the future and deprecated methods may
0052  * get removed from the API.
0053  
0054  @author Niraj Aswani
0055  @author Johann Petrak
0056  
0057  */
0058 public interface Ontology extends LanguageResource {
0059 
0060   /**
0061    * This method removes the entire data from the ontology and emptys
0062    * it. This will also re-initialize the ontology to the state it would have
0063    * after creation and perform the import of system data into the ontology
0064    * store (OWL and RDFS assertions).
0065    */
0066   public void cleanOntology();
0067 
0068   /**
0069    * Retrieves the ontology data and returns a string with the serialization
0070    * of the data in the specified format.
0071    
0072    @param format the format to be used for serialization <@see OConstants>
0073    @return a string containing the serialization of the ontology
0074    @deprecated not supported any more - throws UnsupportedOperationException
0075    */
0076   @Deprecated
0077   public String getOntologyData(byte format);
0078 
0079   /**
0080    * Exports the ontology data into the provided format to the provided
0081    * output stream.
0082    
0083    @param out OutputStream the serialized ontology data is written to
0084    @param format the serialization format, see {@link OConstants}
0085    @deprecated not supported any more - throws UnsupportedOperationException
0086    */
0087   @Deprecated
0088   public void writeOntologyData(OutputStream out, byte format);
0089 
0090   /**
0091    * Write the ontology data to the provided output stream in the specified
0092    * serialization format. The output stream has to be closed by the caller.
0093    *
0094    @since 5.1
0095    @param out an open OutpuStream for writing the data.
0096    @param format the serialization format
0097    @param includeExports if false, do not write any data that was loaded
0098    *   as an ontology import.
0099    */
0100   public void writeOntologyData(OutputStream out, 
0101     OntologyFormat format, boolean includeExports);
0102 
0103   /**
0104    * Exports the ontology data into the provided format using the
0105    * provided writer.
0106    
0107    @param out an open Writer for writing the data
0108    @param format the ontology serialization format , see {@link OConstants}
0109    @deprecated  not supported any more and will throw and exception
0110    * in the new implementation plugin
0111    */
0112   @Deprecated
0113   public void writeOntologyData(Writer out, byte format);
0114 
0115   /**
0116    * Write the ontology data to the provided writer in the specified 
0117    * serialization format. The writer object has to be closed by the caller.
0118    
0119    @param out an open Writer for writing the data
0120    @param format the ontology serialization format , see
0121    {@link OConstants.OntologyFormat}
0122    @param includeExports if false, do not write any data that was loaded as
0123    * and ontology import.
0124    */
0125   public void writeOntologyData(Writer out, 
0126       OntologyFormat format, boolean includeExports);
0127 
0128 
0129   /**
0130    * Read ontology data from the specified stream in the specified format
0131    * and load it into the ontology. The input stream has to be closed by
0132    * the caller.
0133    *
0134    @param in an InputStream object for reading the ontology data
0135    @param baseURI the URI to use for resolving URI references
0136    @param format the serialization format of the ontology, see
0137    {@link OConstants.OntologyFormat}
0138    @param asImport if true, load the data as an ontology import which means
0139    *   that it will not be written as part of the user data, unless explicitly
0140    *   requested.
0141    */
0142   public void readOntologyData(InputStream in, String baseURI,
0143       OntologyFormat format, boolean asImport);
0144 
0145 
0146 
0147     /**
0148    * Read ontology data from the specified reader in the specified format
0149    * and load it into the ontology.
0150    @param in
0151      @param baseURI 
0152      @param format
0153    @param asImport asImport if true, load the data as an ontology import which means
0154    *   that it will not be written as part of the user data, unless explicitly
0155    *   requested.
0156    */
0157   public void readOntologyData(Reader in, String baseURI,
0158       OntologyFormat format, boolean asImport);
0159 
0160 
0161   /**
0162    * Get the URI of this ontology. If no ontology URI is found, null is
0163    * returned. If more than one ontology URI is found, an exception is
0164    * thrown.
0165    
0166    @return the OURI of the current ontology or null
0167    */
0168   public OURI getOntologyURI();
0169 
0170   /**
0171    * Set the ontology URI of the current ontology. If the ontology
0172    * URI is already set to a different value, this method throws an exception.
0173    <p>
0174    * NOTE: this method does not set the default namespace!
0175    <p>
0176    * NOTE: at the moment, this method allows to set the ontology URI as long as no
0177    * URI is set yet. Once an ontology URI is set, it cannot be changed
0178    * since it would not be clear what to do with assertions that alreadt reference
0179    * that ontology URI (e.g. ontology annotations or import specifications).
0180    *
0181    @param theURI
0182    */
0183   public void setOntologyURI(OURI theURI);
0184 
0185 
0186   /**
0187    * Loads all imported ontologies. This method finds all ontology import
0188    * URIs in the current ontology and loads as imports the ontologies
0189    * referenced by these URIs. If an URI is found in <code>importMappings<code>,
0190    * and maps to an empty String, the import will be ignored. If an URI
0191    * is found and maps to a non-empty string, the string will be interpreted
0192    * as an URL from which to load the imported ontology. If no entry is found
0193    * for the URI, the URI will be interpreted as an URL from which to load
0194    * the ontology. All import URIs of ontologies loaded during this process
0195    * will be recursively processed in the same way.
0196    <p>
0197    * A GateOntologyException is thrown if any import that should be loaded
0198    * cannot be loaded and the import loading process is aborted before
0199    * potential additional imports are processed.
0200    
0201    @param importMappings
0202    */
0203   public void resolveImports(Map<String,String> importMappings);
0204 
0205   /**
0206    * Gets the URL of this ontology. This usually is the URL the ontology was
0207    * loaded  from. If several files were loaded, the URL of the first file
0208    * is returned. Files loaded as imports are not considered for this.
0209    * If and how this is set automatically when an ontology LR
0210    * is created depends on the implementation.
0211    * For an ontology LR that connects to an existing ontology repository,
0212    * an URL derived from the ontology repository location may be returned.
0213    
0214    @return the URL of this ontology if set, or null otherwise
0215    */
0216   public URL getURL();
0217 
0218   /**
0219    * Set the URL of this ontology.
0220    * This URL set by this method will be returned by the {@link #getURL()}
0221    * method. The ontology store is not modified by this.
0222    
0223    @param aUrl the url to be set
0224    */
0225   public void setURL(URL aUrl);
0226 
0227 
0228   /**
0229    * Saves the ontology in the specified File
0230    *
0231    @param newOntology  a File object describing the file where to save to
0232    @throws IOException 
0233    @deprecated not implemented any more, throws UnsupportedOperationException
0234    */
0235   @Deprecated
0236   public void store(File newOntologythrows IOException;
0237 
0238   /**
0239    * Sets the default name space/base URI for the ontology.
0240    * This URI must end in "#" or "/". This URI is used when a new OURI
0241    * is created using the {@link #createOURIForName(String)} method.
0242    * Setting the default name space with this method does not change the
0243    * ontology store and does not add a default namespace declaration to the
0244    * store or when the ontology is saved.
0245    
0246    @param aNameSpace a String that can be used as a base URI
0247    */
0248   public void setDefaultNameSpace(String aNameSpace);
0249 
0250   /**
0251    * Gets the default name space for this ontology.
0252    * This is used as the base URI for the ontology.
0253    * This returns the last value set with the method setDefaultNameSpace.
0254    * If the default name space was not set with this method, it is set
0255    * to a default value when an ontology is loaded in the following way:
0256    * If a base URI is specified for the loading, that base URI is used,
0257    * otherwise, if there was no ontology URI already set from a previous
0258    * load and this load determined exactly one ontology URI, that URI
0259    * will be used to set the default name space.
0260    
0261    @return a String value.
0262    */
0263   public String getDefaultNameSpace();
0264 
0265   /**
0266    * Sets the version information for the ontology. 
0267    
0268    @param theVersion the version to be set
0269    @deprecated use method setOntologyAnnotation instead
0270    */
0271   @Deprecated
0272   public void setVersion(String theVersion);
0273 
0274   /**
0275    * Gets the version of this ontology.
0276    
0277    @return the version of this ontology
0278    @deprecated use method getOntologyAnnotationValues instead
0279    */
0280   @Deprecated
0281   public String getVersion();
0282 
0283   /**
0284    * Set an annotation property for the ontology to the specified literal
0285    * value.
0286    *
0287    @param ann the annotation property object
0288    @param value a Literal object describing the value. This usually should be
0289    * a String literal.
0290    
0291    */
0292   public void setOntologyAnnotation(AnnotationProperty ann, Literal value);
0293 
0294   /**
0295    * Get the values of an ontology annotation property.
0296    *
0297    @param ann the annotation property object
0298    @return a a list of literals describing the values for the property
0299    */
0300   public List<Literal> getOntologyAnnotationValues(AnnotationProperty ann);
0301 
0302 
0303   /**
0304    * Creates a new OClass and adds it the ontology.
0305    
0306    @param aURI URI of this class
0307    @param classType one of the values from
0308    *          OConstants.OCLASS_TYPE_OWL_CLASS and
0309    *          OConstants.OCLASS_TYPE_OWL_RESTRICTION;
0310    @return the newly created class or an existing class if available
0311    *         with the same URI.
0312    @deprecated - use one of the dedicated methods to add a named class
0313    *   or a restriction instead
0314    */
0315   @Deprecated
0316   public OClass addOClass(OURI aURI, byte classType);
0317 
0318   /**
0319    * Creates a new OWL Class and adds it the ontology.
0320    * If a class with that URI already exists, that class is returned.
0321    
0322    @param aURI URI of this class
0323    @return the newly created class or an existing class if available
0324    *         with the same URI.
0325    */
0326   public OClass addOClass(OURI aURI);
0327   
0328   
0329 //  /**
0330 //   * Retrieves a named class by its URI.
0331 //   *
0332 //   * @param theClassURI the URI of the class
0333 //   * @return the class with that URI or null if no such class exists
0334 //   */
0335 //  public OClass getOClass(OURI theClassURI);
0336 
0337   /**
0338    * Retrieves a both named classes and anonymous classes and retrictions that
0339    * match either the URI or the blank node identifier represented by ONodeID
0340    @param theClassID
0341    @return the class matching the URI or blank node ID or null if no matches.
0342    */
0343   public OClass getOClass(ONodeID theClassID);
0344 
0345   /**
0346    * Removes a class from this ontology.
0347    
0348    @param theClass the class to be removed
0349    */
0350   public void removeOClass(OClass theClass);
0351 
0352   /**
0353    * Checks whether a class with the specified URI or blank node ID
0354    * exists in the ontology.
0355    
0356    @param theURI a ONodeID, usually an OURI specifying the ID of the
0357    * ontology class
0358    @return true, if the class exists 
0359    */
0360   public boolean containsOClass(ONodeID theURI);
0361 
0362   /**
0363    * Checks whether the ontology contains this class.
0364    
0365    @param theClass a ontology class object
0366    @return true, if the class exists, otherwise - false.
0367    */
0368   public boolean containsOClass(OClass theClass);
0369 
0370   /**
0371    * Retrieves all ontology classes in a set.
0372    * This method returns a set of either all classes in the ontology or
0373    * just the "top" classes. A "top" class is a class that is not a subclass
0374    * of any other class that is not a predefined system class like owl:Thing
0375    * or rdfs:Resource or a trivial subclass (of itself or of a class that
0376    * is defined to be equivalent to itself).
0377    <p>
0378    * NOTE: for large ontologies with a large number of classes it may be
0379    * preferable to use method {@link #getOClassesIterator(boolean)} instead.
0380    
0381    @param top If set to true, only returns those classes with no super
0382    *          classes, otherwise - a set of all classes.
0383    @return set of all the classes in this ontology
0384    */
0385   public Set<OClass> getOClasses(boolean top);
0386 
0387 
0388   /**
0389    * Return an iterator to retrieve all ontology classes in the ontology.
0390    * The iterator should be closed() as soon as it is not needed anymore
0391    * but will auto-close when it is exhausted and the hasNext() method
0392    * returned false.
0393    
0394    @param top If set to true, only returns those classes with no
0395    *     super classes, otherwise all classes
0396    @return a ClosableIterator for accessing the returned ontology classes
0397    */
0398   public ClosableIterator<OClass> getOClassesIterator(boolean top);
0399    
0400 
0401   /**
0402    * Gets the taxonomic distance between 2 classes.
0403    
0404    @param class1 the first class
0405    @param class2 the second class
0406    @return the taxonomic distance between the 2 classes
0407    */
0408   public int getDistance(OClass class1, OClass class2);
0409 
0410   // *****************************
0411   // OInstance methods
0412   // *****************************
0413   /**
0414    * Creates a new OInstance and returns it.
0415    
0416    @param theInstanceURI
0417    @param theClass the class to which the instance belongs.
0418    @return the OInstance that has been added to the ontology.
0419    */
0420   public OInstance addOInstance(OURI theInstanceURI, OClass theClass);
0421 
0422   /**
0423    * Removes the instance from the ontology.
0424    
0425    @param theInstance to be removed
0426    */
0427   public void removeOInstance(OInstance theInstance);
0428 
0429   /**
0430    * Gets all instances in the ontology.
0431    
0432    @return {@link Set} of OInstance objects
0433    */
0434   public Set<OInstance> getOInstances();
0435 
0436   /*
0437    * Return an iterator for accessing all instances in the ontology.
0438    * @return
0439    */
0440   public ClosableIterator<OInstance> getOInstancesIterator();
0441 
0442   /**
0443    * Gets instances in the ontology, which belong to this class. 
0444    
0445    @param theClass the class of the instances
0446    @param closure either DIRECT_CLOSURE or TRANSITIVE_CLOSURE of
0447    *          {@link OConstants}
0448    
0449    @return {@link Set} of OInstance objects
0450    */
0451   @Deprecated
0452   public Set<OInstance> getOInstances(OClass theClass, byte closure);
0453 
0454   /**
0455    * Gets instances in the ontology, which belong to this class.
0456    * The second parameter specifies if the the given class needs to be
0457    * a direct class of the instance (direct closure)
0458    * or a class to which the instance belongs
0459    * indirectly (transitive closure)
0460    *
0461    @param theClass the class of the instances
0462    @param closure either {@link OConstants.Closure#DIRECT_CLOSURE} or
0463    {@link OConstants.Closure#TRANSITIVE_CLOSURE}
0464    *
0465    @return {@link Set} of OInstance objects
0466    */
0467   public Set<OInstance> getOInstances(OClass theClass, OConstants.Closure closure);
0468 
0469   public ClosableIterator<OInstance>
0470       getOInstancesIterator(OClass theClass, OConstants.Closure closure);
0471 
0472   /**
0473    * Gets the instance with the given URI.
0474    
0475    @param theInstanceURI the instance URI
0476    @return the OInstance object with this URI. If there is no such
0477    *         instance then null.
0478    */
0479   public OInstance getOInstance(OURI theInstanceURI);
0480 
0481   /**
0482    * Checks whether the provided Instance exists in the ontology.
0483    
0484    @param theInstance
0485    @return true, if the Instance exists in ontology, otherwise -
0486    *         false.
0487    */
0488   public boolean containsOInstance(OInstance theInstance);
0489 
0490   /**
0491    * Checks whether the provided URI refers to an Instance that exists
0492    * in the ontology.
0493    
0494    @param theInstanceURI
0495    @return true, if the URI exists in ontology and refers to an
0496    *         Instance, otherwise - false.
0497    */
0498   public boolean containsOInstance(OURI theInstanceURI);
0499 
0500   // *****************************
0501   // Property definitions methods
0502   // *****************************
0503   /**
0504    * Creates a new RDFProperty.
0505    
0506    @param aPropertyURI URI of the property to be added into the
0507    *          ontology.
0508    @param domain a set of {@link OResource} (e.g. a Class, a Property
0509    *          etc.).
0510    @param range a set of {@link OResource} (e.g. a Class, a Property
0511    *          etc.).
0512    @deprecated
0513    */
0514   @Deprecated
0515   public RDFProperty addRDFProperty(OURI aPropertyURI, Set<OResource> domain,
0516           Set<OResource> range);
0517 
0518   /**
0519    * Gets the set of RDF Properties in the ontology where for a property
0520    * there exists a statement <theProperty, RDF:Type, RDF:Property>.
0521    
0522    @return {@link Set} of {@link RDFProperty}.
0523    */
0524   public Set<RDFProperty> getRDFProperties();
0525 
0526   /**
0527    * Checkes whether there exists a statement <thePropertyURI, RDF:Type,
0528    * RDF:Property> in the ontology or not.
0529    
0530    @param thePropertyURI
0531    @return true, only if there exists the above statement, otherwise -
0532    *         false.
0533    */
0534   public boolean isRDFProperty(OURI thePropertyURI);
0535 
0536   /**
0537    * Creates a new AnnotationProperty.
0538    
0539    @param aPropertyURI URI of the property to be added into the
0540    *          ontology.
0541    */
0542   public AnnotationProperty addAnnotationProperty(OURI aPropertyURI);
0543 
0544   /**
0545    * Gets the set of Annotation Properties in the ontology where for a
0546    * property there exists a statement <theProperty, RDF:Type,
0547    * OWL:AnnotationProperty>.
0548    
0549    @return {@link Set} of {@link AnnotationProperty}.
0550    */
0551   public Set<AnnotationProperty> getAnnotationProperties();
0552 
0553   /**
0554    * Checkes whether there exists a statement <thePropertyURI, RDF:Type,
0555    * OWL:AnnotationProperty> in the ontology or not.
0556    
0557    @param thePropertyURI
0558    @return true, only if there exists the above statement, otherwise -
0559    *         false.
0560    */
0561   public boolean isAnnotationProperty(OURI thePropertyURI);
0562 
0563   /**
0564    * Create a DatatypeProperty with the given domain and range.
0565    *
0566    * The domain must be specified as a set of OClass objects, the resulting
0567    * domain is the intersection of all specified classes.
0568    <p>
0569    * If this method is called with an OURI of a datatype property that
0570    * already exists, any specified domain class is added to the intersection
0571    * of classes already defined for the domain.
0572    
0573    @param aPropertyURI the URI for the new property.
0574    @param domain the set of ontology classes
0575    * that constitutes the domain for the new property.
0576    @param aDatatype a DataType object describing the datatype of the range.
0577    @return the newly created property.
0578    */
0579   public DatatypeProperty addDatatypeProperty(OURI aPropertyURI,
0580           Set<OClass> domain, DataType aDatatype);
0581 
0582   /**
0583    * Gets the set of Datatype Properties in the ontology.
0584    
0585    @return {@link Set} of {@link DatatypeProperty}.
0586    */
0587   public Set<DatatypeProperty> getDatatypeProperties();
0588 
0589   /**
0590    * Checkes whether the ontology contains a datatype property with the
0591    * given URI.
0592    
0593    @param thePropertyURI
0594    @return true if there is an instance of owl:DatatypeProperty with the
0595    * given URI in the ontology.
0596    */
0597   public boolean isDatatypeProperty(OURI thePropertyURI);
0598 
0599   /**
0600    * Creates a new object property (a property that takes instances as
0601    * values).
0602    <p>
0603    * If this method is called with an OURI of an object property that
0604    * already exists, any specified domain or range class is added to
0605    * the intersection of classes already defined for the domain or range.
0606    
0607    @param aPropertyURI the URI for the new property.
0608    @param domain the set of ontology classes (i.e. {@link OClass}
0609    * objects} that constitutes the domain of the property.
0610    * An instance must belong to the intersection of all classes
0611    * in the set to be a valid member of the domain of the property.
0612    * If an empty set or null is passed, the instance can belong to any
0613    * class.
0614    @param range the set of ontology classes (i.e. {@link OClass}
0615    * objects} that constitutes the range for the new property. The instance
0616    * that is the value of a property must belong to the intersection of
0617    * all classes in this set to be valid. If an empty set or null is passed
0618    * on, the instance can belong to any class.
0619    @return the newly created property.
0620    */
0621   public ObjectProperty addObjectProperty(OURI aPropertyURI, Set<OClass> domain,
0622           Set<OClass> range);
0623 
0624   /**
0625    * Gets the set of Object Properties in the ontology.
0626    
0627    @return {@link Set} of {@link ObjectProperty}.
0628    */
0629   public Set<ObjectProperty> getObjectProperties();
0630 
0631   /**
0632    * Checks if there exists an object property with the given URI
0633    
0634    @param thePropertyURI
0635    @return true, only if there exists an object property with the
0636    * given URI.
0637    */
0638   public boolean isObjectProperty(OURI thePropertyURI);
0639 
0640   /**
0641    * Creates a new symmetric property (an object property that is
0642    * symmetric).
0643    <p>
0644    * If this method is called with an OURI of a datatype property that
0645    * already exists, any specified domainAndRange class is added to the
0646    * intersection of classes already defined for the domain and range.
0647    
0648    @param aPropertyURI the URI for the new property.
0649    @param domainAndRange the set of ontology classes (i.e.
0650    *          {@link OClass} objects} that constitutes the domain and
0651    *          the range for the new property. The property only applies
0652    *          to instances that belong to <b>the intersection of all</b>
0653    * classes included
0654    *          in its domain. An empty set means that the property
0655    *          applies to instances of any class.
0656    @return the newly created property.
0657    */
0658   public SymmetricProperty addSymmetricProperty(OURI aPropertyURI,
0659           Set<OClass> domainAndRange);
0660 
0661   /**
0662    * Gets the set of Symmetric Properties in the ontology.
0663    
0664    @return {@link Set} of {@link SymmetricProperty}.
0665    */
0666   public Set<SymmetricProperty> getSymmetricProperties();
0667 
0668   /**
0669    * Checkes whether there exists a statement <thePropertyURI, RDF:Type,
0670    * OWL:SymmetricProperty> in the ontology or not.
0671    
0672    @param thePropertyURI
0673    @return true, only if there exists the above statement, otherwise -
0674    *         false.
0675    */
0676   public boolean isSymmetricProperty(OURI thePropertyURI);
0677 
0678   /**
0679    * Creates a new transitive property (an object property that is
0680    * transitive).
0681    <p>
0682    * If this method is called with an OURI of a transitive property that
0683    * already exists, any specified domain or range class is added to the intersection
0684    * of classes already defined for the domain or range.
0685    *
0686    @param aPropertyURI the URI for the new property.
0687    @param domain the set of ontology classes (i.e. {@link OClass}
0688    *          objects} that constitutes the range for the new property.
0689    *          The property only applies to instances that belong to
0690    *          <b>the intersection of all</b> classes included in its domain.
0691    * An empty set
0692    *          means that the property applies to instances of any class.
0693    @param range the set of ontology classes (i.e. {@link OClass}
0694    *          objects} that constitutes the range for the new property.
0695    @return the newly created property.
0696    */
0697   public TransitiveProperty addTransitiveProperty(OURI aPropertyURI,
0698           Set<OClass> domain, Set<OClass> range);
0699 
0700   /**
0701    * Gets the set of Transitive Properties in the ontology.
0702    
0703    @return {@link Set} of {@link TransitiveProperty}.
0704    */
0705   public Set<TransitiveProperty> getTransitiveProperties();
0706 
0707   /**
0708    * Checkes whether there exists a statement <thePropertyURI, RDF:Type,
0709    * OWL:TransitiveProperty> in the ontology or not.
0710    
0711    @param thePropertyURI
0712    @return true, only if there exists the above statement, otherwise -
0713    *         false.
0714    */
0715   public boolean isTransitiveProperty(OURI thePropertyURI);
0716 
0717   /**
0718    * Gets the set of RDF, Object, Datatype, Symmetric and Transitive
0719    * property definitions in this ontology.
0720    
0721    @return {@link Set} of {@link RDFProperty},
0722    *         {@link DatatypeProperty}{@link ObjectProperty},
0723    *         {@link TransitiveProperty} and , {@link SymmetricProperty}
0724    *         objects. <B>Please note that the method does not include
0725    *         annotation properties</B>.
0726    */
0727   public Set<RDFProperty> getPropertyDefinitions();
0728 
0729   /**
0730    * Returns the property for a given URI or null if there is no property
0731    * with that URI.
0732    
0733    @param thePropertyURI the URI of the property
0734    @return the RDFProperty object or null if no property with that URI is found
0735    */
0736   public RDFProperty getProperty(OURI thePropertyURI);
0737 
0738   /**
0739    * Returns the annotation property for the given URI or null if there is
0740    * no annotation property with that URI.
0741    *
0742    @param theURI the URI of the property
0743    @return the AnnotationProperty obejct
0744    */
0745   public AnnotationProperty getAnnotationProperty(OURI theURI);
0746 
0747   /**
0748    * Returns the datatype property for the given URI or null if there is
0749    * no datatype property with that URI.
0750    *
0751    @param theURI the URI of the property
0752    @return the DatatypeProperty obejct
0753    */
0754   public DatatypeProperty getDatatypeProperty(OURI theURI);
0755 
0756   /**
0757    * Returns the object property for the given URI or null if there is
0758    * no object property with that URI.
0759    *
0760    @param theURI the URI of the property
0761    @return the AnnotationProperty obejct
0762    */
0763   public ObjectProperty getObjectProperty(OURI theURI);
0764 
0765 
0766   /**
0767    * A method to remove the existing propertyDefinition (exclusive of
0768    * Annotation Property).
0769    
0770    @param theProperty
0771    */
0772   public void removeProperty(RDFProperty theProperty);
0773 
0774   // *****************************
0775   // Restrictions
0776   // *****************************
0777 
0778   /**
0779    * Adds a new MinCardinality Restriction to the ontology. It
0780    * automatically creates a randon anonymous class, which it uses to
0781    * denote the restriction. The default datatype is set to NonNegativeIntegerNumber
0782    
0783    @param onProperty - Specifies the property for which the restriction is being set.
0784    @param minCardinalityValue - generally a numeric number.
0785    @throws InvalidValueException - if a value is not compatible with the nonNegativeIntegerNumber datatype.
0786    */
0787   public MinCardinalityRestriction addMinCardinalityRestriction(
0788           RDFProperty onProperty, String minCardinalityValue)
0789           throws InvalidValueException;
0790   
0791   /**
0792    * Adds a new MaxCardinality Restriction to the ontology. It
0793    * automatically creates a randon anonymous class, which it uses to
0794    * denote the restriction. The default datatype is set to NonNegativeIntegerNumber
0795    
0796    @param onProperty - Specifies the property for which the restriction is being set.
0797    @param maxCardinalityValue - generally a numeric number.
0798    @throws InvalidValueException - if a value is not compatible with the nonNegativeIntegerNumber datatype.
0799    */
0800   public MaxCardinalityRestriction addMaxCardinalityRestriction(
0801           RDFProperty onProperty, String maxCardinalityValue)
0802           throws InvalidValueException;
0803 
0804   /**
0805    * Adds a new Cardinality Restriction to the ontology. It
0806    * automatically creates a randon anonymous class, which it uses to
0807    * denote the restriction. The default datatype is set to NonNegativeIntegerNumber
0808    
0809    @param onProperty - Specifies the property for which the restriction is being set.
0810    @param cardinalityValue - generally a numeric number.
0811    @throws InvalidValueException - if a value is not compatible with the nonNegativeIntegerNumber datatype.
0812    */
0813   public CardinalityRestriction addCardinalityRestriction(
0814           RDFProperty onProperty, String cardinalityValue)
0815           throws InvalidValueException;
0816 
0817   /**
0818    * Adds a new HasValue Restriction to the ontology. It
0819    * automatically creates a randon anonymous class, which it uses to
0820    * denote the restriction.
0821    
0822    @param onProperty - Specifies the property for which the restriction is being set.
0823    @param hasValue - a resource used as a value for hasValue element of the restriction.
0824    */
0825   public HasValueRestriction addHasValueRestriction(
0826           RDFProperty onProperty, OResource hasValue);
0827 
0828   /**
0829    * Adds a new AllValuesFrom Restriction to the ontology.
0830    *
0831    @param onProperty - Specifies the property for which the restriction is being set.
0832    @param hasValue - a resource used as a value for hasValue element of the restriction.
0833    @deprecated - this method is deprecated and kept for backwards compatibility
0834    * as long as the OntologyOWLIM2 plugin is kept. Use the method
0835    {@link #addAllValuesFromRestriction(ObjectProperty, OClass)} instead.
0836    */
0837   @Deprecated
0838   public AllValuesFromRestriction addAllValuesFromRestriction(
0839           RDFProperty onProperty, OResource hasValue);
0840 
0841   public AllValuesFromRestriction addAllValuesFromRestriction(
0842       ObjectProperty onProperty, OClass theClass);
0843 
0844 
0845   /**
0846    * Adds a new AllValuesFrom Restriction to the ontology. It
0847    * automatically creates a randon anonymous class, which it uses to
0848    * denote the restriction.
0849    
0850    @param onProperty - Specifies the property for which the restriction is being set.
0851    @param hasValue - a resource used as a value for hasValue element of the restriction.
0852    */
0853   public SomeValuesFromRestriction addSomeValuesFromRestriction(
0854           RDFProperty onProperty, OResource hasValue);
0855 
0856 
0857   public AnonymousClass addAnonymousClass();
0858   
0859   // *****************************
0860   // Ontology Modification Events
0861   // *****************************
0862   /**
0863    * Sets the modified flag.
0864    
0865    @param isModified sets this param as a value of the modified
0866    *          property of the ontology
0867    */
0868   public void setModified(boolean isModified);
0869 
0870   /**
0871    * Checks the modified flag.
0872    
0873    @return whether the ontology has been modified after the loading
0874    */
0875   @Override
0876   public boolean isModified();
0877 
0878   /**
0879    * Register the Ontology Modification Listeners
0880    */
0881   public void addOntologyModificationListener(OntologyModificationListener oml);
0882 
0883   /**
0884    * Removed the registered ontology modification listeners
0885    */
0886   public void removeOntologyModificationListener(
0887           OntologyModificationListener oml);
0888 
0889   /**
0890    * A method to invoke when a resource's property value is changed
0891    */
0892   public void fireResourcePropertyValueChanged(OResource resource, RDFProperty property, Object value, int eventType);
0893 
0894   /**
0895    * A method to invoke when a resource's property value is changed
0896    
0897    @param resource1
0898    @param resource2
0899    @param eventType
0900    */
0901   public void fireResourceRelationChanged(OResource resource1, OResource resource2,int eventType);
0902 
0903   /**
0904    * A Method to invoke an event for newly added ontology resource
0905    
0906    @param resource
0907    */
0908   public void fireOntologyResourceAdded(OResource resource);
0909 
0910   /**
0911    * A Method to invoke an event for a removed ontology resource
0912    
0913    @param resources 
0914    */
0915   public void fireOntologyResourcesRemoved(String[] resources);
0916 
0917   /**
0918    * A method to invoke when the ontology is reset.
0919    
0920    */
0921   public void fireOntologyReset();
0922 
0923   // *************************
0924   // Sesame Repository methods
0925   // *************************
0926   /**
0927    * Start the transaction before additing statements.
0928    */
0929 
0930   /**
0931    * Commit all changes to the ontology.
0932    * This will commit all changesall the transaction (so far included after the call to
0933    * start transaction) into the repository.
0934    *
0935    @deprecated
0936    */
0937   @Deprecated
0938   public void commitTransaction();
0939 
0940   /**
0941    * Checks whether the transation is already started.
0942    @deprecated 
0943    */
0944   @Deprecated
0945   public boolean transationStarted();
0946 
0947   /**
0948    * Returns the repository created for this particular instance of the
0949    * ontology.
0950    @deprecated
0951    */
0952   @Deprecated
0953   public Object getSesameRepository();
0954 
0955   /**
0956    * Returns the ID of a Sesame Repository created for this particular
0957    * instance of the ontology.
0958    @deprecated
0959    */
0960   @Deprecated
0961   public String getSesameRepositoryID();
0962 
0963 
0964 
0965   /**
0966    * Given a URI object, this method returns its equivalent object
0967    @deprecated
0968    */
0969   @Deprecated
0970   public OResource getOResourceFromMap(String uri);
0971 
0972   /**
0973    * Adds the resource to central map
0974    @deprecated
0975    */
0976   @Deprecated
0977   public void addOResourceToMap(String uri, OResource resource);
0978 
0979   /**
0980    * Removes the resource from the central map
0981    
0982    @param uri
0983    @deprecated 
0984    */
0985   @Deprecated
0986   public void removeOResourceFromMap(String uri);
0987 
0988   /**
0989    * This method checks in its cache to find out the OResource for the
0990    * given resource name. However, It is also possible for two resources
0991    * to have a same name but different name spaces. This method returns
0992    * the first found OResource (without guaranteeing the order) from its
0993    * list. If user wants to retrieve a list of resources, he/she must
0994    * use the getOResourcesByName(String resourceName).
0995    @deprecated
0996    */
0997   @Deprecated
0998   public OResource getOResourceByName(String resourceName);
0999 
1000   /**
1001    * This method checks in its cache to find out the OResources for the
1002    * given resource name. It is possible for two resources to have a
1003    * same name but different name spaces. This method returns a list of
1004    * resources with the common name. Please note that deleting an
1005    * instance from this list (e.g. list.remove(int/Object)) does not
1006    * delete the resource from an ontology. One must use appropriate
1007    * method from the Ontology interface to delete such resources.
1008    */
1009   public List<OResource> getOResourcesByName(String resourceName);
1010 
1011   /**
1012    * This method returns a list of OResources from the ontology. Please
1013    * note that deleting an instance from this list (e.g.
1014    * list.remove(int/Object)) does not delete the resource from an
1015    * ontology. One must use appropriate method from the Ontology
1016    * interface to delete such resources.
1017    
1018    @deprecated
1019    */
1020   @Deprecated
1021   public List<OResource> getAllResources();
1022 
1023   /**
1024    * This method given a property (either an annotation or datatype),
1025    * retrieves a list of resources which have the provided literal set
1026    * as a value.
1027    */
1028   public List<OResource> getOResourcesWith(RDFProperty aProperty, Literal aValue);
1029 
1030   /**
1031    * This method given a property (either object, transitive, symmetric
1032    * or rdf), retrieves a list of resources which have the provided
1033    * resource set as a value.
1034    */
1035   public List<OResource> getOResourcesWith(RDFProperty aProperty,
1036           OResource aValue);
1037 
1038   /**
1039    * The method executes the query on repository and returns the toString()
1040    * result of the QueryResultTable.
1041    *
1042    @deprecated
1043    */
1044   @Deprecated
1045   public String executeQuery(String serqlQuery);
1046 
1047   /**
1048    * This method creates a OntologyTupleQuery object and passes on
1049    * the specified query string in the specified query language.
1050    *
1051    @param theQuery a String representing the tuple query.
1052    @param queryLanguage the query language, either SERQL or SPARQL
1053    @return the OntologyTurpleQuery object that can be used to retrieve
1054    * the matching tuples in several formats. The query object can be re-used
1055    * with different variable bindings.
1056    */
1057   public OntologyTupleQuery createTupleQuery(String theQuery, QueryLanguage queryLanguage);
1058 
1059   /**
1060    * This method creates a OntologyBooleanQuery object and passes on the
1061    * specified query string and the specified query language.
1062    *
1063    @param theQuery a String representing the tuple query.
1064    @param queryLanguage the query language, either SERQL or SPARQL
1065    @return the OntologyBooleanQuery object that can be used to retrieve
1066    * the boolean answer for the query. The query object can be re-used
1067    * with different variable bindings.
1068    */
1069   public OntologyBooleanQuery createBooleanQuery(String theQuery, QueryLanguage queryLanguage);
1070 
1071   /**
1072    * Return an object representing the triple store which backs the ontology.
1073    
1074    @return The OntologyTripleStore object for this ontology or null if
1075    * modifying the ontology via triples is not supported by the implementation.
1076    */
1077   public abstract OntologyTripleStore getOntologyTripleStore();
1078 
1079 
1080 
1081   /**
1082    * Create an ORUI object from the given URI string.
1083    *
1084    @param theURI an URI or IRI string
1085    @return the OURI object representing the URI/IRI
1086    */
1087   public OURI createOURI(String theURI);
1088 
1089   /**
1090    * Create an OURI from the given resource name, using the ontology base URI
1091    * (default name space). This method will throw an exception if no
1092    * default name space is set (i.e. if the method getDefaultNameSpace would
1093    * return null).
1094    *
1095    @param resourceName the resource name i.e. the part of the final URI/IRI
1096    * that is attached to the base URI (aftaer a trailing "#" or "/").
1097    @return the OURI 
1098    */
1099   public OURI createOURIForName(String resourceName);
1100 
1101 
1102   /** Generate a new unique OURI for this ontology.
1103    * This generates a new OURI that is guaranteed to be unique in the
1104    * ontology, using the specified resource name string as a prefix for the
1105    * URI's fragement identifier and the current defaultNameSpace of the
1106    * ontology as a base URI.
1107    * The resource name can be null or the empty string if no prefix is
1108    * wanted.
1109    <p>
1110    * The URI fragment part that is appended to the given resourceName (if any)
1111    * consists of 7 ASCII characters representing the system time  in radix 36
1112    * followed by 3 ASCII characters representing a random number.
1113    <p>
1114    * Note that this method will return an OURI that is guaranteed not
1115    * to be contained in the ontology, but if called repeatedly without
1116    * actually adding a resource with the newly generated OURI to the ontology,
1117    * the method might, although extremely unlikely,
1118    * still return the same OURI more than once. Generated OURIs should hence
1119    * been used for adding resources before more OURIs are generated.
1120    
1121    @param resourceNamePrefix the prefix to use for the generated resource
1122    * name
1123    @return a OURI object for an URI that is new and unique in the ontology
1124    */
1125   public OURI generateOURI(String resourceNamePrefix);
1126 
1127   /** Generate a new unique OURI for this ontology.
1128    * This works in the same way as {@link #generateOURI(java.lang.String) }
1129    * but also allows the specification of the base URI part of the final
1130    * URI.
1131    *
1132    @param resourceNamePrefix the prefix to use for the generated resource name
1133    @param baseURI the base URI to use for the final URI
1134    @return a OURI object for an URI that is new and unique in the ontology
1135    */
1136   public OURI generateOURI(String resourceNamePrefix, String baseURI);
1137 
1138 }