View source for ProtegeOWL API Advanced Topics

''Main article: [[ProtegeOWL_API_Programmers_Guide]]''


__TOC__


== Advanced Topics ==

=== Querying the OWLModel ===

While most of the examples so far were used to create resources in an '''OWLModel''', we will now look at how to query and traverse the contents of an ontology. The following code iterates through all user-defined named classes in the "travel.owl" ontology and prints their instances:


<pre>
String uri = "http://protege.cim3.net/file/pub/ontologies/travel/travel.owl";

//alternatively, you can specify a local path on your computer
//for the travel.owl ontology. Example:
//String uri = "file:///c:/Work/Projects/travel.owl"

OWLModel owlModel = ProtegeOWL.createJenaOWLModelFromURI(uri);

Collection classes = owlModel.getUserDefinedOWLNamedClasses();
for (Iterator it = classes.iterator(); it.hasNext();) {
    OWLNamedClass cls = (OWLNamedClass) it.next();
    Collection instances = cls.getInstances(false);
    System.out.println("Class " + cls.getBrowserText() + " (" + instances.size() + ")");
    for (Iterator jt = instances.iterator(); jt.hasNext();) {
        OWLIndividual individual = (OWLIndividual) jt.next();
        System.out.println(" - " + individual.getBrowserText());
    }
}
</pre>


This program produces the following output (using the "travel.owl" ontology):


<pre>
Class Town (1)
 - Coonabarabran
Class UrbanArea (0)
Class Destination (0)
Class RuralArea (2)
 - CapeYork
 - Woomera
Class QuietDestination (0)
Class FamilyDestination (0)
...
</pre>


