index.html revision 2
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<link media="screen" href="http://www.mindswap.org/css/swap.css" type="text/css" rel="stylesheet" title="normal"/><link media="screen" href="http://www.mindswap.org/css/mind.css" type="text/css" rel="alternate stylesheet" title="none"/><meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="ICBM" content="38.99358387,-76.93262615"/>
<title>OWL-S @ MINDSWAP</title>
</head>
<body>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<!--HTML-->
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Semantic Web Research Group</title>
<link media="screen" href="/css/swap.css" type="text/css" rel="stylesheet" title="normal"/><link media="screen" href="/css/mind.css" type="text/css" rel="alternate stylesheet" title="none"/><meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="ICBM" content="38.99358387,-76.93262615"/>
</head>
<body>
<div id="wholePageHeader">
<div id="pageHeader">
<div id="logo"></div>
<h1 class="headingTitle">Mindswap</h2>
<h2 class="headingSubtitle">Maryland Information and Network Dynamics Lab Semantic Web Agents Project </h2>
</div>
<div class="menu"><ul>
</ul></div>
</div>
<div id="mainContent">
<div id="floatedLogo"></div>
<div id="mainContentInner">
<h2>Contents</h2>
<ol>
<li><h5><a href="#javadocs">API javadocs</a></h5></li>
<li><h5><a href="#services">Service examples</a></h5></li>
<li><h5><a href="#translation">Translating older service descriptions</a></h5></li>
<li><h5><a href="#validation">OWL-S Validation</a></h5></li>
<li><h5><a href="#cache">Loading cached ontologies</a></h5></li>
<li><h5><a href="#exec">Executing services</a></h5></li>
<li><h5><a href="#monitor">Execution monitoring</a></h5></li>
<li><h5><a href="#composite">Creating composite processes</a></h5></li>
<li><h5><a href="#owl">Using OWL resources</a></h5></li>
<li><h5><a href="#wsdl">WSDL support</a></h5></li>
</ol>
<h2>Tutorial</h2>
<ol>
<li><h5><a name="javadocs">API javadocs</a></h5>
<p>The javadocs of the API is included in the distribution file. You can access the online version
</p>
</li>
<li><h5><a name="#services">Service examples</a></h5>
<p>There are couple of example OWL-S files here <a href="http://www.mindswap.org/2004/owl-s/services.shtml">http://www.mindswap.org/2004/owl-s/services.shtml</a>.
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.</p>
<p>The examples directory in the distribution file contains example code that shows how to use these service
descriptions in the API.</p>
<p> </p>
</li>
<p>There are two important interfaces in the OWL-S API:
<font face="Courier New">
<font face="Courier New">
<a href="javadoc/org/mindswap/owl/OWLKnowledgeBase.html">OWLKnowledgeBase</a></font>. 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). </p>
<p>
<code>
<a href="javadoc/org/mindswap/owl/OWLKnowledgeBase.html#read(java.net.URI)">OWLKnowledgeBase.read(URI)</a></code> function reads the file from the
given ontology and loads the generated OWLOntology to the KB.
<a href="javadoc/org/mindswap/owl/OWLOntology.html#getService()">
<font face="Courier New">OWLOntology.getService()</font> </a>can be used to get the service instance from the
ontology (<font face="Courier New"><a href="javadoc/org/mindswap/owl/OWLOntology.html#getServices()">OWLOntology.getServices()</a></font> if there are multiple services).
<code>
<font face="Courier New">OWLKnowledgeBase.readService(URI)</font></a><font face="tahoma, arial, sans-serif">
</font> </code>(and resp.
<code>
<font face="Courier New">OWLKnowledgeBase.readServices(URI)</font></a><font face="tahoma, arial, sans-serif">) function will automatically do that.
</font> </code>If an error occurs
during parsing these functions will return null value. See next section about
<a href="##validation">validation</a> to get more info about catching these
problems.</p>
<p>The ontology associated with a service can be serialized using
<font face="Courier New">
<!-- ======================================================== -->
<!-- = Java Sourcecode to HTML automatically converted code = -->
<!-- = Java2Html Converter V4.0 2004 by Markus Gebhard markus@jave.de = -->
<!-- = Further information: http://www.java2html.de = -->
<div align="left" class="java">
<div align="center">
<center>
<table border="2" cellpadding="3" cellspacing="0" bgcolor="#ffffff" width="60%" style="border-collapse: collapse" bordercolor="#111111">
<tr>
<!-- start source code -->
<td nowrap="nowrap" valign="top" align="left">
<code>
<font color="#3f7f5f"> // create a URI for the service (note
that this is a 0.9 version file) </font>
<font color="#ffffff"> </font><br/>
<font color="#ffffff"> </font><font color="#000000">URI uri = </font><font color="#7f0055"><b>new </b></font><font color="#000000">URI(</font></code><font SIZE="2" COLOR="#2a00ff">"http://www.mindswap.org/2004/owl-s/0.9/ZipCodeFinder.owl"</font><code><font color="#000000">);</font></code><p>
<code>
<font color="#3f7f5f"> // create a KB</font><font color="#ffffff"> </font><br/>
<font color="#000000"> OWLKnowledgeBase kb =
OWLFactory.createKB();<br>
</font><br/>
<font color="#3f7f5f"> // create a generic reader and a 1.0
writer<br>
</font>
<font color="#ffffff"> </font><font color="#000000">OWLOntology ont = kb.read(uri;</font><br/>
<font color="#ffffff"> </font><br/>
<font color="#3f7f5f"> // get the service<br>
</font>
<font color="#ffffff"> </font><font color="#000000">Service service = ont.getService();<br>
</font>
<font color="#ffffff"> </font><br/>
<font color="#3f7f5f"> // write the output to console (a file
stream can also be used here)<br>
</font>
<font color="#ffffff"> </font><font color="#000000">ont.write(System.out);</font><br/>
</code></td>
<!-- end source code -->
</tr>
<!-- start Java2Html link -->
<!-- end Java2Html link -->
</table>
</center>
</div>
</div>
<!-- = END of automatically generated HTML code = -->
<!-- ======================================================== -->
<p> </p>
</li>
<li><h5><a name="#translation">Translating older service descriptions</a></h5>
<p>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.</p>
<p> </p>
</li>
<li><h5><a name="#validation">OWL-S Validation</a></h5>
<p>The validation feature has not yet been implemented.</p>
<p> </p>
<p>
</p>
</li>
<li><h5><a name="#cache">Loading cached ontologies</a></h5>
<p>Sometimes it is desirable to use cached versions of the files rather than
downloading the remote files. The
<a href="javadoc/org/mindswap/owl/OWLCache.html">
OWLCache</a> class provides the functionality for this purpose.
<font face="Courier New">
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 </p>
<p> [service description url]=[local filename] </p>
<p>The ':' characters in the url's should be escaped as "\:". See
<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Properties.html#load(java.io.InputStream)">
to add file entries one by one using the
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
xml:base statement in your cached files so that URIs generated from your local
file will be exactly same as the remote one.</p>
<p>There is one OWLCache assocaited with each OWLReader.
OWLKnowledgeBase.getReader().getCache() will return the cache assocaited with
a KB.</p>
<p> </p>
<p>
</p>
</li>
<li><h5><a name="#exec">Executing services</a></h5>
<p>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 <font color="#000000">
<code>
<a href="javadoc/org/mindswap/owls/process/execution/ProcessExecutionEngine.html">ProcessExecutionEngine.execute(Process,
ValueMap)</a> </code><font face="Tahoma">
function where second parameter specifies the values for
input parameters. This function returns another
ValueMap</a></code> which contains the output value bindings. The following
code segment shows an example of executing a service:</font></font></p>
<div align="left" class="java">
<div align="center">
<center>
<table border="2" cellpadding="3" cellspacing="0" bgcolor="#ffffff" width="60%" style="border-collapse: collapse" bordercolor="#111111">
<tr>
<td nowrap="nowrap" valign="top" align="left">
<code>
<font color="#ffffff"> </font><font color="#3f7f5f">// create an execution engine </font><br/>
<font color="#ffffff"> </font><font color="#000000">ProcessExecutionEngine exec = OWLSFactory.createExecutionEngine();</font></code><p>
<code>
<font color="#ffffff"> </font><font color="#3f7f5f">// </font><font color="#3F7F5F">load
the service description</font><font color="#ffffff"><br>
</font><font color="#000000">Service service = kb.readService(</font><font color="#2a00ff">"http://www.mindswap.org/2004/owl-s/1.0/Dictionary.owl"</font><font color="#000000">);<br>
</font>
<font color="#ffffff"> </font><font color="#3f7f5f">// get
the process of the service</font><br/>
<font color="#ffffff"> </font><font color="#000000">Process process = service.getProcess();</font><br/>
<br/>
<font color="#ffffff"> </font><font color="#3f7f5f">// create
an empty value map</font><br/>
<font color="#ffffff"> </font><font color="#000000">ValueMap values = new
ValueMap();</font><br/>
<font color="#ffffff"> </font><br/>
<font color="#ffffff"> </font><font color="#3f7f5f">// set
the value of input parameter</font><br/>
<font color="#ffffff"> </font><font color="#000000">values.setDataValue(process.getInput(</font><font color="#2a00ff">"InputString"</font><font color="#000000">), </font><font color="#2a00ff">"computer"</font><font color="#000000">); </font><br/>
<font color="#ffffff"> </font><font color="#3f7f5f">// execute
the process with the given input bindings</font><br/>
<font color="#ffffff"> </font><font color="#000000">values = exec.execute(process, values); </font><br/>
<font color="#ffffff"> </font><br/>
<font color="#ffffff"> </font><font color="#3f7f5f">// get the output value
as a string</font><br/>
<font color="#ffffff"> </font><font color="#000000">String outValue = values.getStringValue(process.getOutput());</font><br/>
<font color="#ffffff"> </font><br/>
<font color="#ffffff"> </font><font color="#3f7f5f">// display the result</font><br/>
<font color="#ffffff"> </font><font color="#000000">System.out.println(</font><font color="#2a00ff">"Output = " </font><font color="#000000">+ outValue);</font></code></td>
<!-- end source code -->
</tr>
<!-- start Java2Html link -->
<!-- end Java2Html link -->
</table>
</center>
</div>
</div>
<!-- = END of automatically generated HTML code = -->
<!-- ======================================================== -->
<p><br>
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
for more examples of this kind.<br>
</p>
<p>
</p>
</li>
<li><h5><a name="#monitor">Execution monitoring</a></h5>
<p>It is possible to see the progress of execution when a complex service is
being executed.
ProcessExecutionListener</a> defines a set of minimal functions for this
purpose. simply use the <font color="#000000">
<code>
<a href="javadoc/org/mindswap/owls/process/execution/ProcessExecutionEngine.html">ProcessExecutionEngine.addExecutionListener(ProcessExecutionListener)</a> </code>
to set a listener on the execution engine. </font>See
for examples of how to use the listener.<br>
</p>
<p>
</p>
</li>
<li><h5><a name="#composite">Creating composite processes</a></h5>
<p>It is possible to create service descriptions, profiles or processes
programmatically.
<code>
<a href="javadoc/org/mindswap/owl/OWLOntology.html">OWLOntology</a></code> provides functions to create any of these structures.
<code>
shows an example of how to do this. The following code snippet shows the main
idea:</p>
<div align="left" class="java">
<div align="center">
<center>
<table border="2" cellpadding="3" cellspacing="0" bgcolor="#ffffff" width="60%" style="border-collapse: collapse" bordercolor="#111111">
<tr>
<td nowrap="nowrap" valign="top" align="left">
<code>
<font color="#ffffff"> </font><font color="#3f5fbf">/**</font><br/>
<font color="#ffffff"> </font><font color="#3f5fbf">* </font><br/>
<font color="#ffffff"> </font><font color="#3f5fbf">* Create a new Sequence from the processes of the given services and put them in a new</font><br/>
<font color="#ffffff"> </font><font color="#3f5fbf">* Service.</font><br/>
<font color="#ffffff"> </font><font color="#3f5fbf">* </font><br/>
<font color="#ffffff"> </font><font color="#3f5fbf">* </font><font color="#7f9fbf">@param </font><font color="#3f5fbf">services List of Service</font><font color="#3F5FBF">s</font><br/>
<font color="#ffffff"> </font><font color="#3f5fbf">* </font><font color="#7f9fbf">@param </font><font color="#3f5fbf">baseURI The base URI for the generated service</font><br/>
<font color="#ffffff"> </font><font color="#3f5fbf">* </font><font color="#7f9fbf">@return </font><font color="#3f5fbf">The Service which is a Sequence of the given services </font><br/>
<font color="#ffffff"> </font><font color="#3f5fbf">*/</font><br/>
<font color="#ffffff"> </font><font color="#000000">Service createSequenceService(List services, String baseURI) {</font><font color="#ffffff"> <br>
</font><font color="#3f7f5f">// create an empty ontology</font><br/>
OWLOntology ont = OWLFactory.createOntology();<br/>
<font color="#ffffff"> </font><font color="#3f7f5f">// create a
n</font><font color="#3F7F5F">ew service</font><br/>
<font color="#ffffff"> </font><font color="#000000">Service service = ont.createService(URI.create(baseURI + </font><font color="#2a00ff">"Service"</font><font color="#000000">));</font><br/>
<font color="#ffffff"> </font><font color="#3f7f5f">// create a new
composite process </font><br/>
<font color="#ffffff"> </font><font color="#000000">CompositeProcess process = ont.createCompositeProcess(URI.create(baseURI + </font><font color="#2a00ff">"Process"</font><font color="#000000">)); </font><br/>
<font color="#ffffff"><br>
</font><font color="#3f7f5f">// create a new sequence
construct</font><br/>
<font color="#ffffff"> </font><font color="#000000">Sequence sequence = ont.createSequence();</font><br/>
<font color="#ffffff"> </font><font color="#3f7f5f">// put
the sequence into composite process </font><br/>
<font color="#ffffff"> </font><font color="#000000">compositeProcess.setComposedOf(sequence);</font><br/>
<font color="#ffffff"> </font><br/>
<font color="#ffffff"> </font><font color="#7f0055"><b>for</b></font><font color="#000000">(</font><font color="#7f0055"><b>int </b></font><font color="#000000">i = </font><font color="#990000">0</font><font color="#000000">; i < services.size(); i++) { </font><br/>
<font color="#ffffff"> </font><font color="#3f7f5f">// get
the service from the list</font><br/>
<font color="#ffffff"> </font><font color="#000000">Service s = (Service) services.get(i);</font><br/>
<font color="#ffffff"> </font><font color="#3f7f5f">// get
the process fron the service<br>
</font>
<font color="#ffffff"> </font><font color="#000000">Process p = s.getProcess();</font><br/>
<font color="#ffffff"> <br>
</font><font color="#3f7f5f">// create a perform
construct<br>
perform.setProcess(p);<br/>
<font color="#ffffff"> </font><font color="#3f7f5f">// put
the process into the sequence</font><br/>
<font color="#ffffff"> </font><font color="#000000">sequence.addComponent(p);</font><br/>
<font color="#ffffff"><br>
</font><font color="#3f7f5f">// create data flow if
necessary... </font><br/>
<font color="#ffffff"><br>
</font><font color="#000000">}<br>
</font>
<font color="#ffffff"><br>
</font><font color="#3f7f5f">// create profile...<br>
</font>
<font color="#ffffff"><br>
</font><font color="#3f7f5f">// create grounding </font><br/>
<font color="#3f7f5f"><br>
</font>
<font color="#ffffff"> </font><font color="#7f0055"><b>return </b></font><font color="#000000">service;</font><font color="#3f7f5f"><br>
</font><font color="#000000"> }</font></code></td>
<!-- end source code -->
</tr>
<!-- start Java2Html link -->
<!-- end Java2Html link -->
<tr>
<td nowrap="nowrap" valign="top" align="left">
</td>
</tr>
</table>
</center>
</div>
</div>
<!-- = END of automatically generated HTML code = -->
<!-- ======================================================== -->
<p><br>
</p>
<p>
</p>
</li>
<li><h5><a name="#owl">Using OWL resources</a></h5>
<p>
Every resource in the API (<code><a href="javadoc/org/mindswap/owls/service/Service.html">Service</a>,</code>
<code>
Profile</a>,</code>
<code>
Process</a>,</code> etc.) extends
<code>
<a href="javadoc/org/mindswap/owl/OWLIndividual.html">
OWLIndividual</a></code> 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.</p>
<p>
In the future releases it is planned to add support for
</p>
<p>
</p>
</li>
<li><h5><a name="#wsdl">WSDL Support</a></h5>
<p>The API contains a package
<a href="javadoc/org/mindswap/wsdl/package-summary.html">
org.mindswap.owls.wsdl</a> that provides support for reading and executing
WSDL services. Execution of OWL-S services is achieved through this package.
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.<br>
</p>
<p>
</p>
</li>
</ol>
</div>
</div>
</body>
</html>