0001 /*
0002 * Ontology.java
0003 *
0004 * Niraj Aswani, 09/March/07
0005 *
0006 * $Id: Ontology.java 12160 2010-01-14 09:32:42Z johann_p $
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 newOntology) throws 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 * The annotation property can be one of the predefined system annotation
0287 * properties that can be generated with
0288 * {@link #getSystemAnnotationProperty(OConstants.SystemAnnotationProperty)} or
0289 * a user-defined annotation property.
0290 *
0291 * @param ann the annotation property object
0292 * @param value a Literal object describing the value. This usually should be
0293 * a String literal.
0294 *
0295 */
0296 public void setOntologyAnnotation(AnnotationProperty ann, Literal value);
0297
0298 /**
0299 * Get the values of an ontology annotation property.
0300 * The annotation property can be one of the predefined system annotation
0301 * properties that can be generated with
0302 * {@link #getSystemAnnotationProperty(OConstants.SystemAnnotationProperty)} or
0303 * a user-defined annotation property.
0304 *
0305 * @param ann the annotation property object
0306 * @return a a list of literals describing the values for the property
0307 */
0308 public List<Literal> getOntologyAnnotationValues(AnnotationProperty ann);
0309
0310
0311 /**
0312 * Creates a new OClass and adds it the ontology.
0313 *
0314 * @param aURI URI of this class
0315 * @param classType one of the values from
0316 * OConstants.OCLASS_TYPE_OWL_CLASS and
0317 * OConstants.OCLASS_TYPE_OWL_RESTRICTION;
0318 * @return the newly created class or an existing class if available
0319 * with the same URI.
0320 * @deprecated - use one of the dedicated methods to add a named class
0321 * or a restriction instead
0322 */
0323 @Deprecated
0324 public OClass addOClass(OURI aURI, byte classType);
0325
0326 /**
0327 * Creates a new OWL Class and adds it the ontology.
0328 * If a class with that URI already exists, that class is returned.
0329 *
0330 * @param aURI URI of this class
0331 * @return the newly created class or an existing class if available
0332 * with the same URI.
0333 */
0334 public OClass addOClass(OURI aURI);
0335
0336
0337 // /**
0338 // * Retrieves a named class by its URI.
0339 // *
0340 // * @param theClassURI the URI of the class
0341 // * @return the class with that URI or null if no such class exists
0342 // */
0343 // public OClass getOClass(OURI theClassURI);
0344
0345 /**
0346 * Retrieves a both named classes and anonymous classes and retrictions that
0347 * match either the URI or the blank node identifier represented by ONodeID
0348 * @param theClassID
0349 * @returnthe class matching the URI or blank node ID or null if no matches.
0350 */
0351 public OClass getOClass(ONodeID theClassID);
0352
0353 /**
0354 * Removes a class from this ontology.
0355 *
0356 * @param theClass the class to be removed
0357 */
0358 public void removeOClass(OClass theClass);
0359
0360 /**
0361 * Checks whether a class with the specified URI or blank node ID
0362 * exists in the ontology.
0363 *
0364 * @param theURI a ONodeID, usually an OURI specifying the ID of the
0365 * ontology class
0366 * @return true, if the class exists
0367 */
0368 public boolean containsOClass(ONodeID theURI);
0369
0370 /**
0371 * Checks whether the ontology contains this class.
0372 *
0373 * @param theClass a ontology class object
0374 * @return true, if the class exists, otherwise - false.
0375 */
0376 public boolean containsOClass(OClass theClass);
0377
0378 /**
0379 * Retrieves all ontology classes in a set.
0380 * This method returns a set of either all classes in the ontology or
0381 * just the "top" classes. A "top" class is a class that is not a subclass
0382 * of any other class that is not a predefined system class like owl:Thing
0383 * or rdfs:Resource or a trivial subclass (of itself or of a class that
0384 * is defined to be equivalent to itself).
0385 * <p>
0386 * NOTE: for large ontologies with a large number of classes it may be
0387 * preferable to use method {@link #getOClassesIterator(boolean)} instead.
0388 *
0389 * @param top If set to true, only returns those classes with no super
0390 * classes, otherwise - a set of all classes.
0391 * @return set of all the classes in this ontology
0392 */
0393 public Set<OClass> getOClasses(boolean top);
0394
0395
0396 /**
0397 * Return an iterator to retrieve all ontology classes in the ontology.
0398 * The iterator should be closed() as soon as it is not needed anymore
0399 * but will auto-close when it is exhausted and the hasNext() method
0400 * returned false.
0401 *
0402 * @param top If set to true, only returns those classes with no
0403 * super classes, otherwise all classes
0404 * @return a ClosableIterator for accessing the returned ontology classes
0405 */
0406 public ClosableIterator<OClass> getOClassesIterator(boolean top);
0407
0408
0409 /**
0410 * Gets the taxonomic distance between 2 classes.
0411 *
0412 * @param class1 the first class
0413 * @param class2 the second class
0414 * @return the taxonomic distance between the 2 classes
0415 */
0416 public int getDistance(OClass class1, OClass class2);
0417
0418 // *****************************
0419 // OInstance methods
0420 // *****************************
0421 /**
0422 * Creates a new OInstance and returns it.
0423 *
0424 * @param theInstanceURI
0425 * @param theClass the class to which the instance belongs.
0426 * @return the OInstance that has been added to the ontology.
0427 */
0428 public OInstance addOInstance(OURI theInstanceURI, OClass theClass);
0429
0430 /**
0431 * Removes the instance from the ontology.
0432 *
0433 * @param theInstance to be removed
0434 */
0435 public void removeOInstance(OInstance theInstance);
0436
0437 /**
0438 * Gets all instances in the ontology.
0439 *
0440 * @return a {@link Set} of OInstance objects
0441 * {@link #getOInstanceIterator()} instead
0442 */
0443 public Set<OInstance> getOInstances();
0444
0445 /*
0446 * Return an iterator for accessing all instances in the ontology.
0447 * @return
0448 */
0449 public ClosableIterator<OInstance> getOInstancesIterator();
0450
0451 /**
0452 * Gets instances in the ontology, which belong to this class.
0453 *
0454 * @param theClass the class of the instances
0455 * @param closure either DIRECT_CLOSURE or TRANSITIVE_CLOSURE of
0456 * {@link OConstants}
0457 *
0458 * @return {@link Set} of OInstance objects
0459 */
0460 @Deprecated
0461 public Set<OInstance> getOInstances(OClass theClass, byte closure);
0462
0463 /**
0464 * Gets instances in the ontology, which belong to this class.
0465 * The second parameter specifies if the the given class needs to be
0466 * a direct class of the instance (direct closure)
0467 * or a class to which the instance belongs
0468 * indirectly (transitive closure)
0469 *
0470 * @param theClass the class of the instances
0471 * @param closure either {@link OConstants.Closure.DIRECT_CLOSURE} or
0472 * {@link OConstants.Closure.TRANSITIVE_CLOSURE}
0473 *
0474 * @return {@link Set} of OInstance objects
0475 */
0476 public Set<OInstance> getOInstances(OClass theClass, OConstants.Closure closure);
0477
0478 public ClosableIterator<OInstance>
0479 getOInstancesIterator(OClass theClass, OConstants.Closure closure);
0480
0481 /**
0482 * Gets the instance with the given URI.
0483 *
0484 * @param theInstanceURI the instance URI
0485 * @return the OInstance object with this URI. If there is no such
0486 * instance then null.
0487 */
0488 public OInstance getOInstance(OURI theInstanceURI);
0489
0490 /**
0491 * Checks whether the provided Instance exists in the ontology.
0492 *
0493 * @param theInstance
0494 * @return true, if the Instance exists in ontology, otherwise -
0495 * false.
0496 */
0497 public boolean containsOInstance(OInstance theInstance);
0498
0499 /**
0500 * Checks whether the provided URI refers to an Instance that exists
0501 * in the ontology.
0502 *
0503 * @param theInstanceURI
0504 * @return true, if the URI exists in ontology and refers to an
0505 * Instance, otherwise - false.
0506 */
0507 public boolean containsOInstance(OURI theInstanceURI);
0508
0509 // *****************************
0510 // Property definitions methods
0511 // *****************************
0512 /**
0513 * Creates a new RDFProperty.
0514 *
0515 * @param aPropertyURI URI of the property to be added into the
0516 * ontology.
0517 * @param domain a set of {@link OResource} (e.g. a Class, a Property
0518 * etc.).
0519 * @param range a set of {@link OResource} (e.g. a Class, a Property
0520 * etc.).
0521 * @return
0522 * @deprecated
0523 */
0524 @Deprecated
0525 public RDFProperty addRDFProperty(OURI aPropertyURI, Set<OResource> domain,
0526 Set<OResource> range);
0527
0528 /**
0529 * Gets the set of RDF Properties in the ontology where for a property
0530 * there exists a statement <theProperty, RDF:Type, RDF:Property>.
0531 *
0532 * @return a {@link Set} of {@link Property}.
0533 */
0534 public Set<RDFProperty> getRDFProperties();
0535
0536 /**
0537 * Checkes whether there exists a statement <thePropertyURI, RDF:Type,
0538 * RDF:Property> in the ontology or not.
0539 *
0540 * @param thePropertyURI
0541 * @return true, only if there exists the above statement, otherwise -
0542 * false.
0543 */
0544 public boolean isRDFProperty(OURI thePropertyURI);
0545
0546 /**
0547 * Creates a new AnnotationProperty.
0548 *
0549 * @param aPropertyURI URI of the property to be added into the
0550 * ontology.
0551 * @return
0552 */
0553 public AnnotationProperty addAnnotationProperty(OURI aPropertyURI);
0554
0555 /**
0556 * Gets the set of Annotation Properties in the ontology where for a
0557 * property there exists a statement <theProperty, RDF:Type,
0558 * OWL:AnnotationProperty>.
0559 *
0560 * @return a {@link Set} of {@link AnnotationProperty}.
0561 */
0562 public Set<AnnotationProperty> getAnnotationProperties();
0563
0564 /**
0565 * Checkes whether there exists a statement <thePropertyURI, RDF:Type,
0566 * OWL:AnnotationProperty> in the ontology or not.
0567 *
0568 * @param thePropertyURI
0569 * @return true, only if there exists the above statement, otherwise -
0570 * false.
0571 */
0572 public boolean isAnnotationProperty(OURI thePropertyURI);
0573
0574 /**
0575 * Create a DatatypeProperty with the given domain and range.
0576 *
0577 * The domain must be specified as a set of OClass objects, the resulting
0578 * domain is the intersection of all specified classes.
0579 * <p>
0580 * If this method is called with an OURI of a datatype property that
0581 * already exists, any specified domain class is added to the intersection
0582 * of classes already defined for the domain.
0583 *
0584 * @param aPropertyURI the URI for the new property.
0585 * @param domain the set of ontology classes
0586 * that constitutes the domain for the new property.
0587 * @param aDatatype a DataType object describing the datatype of the range.
0588 * @return the newly created property.
0589 */
0590 public DatatypeProperty addDatatypeProperty(OURI aPropertyURI,
0591 Set<OClass> domain, DataType aDatatype);
0592
0593 /**
0594 * Gets the set of Datatype Properties in the ontology.
0595 *
0596 * @return a {@link Set} of {@link DatatypeProperty}.
0597 */
0598 public Set<DatatypeProperty> getDatatypeProperties();
0599
0600 /**
0601 * Checkes whether the ontology contains a datatype property with the
0602 * given URI.
0603 *
0604 * @param thePropertyURI
0605 * @return true if there is an instance of owl:DatatypeProperty with the
0606 * given URI in the ontology.
0607 */
0608 public boolean isDatatypeProperty(OURI thePropertyURI);
0609
0610 /**
0611 * Creates a new object property (a property that takes instances as
0612 * values).
0613 * <p>
0614 * If this method is called with an OURI of an object property that
0615 * already exists, any specified domain or range class is added to
0616 * the intersection of classes already defined for the domain or range.
0617 *
0618 * @param aPropertyURI the URI for the new property.
0619 * @param domain the set of ontology classes (i.e. {@link OClass}
0620 * objects} that constitutes the domain of the property.
0621 * An instance must belong to the intersection of all classes
0622 * in the set to be a valid member of the domain of the property.
0623 * If an empty set or null is passed, the instance can belong to any
0624 * class.
0625 * @param range the set of ontology classes (i.e. {@link OClass}
0626 * objects} that constitutes the range for the new property. The instance
0627 * that is the value of a property must belong to the intersection of
0628 * all classes in this set to be valid. If an empty set or null is passed
0629 * on, the instance can belong to any class.
0630 * @return the newly created property.
0631 */
0632 public ObjectProperty addObjectProperty(OURI aPropertyURI, Set<OClass> domain,
0633 Set<OClass> range);
0634
0635 /**
0636 * Gets the set of Object Properties in the ontology.
0637 *
0638 * @return a {@link Set} of {@link ObjectProperty}.
0639 */
0640 public Set<ObjectProperty> getObjectProperties();
0641
0642 /**
0643 * Checks if there exists an object property with the given URI
0644 *
0645 * @param thePropertyURI
0646 * @return true, only if there exists an object property with the
0647 * given URI.
0648 */
0649 public boolean isObjectProperty(OURI thePropertyURI);
0650
0651 /**
0652 * Creates a new symmetric property (an object property that is
0653 * symmetric).
0654 * <p>
0655 * If this method is called with an OURI of a datatype property that
0656 * already exists, any specified domainAndRange class is added to the
0657 * intersection of classes already defined for the domain and range.
0658 *
0659 * @param aPropertyURI the URI for the new property.
0660 * @param domainAndRange the set of ontology classes (i.e.
0661 * {@link OClass} objects} that constitutes the domain and
0662 * the range for the new property. The property only applies
0663 * to instances that belong to <b>the intersection of all</b>
0664 * classes included
0665 * in its domain. An empty set means that the property
0666 * applies to instances of any class.
0667 * @return the newly created property.
0668 */
0669 public SymmetricProperty addSymmetricProperty(OURI aPropertyURI,
0670 Set<OClass> domainAndRange);
0671
0672 /**
0673 * Gets the set of Symmetric Properties in the ontology.
0674 *
0675 * @return a {@link Set} of {@link SymmetricProperty}.
0676 */
0677 public Set<SymmetricProperty> getSymmetricProperties();
0678
0679 /**
0680 * Checkes whether there exists a statement <thePropertyURI, RDF:Type,
0681 * OWL:SymmetricProperty> in the ontology or not.
0682 *
0683 * @param thePropertyURI
0684 * @return true, only if there exists the above statement, otherwise -
0685 * false.
0686 */
0687 public boolean isSymmetricProperty(OURI thePropertyURI);
0688
0689 /**
0690 * Creates a new transitive property (an object property that is
0691 * transitive).
0692 * <p>
0693 * If this method is called with an OURI of a transitive property that
0694 * already exists, any specified domain or range class is added to the intersection
0695 * of classes already defined for the domain or range.
0696 *
0697 * @param aPropertyURI the URI for the new property.
0698 * @param domain the set of ontology classes (i.e. {@link OClass}
0699 * objects} that constitutes the range for the new property.
0700 * The property only applies to instances that belong to
0701 * <b>the intersection of all</b> classes included in its domain.
0702 * An empty set
0703 * means that the property applies to instances of any class.
0704 * @param range the set of ontology classes (i.e. {@link OClass}
0705 * objects} that constitutes the range for the new property.
0706 * @return the newly created property.
0707 */
0708 public TransitiveProperty addTransitiveProperty(OURI aPropertyURI,
0709 Set<OClass> domain, Set<OClass> range);
0710
0711 /**
0712 * Gets the set of Transitive Properties in the ontology.
0713 *
0714 * @return a {@link Set} of {@link TransitiveProperty}.
0715 */
0716 public Set<TransitiveProperty> getTransitiveProperties();
0717
0718 /**
0719 * Checkes whether there exists a statement <thePropertyURI, RDF:Type,
0720 * OWL:TransitiveProperty> in the ontology or not.
0721 *
0722 * @param thePropertyURI
0723 * @return true, only if there exists the above statement, otherwise -
0724 * false.
0725 */
0726 public boolean isTransitiveProperty(OURI thePropertyURI);
0727
0728 /**
0729 * Gets the set of RDF, Object, Datatype, Symmetric and Transitive
0730 * property definitions in this ontology.
0731 *
0732 * @return a {@link Set} of {@link RDFProperty},
0733 * {@link DatatypeProperty}, {@link ObjectProperty},
0734 * {@link TransitiveProperty} and , {@link SymmetricProperty}
0735 * objects. <B>Please note that the method does not include
0736 * annotation properties</B>.
0737 */
0738 public Set<RDFProperty> getPropertyDefinitions();
0739
0740 /**
0741 * Returns the property for a given URI or null if there is no property
0742 * with that URI.
0743 *
0744 * @param thePropertyURI the URI of the property
0745 * @return the RDFProperty object or null if no property with that URI is found
0746 */
0747 public RDFProperty getProperty(OURI thePropertyURI);
0748
0749 /**
0750 * Returns the annotation property for the given URI or null if there is
0751 * no annotation property with that URI.
0752 *
0753 * @param theURI the URI of the property
0754 * @return the AnnotationProperty obejct
0755 */
0756 public AnnotationProperty getAnnotationProperty(OURI theURI);
0757
0758 /**
0759 * Returns the datatype property for the given URI or null if there is
0760 * no datatype property with that URI.
0761 *
0762 * @param theURI the URI of the property
0763 * @return the DatatypeProperty obejct
0764 */
0765 public DatatypeProperty getDatatypeProperty(OURI theURI);
0766
0767 /**
0768 * Returns the object property for the given URI or null if there is
0769 * no object property with that URI.
0770 *
0771 * @param theURI the URI of the property
0772 * @return the AnnotationProperty obejct
0773 */
0774 public ObjectProperty getObjectProperty(OURI theURI);
0775
0776
0777 /**
0778 * A method to remove the existing propertyDefinition (exclusive of
0779 * Annotation Property).
0780 *
0781 * @param theProperty
0782 */
0783 public void removeProperty(RDFProperty theProperty);
0784
0785 // *****************************
0786 // Restrictions
0787 // *****************************
0788
0789 /**
0790 * Adds a new MinCardinality Restriction to the ontology. It
0791 * automatically creates a randon anonymous class, which it uses to
0792 * denote the restriction. The default datatype is set to NonNegativeIntegerNumber
0793 *
0794 * @param onProperty - Specifies the property for which the restriction is being set.
0795 * @param minCardinalityValue - generally a numeric number.
0796 * @return
0797 * @throws InvalidValueException - if a value is not compatible with the nonNegativeIntegerNumber datatype.
0798 */
0799 public MinCardinalityRestriction addMinCardinalityRestriction(
0800 RDFProperty onProperty, String minCardinalityValue)
0801 throws InvalidValueException;
0802
0803 /**
0804 * Adds a new MaxCardinality Restriction to the ontology. It
0805 * automatically creates a randon anonymous class, which it uses to
0806 * denote the restriction. The default datatype is set to NonNegativeIntegerNumber
0807 *
0808 * @param onProperty - Specifies the property for which the restriction is being set.
0809 * @param maxCardinalityValue - generally a numeric number.
0810 * @return
0811 * @throws InvalidValueException - if a value is not compatible with the nonNegativeIntegerNumber datatype.
0812 */
0813 public MaxCardinalityRestriction addMaxCardinalityRestriction(
0814 RDFProperty onProperty, String maxCardinalityValue)
0815 throws InvalidValueException;
0816
0817 /**
0818 * Adds a new Cardinality Restriction to the ontology. It
0819 * automatically creates a randon anonymous class, which it uses to
0820 * denote the restriction. The default datatype is set to NonNegativeIntegerNumber
0821 *
0822 * @param onProperty - Specifies the property for which the restriction is being set.
0823 * @param cardinalityValue - generally a numeric number.
0824 * @return
0825 * @throws InvalidValueException - if a value is not compatible with the nonNegativeIntegerNumber datatype.
0826 */
0827 public CardinalityRestriction addCardinalityRestriction(
0828 RDFProperty onProperty, String cardinalityValue)
0829 throws InvalidValueException;
0830
0831 /**
0832 * Adds a new HasValue Restriction to the ontology. It
0833 * automatically creates a randon anonymous class, which it uses to
0834 * denote the restriction.
0835 *
0836 * @param onProperty - Specifies the property for which the restriction is being set.
0837 * @param hasValue - a resource used as a value for hasValue element of the restriction.
0838 * @return
0839 */
0840 public HasValueRestriction addHasValueRestriction(
0841 RDFProperty onProperty, OResource hasValue);
0842
0843 /**
0844 * Adds a new AllValuesFrom Restriction to the ontology.
0845 *
0846 * @param onProperty - Specifies the property for which the restriction is being set.
0847 * @param hasValue - a resource used as a value for hasValue element of the restriction.
0848 * @return
0849 * @deprecated - this method is deprecated and kept for backwards compatibility
0850 * as long as the OntologyOWLIM2 plugin is kept. Use the method
0851 * {@link addAllValuesFromRestriction(ObjectProperty, OClass)} instead.
0852 */
0853 @Deprecated
0854 public AllValuesFromRestriction addAllValuesFromRestriction(
0855 RDFProperty onProperty, OResource hasValue);
0856
0857 public AllValuesFromRestriction addAllValuesFromRestriction(
0858 ObjectProperty onProperty, OClass theClass);
0859
0860
0861 /**
0862 * Adds a new AllValuesFrom Restriction to the ontology. It
0863 * automatically creates a randon anonymous class, which it uses to
0864 * denote the restriction.
0865 *
0866 * @param onProperty - Specifies the property for which the restriction is being set.
0867 * @param hasValue - a resource used as a value for hasValue element of the restriction.
0868 * @return
0869 */
0870 public SomeValuesFromRestriction addSomeValuesFromRestriction(
0871 RDFProperty onProperty, OResource hasValue);
0872
0873
0874 /**
0875 *
0876 * @return
0877 */
0878 public AnonymousClass addAnonymousClass();
0879
0880 // *****************************
0881 // Ontology Modification Events
0882 // *****************************
0883 /**
0884 * Sets the modified flag.
0885 *
0886 * @param isModified sets this param as a value of the modified
0887 * property of the ontology
0888 */
0889 public void setModified(boolean isModified);
0890
0891 /**
0892 * Checks the modified flag.
0893 *
0894 * @return whether the ontology has been modified after the loading
0895 */
0896 public boolean isModified();
0897
0898 /**
0899 * Register the Ontology Modification Listeners
0900 *
0901 * @param oml
0902 */
0903 public void addOntologyModificationListener(OntologyModificationListener oml);
0904
0905 /**
0906 * Removed the registered ontology modification listeners
0907 *
0908 * @param oml
0909 */
0910 public void removeOntologyModificationListener(
0911 OntologyModificationListener oml);
0912
0913 /**
0914 * A method to invoke when a resource's property value is changed
0915 *
0916 * @param resource
0917 * @param property
0918 * @param value
0919 * @param eventType
0920 */
0921 public void fireResourcePropertyValueChanged(OResource resource, RDFProperty property, Object value, int eventType);
0922
0923 /**
0924 * A method to invoke when a resource's property value is changed
0925 *
0926 * @param resource1
0927 * @param resource2
0928 * @param eventType
0929 */
0930 public void fireResourceRelationChanged(OResource resource1, OResource resource2,int eventType);
0931
0932 /**
0933 * A Method to invoke an event for newly added ontology resource
0934 *
0935 * @param resource
0936 */
0937 public void fireOntologyResourceAdded(OResource resource);
0938
0939 /**
0940 * A Method to invoke an event for a removed ontology resource
0941 *
0942 * @param resources
0943 */
0944 public void fireOntologyResourcesRemoved(String[] resources);
0945
0946 /**
0947 * A method to invoke when the ontology is reset.
0948 *
0949 */
0950 public void fireOntologyReset();
0951
0952 // *************************
0953 // Sesame Repository methods
0954 // *************************
0955 /**
0956 * Start the transaction before additing statements.
0957 */
0958
0959 /**
0960 * Commit all changes to the ontology.
0961 * This will commit all changesall the transaction (so far included after the call to
0962 * start transaction) into the repository.
0963 *
0964 * @deprecated
0965 */
0966 @Deprecated
0967 public void commitTransaction();
0968
0969 /**
0970 * Checks whether the transation is already started.
0971 *
0972 * @return
0973 * @deprecated
0974 */
0975 @Deprecated
0976 public boolean transationStarted();
0977
0978 /**
0979 * Returns the repository created for this particular instance of the
0980 * ontology.
0981 *
0982 * @return
0983 * @deprecated
0984 */
0985 @Deprecated
0986 public Object getSesameRepository();
0987
0988 /**
0989 * Returns the ID of a Sesame Repository created for this particular
0990 * instance of the ontology.
0991 *
0992 * @return
0993 * @deprecated
0994 */
0995 @Deprecated
0996 public String getSesameRepositoryID();
0997
0998
0999
1000 /**
1001 * Given a URI object, this method returns its equivalent object
1002 *
1003 * @param uri
1004 * @return
1005 * @deprecated
1006 */
1007 @Deprecated
1008 public OResource getOResourceFromMap(String uri);
1009
1010 /**
1011 * Adds the resource to central map
1012 *
1013 * @param uri
1014 * @param resource
1015 * @deprecated
1016 */
1017 @Deprecated
1018 public void addOResourceToMap(String uri, OResource resource);
1019
1020 /**
1021 * Removes the resource from the central map
1022 *
1023 * @param uri
1024 * @deprecated
1025 */
1026 @Deprecated
1027 public void removeOResourceFromMap(String uri);
1028
1029 /**
1030 * This method checks in its cache to find out the OResource for the
1031 * given resource name. However, It is also possible for two resources
1032 * to have a same name but different name spaces. This method returns
1033 * the first found OResource (without gurantteeing the order) from its
1034 * list. If user wants to retrieve a list of resources, he/she must
1035 * use the getOResourcesByName(String resourceName).
1036 *
1037 * @param resourceName
1038 * @return
1039 * @deprecated
1040 */
1041 @Deprecated
1042 public OResource getOResourceByName(String resourceName);
1043
1044 /**
1045 * This method checks in its cache to find out the OResources for the
1046 * given resource name. It is possible for two resources to have a
1047 * same name but different name spaces. This method returns a list of
1048 * resources with the common name. Please note that deleting an
1049 * instance from this list (e.g. list.remove(int/Object)) does not
1050 * delete the resource from an ontology. One must use appropriate
1051 * method from the Ontology interface to delete such resources.
1052 *
1053 * @param resourceName
1054 * @return
1055 * @deprecated
1056 */
1057 public List<OResource> getOResourcesByName(String resourceName);
1058
1059 /**
1060 * This method returns a list of OResources from the ontology. Please
1061 * note that deleting an instance from this list (e.g.
1062 * list.remove(int/Object)) does not delete the resource from an
1063 * ontology. One must use appropriate method from the Ontology
1064 * interface to delete such resources.
1065 *
1066 * @return
1067 * @deprecated
1068 */
1069 @Deprecated
1070 public List<OResource> getAllResources();
1071
1072 /**
1073 * This method given a property (either an annotation or datatype),
1074 * retrieves a list of resources which have the provided literal set
1075 * as a value.
1076 *
1077 * @param aProperty
1078 * @param aValue
1079 * @return
1080 */
1081 public List<OResource> getOResourcesWith(RDFProperty aProperty, Literal aValue);
1082
1083 /**
1084 * This method given a property (either object, transitive, symmetric
1085 * or rdf), retrieves a list of resources which have the provided
1086 * resource set as a value.
1087 *
1088 * @param aProperty
1089 * @param aValue
1090 * @return
1091 */
1092 public List<OResource> getOResourcesWith(RDFProperty aProperty,
1093 OResource aValue);
1094
1095 /**
1096 * The method executes the query on repository and returns the toString()
1097 * result of the QueryResultTable.
1098 * @param serqlQuery
1099 * @return
1100 *
1101 * @deprecated As of release 1.3, replaced by {@link #createQuery()}
1102 */
1103 @Deprecated
1104 public String executeQuery(String serqlQuery);
1105
1106 /**
1107 * This method creates a OntologyTupleQuery object and passes on
1108 * the specified query string in the specified query language.
1109 *
1110 * @param theQuery a String representing the tuple query.
1111 * @param queryLanguage the query language, either SERQL or SPARQL
1112 * @return the OntologyTurpleQuery object that can be used to retrieve
1113 * the matching tuples in several formats. The query object can be re-used
1114 * with different variable bindings.
1115 */
1116 public OntologyTupleQuery createTupleQuery(String theQuery, QueryLanguage queryLanguage);
1117
1118 /**
1119 * This method creates a OntologyBooleanQuery object and passes on the
1120 * specified query string and the specified query language.
1121 *
1122 * @param theQuery a String representing the tuple query.
1123 * @param queryLanguage the query language, either SERQL or SPARQL
1124 * @return the OntologyBooleanQuery object that can be used to retrieve
1125 * the boolean answer for the query. The query object can be re-used
1126 * with different variable bindings.
1127 */
1128 public OntologyBooleanQuery createBooleanQuery(String theQuery, QueryLanguage queryLanguage);
1129
1130 /**
1131 * Create an ORUI object from the given URI string.
1132 *
1133 * @param theURI an URI or IRI string
1134 * @return the OURI object representing the URI/IRI
1135 */
1136 public OURI createOURI(String theURI);
1137
1138 /**
1139 * Create an OURI from the given resource name, using the ontology base URI
1140 * (default name space). This method will throw an exception if no
1141 * default name space is set (i.e. if the method getDefaultNameSpace would
1142 * return null).
1143 *
1144 * @param resourceName the resource name i.e. the part of the final URI/IRI
1145 * that is attached to the base URI (aftaer a trailing "#" or "/").
1146 * @return the OURI
1147 */
1148 public OURI createOURIForName(String resourceName);
1149
1150
1151 /** Generate a new unique OURI for this ontology.
1152 * This generates a new OURI that is guaranteed to be unique in the
1153 * ontology, using the specified resource name string as a prefix for the
1154 * URI's fragement identifier and the current defaultNameSpace of the
1155 * ontology as a base URI.
1156 * The resource name can be null or the empty string if no prefix is
1157 * wanted.
1158 * <p>
1159 * The URI fragment part that is appended to the given resourceName (if any)
1160 * consists of 7 ASCII characters representing the system time in radix 36
1161 * followed by 3 ASCII characters representing a random number.
1162 * <p>
1163 * Note that this method will return an OURI that is guaranteed not
1164 * to be contained in the ontology, but if called repeatedly without
1165 * actually adding a resource with the newly generated OURI to the ontology,
1166 * the method might, although extremely unlikely,
1167 * still return the same OURI more than once. Generated OURIs should hence
1168 * been used for adding resources before more OURIs are generated.
1169 *
1170 * @param resourceNamePrefix the prefix to use for the generated resource
1171 * name
1172 * @return a OURI object for an URI that is new and unique in the ontology
1173 */
1174 public OURI generateOURI(String resourceNamePrefix);
1175
1176 /** Generate a new unique OURI for this ontology.
1177 * This works in the same way as {@link #generateOURI(java.lang.String) }
1178 * but also allows the specification of the base URI part of the final
1179 * URI.
1180 *
1181 * @param resourceNamePrefix the prefix to use for the generated resource name
1182 * @param baseURI the base URI to use for the final URI
1183 * @return a OURI object for an URI that is new and unique in the ontology
1184 */
1185 public OURI generateOURI(String resourceNamePrefix, String baseURI);
1186
1187 }
|