Note that the '''OWLModel''' contains many more classes than those returned by the '''getUserDefined...''' methods. These methods filter out the system resources such as the '''owl:Class''' metaclass, '''owl:Thing''' and '''rdfs:subClassOf'''. If you want to access other resources by their names, you can easily use methods such as [http://protege.stanford.edu/protege/3.4/docs/api/owl/edu/stanford/smi/protegex/owl/model/OWLModel.html#getOWLNamedClass(java.lang.String) OWLModel.getOWLNamedClass()] or [http://protege.stanford.edu/protege/3.4/docs/api/owl/edu/stanford/smi/protegex/owl/model/OWLModel.html#getOWLObjectProperty(java.lang.String) OWLModel.getOWLObjectProperty()].

In summary, the OWLModel class provides access to all the resources in the model. After you have gained access to the resource objects via the OWLModel, you can then call other getter methods.

To a certain extent, other types of queries are also supported. For example, you can use [http://protege.stanford.edu/protege/3.4/docs/api/owl/edu/stanford/smi/protegex/owl/model/OWLModel.html#getRDFResourcesWithPropertyValue(edu.stanford.smi.protegex.owl.model.RDFProperty,%20java.lang.Object) OWLModel.getRDFResourcesWithPropertyValue()] to get all resources that have a certain property value. These properties can also be system properties, and the next example code snippet performs a query of all resources that have owl:Thing as their superclass:


<pre>
RDFProperty subClassOfProperty = owlModel.getRDFProperty(RDFSNames.Slot.SUB_CLASS_OF);
OWLNamedClass owlThingClass = owlModel.getOWLThingClass();
Collection results = owlModel.getRDFResourcesWithPropertyValue(subClassOfProperty, owlThingClass);
System.out.println("Subclasses of owl:Thing:");
for (Iterator it = results.iterator(); it.hasNext();) {
    RDFResource resource = (RDFResource) it.next();
    System.out.println(" - " + resource.getBrowserText());
}
</pre>


For more advanced queries in languages like RDQL, you need to use external libraries as there is currently no native support in Protege-OWL for them. For example, you could access a Jena '''OntModel''' on the fly and then perform queries on this OntModel. Instructions for accessing the Jena model are provided later.


=== RDF(S) and OWL ===

The Protege-OWL API is not limited to OWL. Since OWL is an extension of RDF Schema, the API also has native support for handling all relevant RDF elements. In particular, it is possible to create and query pure RDF files, using classes such as '''RDFSNamedClass''', '''RDFProperty''', and '''RDFIndividual''' instead of their OWL-specific extensions. It is also easy to create hybrid solutions that make use of selected OWL features to overcome limitations of pure RDF. For example, you can assign union classes as ranges or domains to an '''RDFProperty'''.

The following code snippet shows a typical sequence for creating an RDF ontology:

<pre>
    JenaOWLModel owlModel = ProtegeOWL.createJenaOWLModel();

    RDFSNamedClass personClass = owlModel.createRDFSNamedClass("Person");
    RDFProperty ageProperty = owlModel.createRDFProperty("age");
    ageProperty.setRange(owlModel.getXSDint());
    ageProperty.setDomain(personClass);

    RDFIndividual individual = personClass.createRDFIndividual("Holger");
    individual.setPropertyValue(ageProperty, new Integer(33));

    Jena.dumpRDF(owlModel.getOntModel());
</pre>

The resulting output is the following OWL/RDF file:

<pre>
    <?xml version="1.0"?>
    <rdf:RDF
      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema#"
      xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
      xmlns:owl="http://www.w3.org/2002/07/owl#"
      xmlns="http://www.owl-ontologies.com/unnamed.owl#"
      xml:base="http://www.owl-ontologies.com/unnamed.owl">
      <owl:Ontology rdf:about=""/>
      <rdfs:Class rdf:ID="Person"/>
      <rdf:Property rdf:ID="age">
        <rdfs:domain rdf:resource="#Person"/>
        <rdfs:range rdf:resource="http://www.w3.org/2001/XMLSchema#int"/>
      </rdf:Property>
      <Person rdf:ID="Holger">
        <age rdf:datatype="http://www.w3.org/2001/XMLSchema#int">33</age>
      </Person>
    </rdf:RDF>
</pre>

If the '''owl:Ontology''' tag is not desired in the output, it can be easily stripped from the Jena model before the file is saved.

=== Reacting to Changes using Listeners ===

The Protege-OWL API supports the typical Model-view-controller architecture. This means that the model stores the representation of the ontology data, and changes in that model trigger events which external components such as UI widgets can react to. The OWL API follows the typical observer design pattern known from Swing and other UI libraries to implement such event mechanisms. Here is a trivial example, which reacts on instance creation for a given class:

<pre>
    OWLNamedClass cls = owlModel.createOWLNamedClass("Class");
    cls.addClassListener(new ClassAdapter() {
        public void instanceAdded(RDFSClass cls, RDFResource instance) {
            System.out.println("Instance was added to class: " + instance.getName());
        }
    });

    for(int i = 0; i < 5; i++) {
        String newName = "Individual" + (int)(Math.random() * 10000);
        cls.createOWLIndividual(newName);
    }
</pre>

The basic idea is that a dedicated object called a listener registers with the model and from then on will receive notifications about changes in that object. In the example above, the listener is an instance of the '''[http://protege.stanford.edu/protege/3.4/docs/api/owl/edu/stanford/smi/protegex/owl/model/event/ClassListener.html ClassListener]''' interface, which is registered at the given named class. Other listener types are '''[http://protege.stanford.edu/protege/3.4/docs/api/owl/edu/stanford/smi/protegex/owl/model/event/PropertyListener.html PropertyListener]''' (for property-related events), '''[http://protege.stanford.edu/protege/3.4/docs/api/owl/edu/stanford/smi/protegex/owl/model/event/PropertyValueListener.html PropertyValueListener]''' (for arbitrary property value changes at any resource), and '''[http://protege.stanford.edu/protege/3.4/docs/api/owl/edu/stanford/smi/protegex/owl/model/event/ResourceListener.html ResourceListener]''' for type changes of a resource. There is also a very powerful listener type '''[http://protege.stanford.edu/protege/3.4/docs/api/owl/edu/stanford/smi/protegex/owl/model/event/ModelListener.html ModelListener]''', which can be used to detect changes the affect the OWLModel in general, e.g., if a new class is created. This is demonstrated in the following code snippet:

<pre>
    owlModel.addModelListener(new ModelAdapter() {
        public void propertyCreated(RDFProperty property) {
            System.out.println("Property created: " + property.getName());
        }
    });

    owlModel.createRDFProperty("RDF-Property");
    owlModel.createOWLObjectProperty("Object-Property");
    owlModel.createOWLDatatypeProperty("Datatype-Property");
</pre>

The code shown above will print out three lines after each create statement. The main trick here is that event handling can be completely decoupled. This is typically used in interactive user interfaces, where an action is required after a user has done a certain action, but it is not known in advance when the user will perform the action.

=== Loading and Saving Files ===

The Protégé-OWL API can be used in two storage modes:

* OWL Files mode (class [http://protege.stanford.edu/protege/3.4/docs/api/owl/edu/stanford/smi/protegex/owl/jena/JenaOWLModel.html JenaOWLModel])
* OWL Database mode (class [http://protege.stanford.edu/protege/3.4/docs/api/owl/edu/stanford/smi/protegex/owl/database/OWLDatabaseModel.html OWLDatabaseModel])

Both modes operate on the same '''OWLModel''' core interface. Method calls to do things like create classes are totally independent from the storage mode. Programmers do not have to care whether the class is physically created in a database or only kept in memory. There are some subtle differences between the two modes as both have some extra functions.

OWL Files mode is based on the '''JenaOWLModel''' class. You can use the static methods from the '''ProtegeOWL''' class to load an existing OWL file from a stream or a URL. The calls will return a '''JenaOWLModel''', and you can then use the save methods in the '''JenaOWLModel''' to write the file back to disk:

<pre>
   String uri = "http://protege.cim3.net/file/pub/ontologies/travel/travel.owl";
    //alternatively, you can specify a local path on your computer
    //for the travel.owl ontology. Example:
    //String uri = "file:///c:/Work/Projects/travel.owl"
    JenaOWLModel owlModel = ProtegeOWL.createJenaOWLModelFromURI(uri);

    OWLNamedClass destinationClass = owlModel.getOWLNamedClass("Destination");
    // ...

    String fileName = "travel-saved.owl";
    Collection errors = new ArrayList();
    owlModel.save(new File(fileName).toURI(), FileUtils.langXMLAbbrev, errors);
    System.out.println("File saved with " + errors.size() + " errors.");
</pre>

=== Working with Multi-File Projects and TripleStores ===

OWL ontologies can import other ontologies and thus establish relationships between resources from multiple files. For example, it is a common design pattern to keep instance data separate from classes and properties. In this case, the instances ontology would import the ontology that defines the classes. The Protégé user interface allows users to switch the "active" sub-ontology, so that users can select which file changes will be propogated to.

Protégé stores OWL ontologies in triple tables, one table for each file. These tables are now named after the Java interface [http://protege.stanford.edu/protege/3.4/docs/api/owl/edu/stanford/smi/protegex/owl/model/triplestore/TripleStore.html TripleStore]. Each '''OWLModel''' manages a list of '''TripleStores''' by means of its [http://protege.stanford.edu/protege/3.4/docs/api/owl/edu/stanford/smi/protegex/owl/model/triplestore/TripleStoreModel.html TripleStoreModel]. An empty project has two '''TripleStores''': The system '''TripleStore''' containing the system classes such as '''owl:Class''', and the main '''TripleStore'''. If your project imports other ontologies, you can change the active '''TripleStore''' using the corresponding '''TripleStoreModel''' methods.

When you save your project, the saver will overwrite all files that have an alternative file:-entry in the ont-policy file, and which are declared to be editable.

=== Working with Jena models ===

Protégé-OWL uses the popular [http://jena.sourceforge.net/ Jena] API for various tasks, in particular for parsing of OWL/RDF files. Furthermore, the Protégé-OWL API can be used to generate a '''Jena OntModel''' at any time. Both '''JenaOWLModel''' and '''OWLDatabaseModel''' implement the [http://protege.stanford.edu/protege/3.4/docs/api/owl/edu/stanford/smi/protegex/owl/jena/OntModelProvider.html OntModelProvider]  interface, which has a [http://protege.stanford.edu/protege/3.4/docs/api/owl/edu/stanford/smi/protegex/owl/jena/OntModelProvider.html#getOntModel() getOntModel()]  method to create an '''OntModel''' from the current ontology.

<pre>
   JenaOWLModel owlModel = ProtegeOWL.createJenaOWLModel();

    OWLNamedClass cls = owlModel.createOWLNamedClass("Class");
    OWLDatatypeProperty property = owlModel.createOWLDatatypeProperty("property");
    OWLIndividual individual = cls.createOWLIndividual("Individual");

    OntModel ontModel = owlModel.getOntModel();
    OntClass ontClass = ontModel.getOntClass(cls.getURI());
    DatatypeProperty ontProperty = ontModel.getDatatypeProperty(property.getURI());
    Individual ontIndividual = ontModel.getIndividual(individual.getURI());
</pre>

As an application programmer, you are free to do arbitrary operations on the resulting '''OntModel'''. In particular you can use any Jena-based services such as querying or saving files. Note however, that you currently need to call '''getOntModel()''' after each change if you want to have an '''OntModel''' that is synchronized with the current '''OWLModel'''. This may be a time consuming procedure for large ontologies.