Exposing a matcher as a web service

This tutorial explains, step-by-step, how to make available a matcher implementation through a web service, by extending a simple web service interface.

The minimal web service interface

There are many different methods for computing alignments. However, they always need at least two ontologies as input and provide an alignment as output. So, a minimal interface for providing an alignment should contain:

String align(URI onto1,URI onto2)

This method takes as parameters the URIs of the two ontologies to be matched and returns a String representing the alignment. In order to make available such an interface as an operation within a web service, we define a minimal web service interface, as presented below.

Different ways for creating web services can be used. Here we propose to follow the Java API for XML Web Services (JAX-WS). Following this approach, a service endpoint is a Java interface or class that specifies the methods that a client can invoke on the service. The development of JAX-WS web services is based on a set of annotations. The @WebService annotation defines the class as a web service endpoint while @WebMethod defines the operations of this web service. We can determine the encoding style for messages send to and from the Web Service, through the annotation @SOAPBinding.

package eu.sealsproject.omt.ws.matcher; import java.net.URI; import javax.jws.WebMethod; import javax.jws.WebService; import javax.jws.soap.SOAPBinding; import javax.jws.soap.SOAPBinding.Style; @WebService @SOAPBinding(style = Style.RPC) public interface AlignmentWS { @WebMethod public String align(URI source, URI target); }

This interface defines a service endpoint, AlignmentWS and its operation, align, which takes as parameters the URIs of the two ontologies to be aligned and returns a String representing the alignment.

Extending the minimal interface

Extending the web service interface requires the definition of the corresponding interface by adding the endpointInterface element to the @WebService annotation in the implementation class (AlignmentWSImpl.java):

package example.ws.matcher; import javax.jws.WebService; @WebService(endpointInterface="eu.sealsproject.omt.ws.matcher.AlignmentWS") public class AlignmentWSImpl implements AlignmentWS { public String align(URI source, URI target) { // your implementation return alignment; } }

The method align must implement the matching process. The easiest way to do this is to implement the Alignment API (see details in how to extend the Alignment API with a new matcher). Basically, you need to implement the AlignmentProcess interface (method align) and extend the URIAlignment class (MyAlignment.java):

package example.ws.matcher; import java.net.URI; import java.util.Properties; import org.semanticweb.owl.align.Alignment; import org.semanticweb.owl.align.AlignmentException; import org.semanticweb.owl.align.AlignmentProcess; import fr.inrialpes.exmo.align.impl.URIAlignment; public class MyAlignment extends URIAlignment implements AlignmentProcess { public void align( Alignment alignment, Properties params ) throws AlignmentException { // matcher code } }

Then, it is simple to expose MyAlignment as a web service (MyAlignmentWS.java):

package example.ws.matcher; import java.io.BufferedWriter; import java.io.OutputStreamWriter; import java.io.PrintWriter; import java.net.URI; import java.util.Properties; import javax.jws.WebService; import org.semanticweb.owl.align.Alignment; import org.semanticweb.owl.align.AlignmentException; import org.semanticweb.owl.align.AlignmentProcess; import org.semanticweb.owl.align.AlignmentVisitor; import fr.inrialpes.exmo.align.impl.renderer.RDFRendererVisitor; @WebService(endpointInterface="eu.sealsproject.omt.ws.matcher.AlignmentWS") public class MyAlignmentWS extends MyAlignment implements AlignmentWS { @Override public String align(URI source, URI target) { try { init(source,target); align((Alignment)null, new Properties()); SBWriter sbWriter = null; try { sbWriter = new SBWriter(new BufferedWriter(new OutputStreamWriter( System.out, "UTF-8" )), true); AlignmentVisitor renderer = new RDFRendererVisitor(sbWriter); render(renderer); String alignment = sbWriter.toString(); return alignment; } catch(Exception e) { } } catch (AlignmentException e) { e.printStackTrace(); } return null; } }

Publishing the web service

In order to be available for external access, the web service must be published at an endpoint, at which point it starts accepting incoming requests. This could be done by creating a WAR file to be deployed in a tomcat server, or by creating a publisher. In the second case, the publisher can use the method publish to publish its address to the Endpoint (AlignmentWSPublisher.java):

package example.ws.matcher; import javax.xml.ws.Endpoint; import eu.sealsproject.omt.ws.matcher.AlignmentWS; import eu.sealsproject.omt.ws.matcher.AlignmentWSImpl; public class AlignmentWSPublisher { public static void main(String args[]) { /* Publish matcher service web service */ AlignmentWS serverMatcher = new AlignmentWSImpl(); Endpoint endpointMatcher = Endpoint.publish("http://134.155.86.66:8080/matcherWS", serverMatcher); System.out.println("Matcher service published ... "); } }

The endpoint has to be started on a public available machine (a machine that is accessible from the internet). In the example above we specified the IP 134.155.86.66 as part of the address, because it is the IP of the machine that we used for testing the example. If you make your matcher available as a webservice based on this example, you have to additionally take into account the following:

The service can be accessed at via the URL http://134.155.86.66:8080/matcherWS and its WSDL - describing its methods - can be found at http://134.155.86.66:8080/matcherWS?wsdl.

To use the seals infrastructure you have to specify the class including its package specification (e.g. example.ws.matcher.AlignmentWSImpl or example.ws.matcher.MyAlignmentWS) and you have to specify the URL of the service endpoint (e.g. http://134.155.86.66:8080/matcherWS or http://134.155.86.66:8080/matcherWS?wsdl).