Mindswap

Maryland Information and Network Dynamics Lab Semantic Web Agents Project

Contents

1. API javadocs

2. Service examples

3. Reading/writing service descriptions

4. Translating older service descriptions

5. OWL-S Validation

6. Loading cached ontologies

7. Executing services

8. Execution monitoring

9. Creating composite processes

10. Using OWL resources

11. WSDL support

Tutorial

1. API javadocs

   The javadocs of the API is included in the distribution file. You can access the online version here.

2. Service examples

   There are couple of example OWL-S files here http://www.mindswap.org/2004/owl-s/services.shtml. These services are all grounded in actual WSDL services and can be executed with the API. These are simple service descriptions to show different features in OWL-S such as how to define XSLT transformations in groundings, how to define CompositeProcesses and data flows and so on.

   The examples directory in the distribution file contains example code that shows how to use these service descriptions in the API.

    

3. Reading/writing service descriptions

   There are two important interfaces in the OWL-S API: OWLOntology and OWLKnowledgeBase. OWLOntology represents the information stored in a single file and an OWLKnowledgeBase is a collection of ontologies. RDF data (triples) can only be added to OWLOntology objects and only OWLOntology objects can be serialized. There is one base ontology associated with each KB that is used to store data (for example after execution new instances will be added to this ontology).

   OWLKnowledgeBase.read(URI) function reads the file from the given ontology and loads the generated OWLOntology to the KB. OWLOntology.getService() can be used to get the service instance from the ontology (OWLOntology.getServices() if there are multiple services). OWLKnowledgeBase.readService(URI) (and resp. OWLKnowledgeBase.readServices(URI)) function will automatically do that. If an error occurs during parsing these functions will return null value. See next section about validation to get more info about catching these problems.

   The ontology associated with a service can be serialized using OWLOntology.write(Writer) function.

   // create a URI for the service (note that this is a 0.9 version file)        URI uri = new URI("http://www.mindswap.org/2004/owl-s/0.9/ZipCodeFinder.owl");     // create a KB       OWLKnowledgeBase kb = OWLFactory.createKB();     // create a generic reader and a 1.0 writer     OWLOntology ont = kb.read(uri;          // get the service     Service service = ont.getService();          // write the output to console (a file stream can also be used here)     ont.write(System.out);

    

4. Translating older service descriptions

   There is limited support for older versions of OWL-S. Currently, API natively supports 1.1 version and provides translators for 1.0 version. Translation should be enabled with the OWLKnowledgeBase.setAutoTranslate(true) function call.

    

5. OWL-S Validation

   The validation feature has not yet been implemented.

    

6. Loading cached ontologies

   Sometimes it is desirable to use cached versions of the files rather than downloading the remote files. The OWLCache class provides the functionality for this purpose.  OWLCache.setLocalCacheDirectory(String) specifies a directory to find the cached files. The cache dir should include a file named service.idx that has the mappings from URI's to local file names. This index file is a text file where each line is in the format

       [service description url]=[local filename]

   The ':' characters in the url's should be escaped as "\:". See Properties.load() for more details about the file format. You may choose to add file entries one by one using the OWLCache.addCachedFile() function. When there is a cache entry for a file, the cached version is only used when the original file cannot be found (e.g. no connection). It is also possible to give more priority to cached files and try to get the remote file only if there is no cached version. See OWLCache.setForced(boolean) for this functionality. Remember to include an xml:base statement in your cached files so that URIs generated from your local file will be exactly same as the remote one.

   There is one OWLCache assocaited with each OWLReader. OWLKnowledgeBase.getReader().getCache() will return the cache assocaited with a KB.

    

7. Executing services

   Executing a service means executing the process it has. The process should have a valid grounding specification in order to invoke the service successfully. The WSDL and UPnP groundings are supported by the API. A process is executed by the ProcessExecutionEngine.execute(Process, ValueMap) function where second parameter specifies the values for input parameters.  This function returns another ValueMap which contains the output value bindings. The following code segment shows an example of executing a service:

   // create an execution engine      ProcessExecutionEngine exec = OWLSFactory.createExecutionEngine();     // load the service description     Service service = kb.readService("http://www.mindswap.org/2004/owl-s/1.0/Dictionary.owl");     // get the process of the service     Process process = service.getProcess();     // create an empty value map     ValueMap values = new ValueMap();          // set the value of input parameter     values.setDataValue(process.getInput("InputString"), "computer");         // execute the process with the given input bindings     values = exec.execute(process, values);            // get the output value as a string     String outValue = values.getStringValue(process.getOutput());          // display the result     System.out.println("Output = " + outValue);

   
   The above is a simple example where the input is a simple XML Schema string. However, some services will have complex input types that are represented by OWL classes. In this case, the value of input parameter can be set to an OWLIndividual. See RunService.java in the examples directory for more examples of this kind.
    

8. Execution monitoring

   It is possible to see the progress of execution when a complex service is being executed. ProcessExecutionListener defines a set of minimal functions for this purpose. simply use the ProcessExecutionEngine.addExecutionListener(ProcessExecutionListener) to set a listener on the execution engine. See RunService.java in the examples directory for examples of how to use the listener.
    

9. Creating composite processes

   It is possible to create service descriptions, profiles or processes programmatically. OWLOntology provides functions to create any of these structures. CreateSequence.java in the examples directory shows an example of how to do this. The following code snippet shows the main idea:

   /**    *     * Create a new Sequence from the processes of the given services and put them in a new    * Service.    *     * @param services List of Services    * @param baseURI The base URI for the generated service    * @return The Service which is a Sequence of the given services     */   Service createSequenceService(List services, String baseURI) {        // create an empty ontology     OWLOntology ont = OWLFactory.createOntology();     // create a new service     Service service = ont.createService(URI.create(baseURI + "Service"));     // create a new composite process      CompositeProcess process = ont.createCompositeProcess(URI.create(baseURI + "Process"));          // create a new sequence construct     Sequence sequence = ont.createSequence();     // put the sequence into composite process      compositeProcess.setComposedOf(sequence);          for(int i = 0; i < services.size(); i++) {         // get the service from the list       Service s = (Service) services.get(i);       // get the process fron the service       Process p = s.getProcess();              // create a perform construct       Perform perform = ont.createPreform();       perform.setProcess(p);       // put the process into the sequence       sequence.addComponent(p);       // create data flow if necessary...      }     // create profile...     // create grounding      return service;   }

   
    

10. Using OWL resources

    Every resource in the API (Service, Profile, Process, etc.) extends OWLIndividual which provides the basic functionalities to get and set object and data properties for any OWL individual. If additional information is required about the resources then the underlying RDF model can be queried. OWLIndividual.getImplementation() returns the implementation specific object. Right now, API is built on top of Jena so the function will return the corresponding Resource in the Jena model.

    In the future releases it is planned to add support for OWL API.
     

11. WSDL Support

    The API contains a package org.mindswap.owls.wsdl that provides support for reading and executing WSDL services. Execution of OWL-S services is achieved through this package. The WSDL functionality is based on Axis package version 1.1. The main functionality added to Axis is the ability to execute services with complex inputs dynamically without a need to create stubs or extra code. The SOAP messages are created from the string representation of XML Schema complex type. This invocation method is not robust but works for most of the cases.