Exposing a matcher as a web service

This version:
Cássia Trojahn dos Santos & Jérôme Euzenat, INRIA & Univ. Grenoble Alpes
with contributions from Christian Meilicke, University of Mannheim

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.

Our minimal web service interface is defined as follow (AlignmentWS.java):

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 } }

The complete example, following how to extend the Alignment API with a new matcher, can be found at MyAlignmentComplete.java.

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 org.semanticweb.owl.align.Cell; 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 { for (Object c: this.getArrayElements().toArray()) { this.remCell((Cell)c); } 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; } }

Note that we have added a loop for removing the cells in the URIAlignment object (lines before the method init(source,target)). This is due the fact that the method align will be called several times in a web service cycle life (for each test). If we do not remove the cells computed in a previous call, the previous cells will be included in the current result.

Nothing more is needed.

You can download SBWriter.java.

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("", 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 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 and its WSDL - describing its methods - can be found at

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. or

Additional Note: If you exactly follow these instructions to publish your wrapped matcher as a webservice, this will automatically generate a WSDL file that contains all required information. However, you can use also use another framework (e.g. axis) for publishing the webservice, but than you have to ensure to use the namespace "http://matcher.ws.omt.sealsproject.eu/" in the appropriate way. Take a look at this file as an example.

Deploying the web service on a Tomcat

You might be interested to deploy the matcher webservice at a stable endpoint on a Tomcat application server. We have prepared a minimal matcher as described in the tutorial and some additional files (xml files for deployment, libraries, ant-file) that are required to deploy the service on a Tomcat server. The whole bundle is available here for download!

Unzip the file and open the readme.txt file. It explains how to generate, deploy and test the webservice. It is required that you have ant installed to use it.

Further exercises

More info: https://moex.gitlabpages.inria.fr/alignapi/tutorial/