Quick start with the Alignment API in Java

An extensive presentation of the alignment API can be found at http://gforge.inria.fr/docman/?group_id=117. We also have an on-line tutorial on using it.

Fetching the Alignment API and starting

Requirements

For using you will need Java runtime environment (tested in 1.5). All other necessary libraries are available in the archive (see the list of libraries).

Fetching the ZIP'ed version

The simplest way to use alignapi is to get the last release zipfile from the site http://gforge.inria.fr/frs/?group_id=117. It contains all the sources, compiled library, required libraries.

Running

Running the program is achieved through:

$ java -jar lib/procalign.jar
Two URIs required
usage: Procalign [options] URI1 URI2
options are:
	--impl=className -i classname		Use the given alignment implementation.
	--renderer=className -r className	Specifies the alignment renderer
	--output=filename -o filename	Output the alignment in filename
	--params=filename -p filename	Reads parameters from filename
	--alignment=filename -a filename Start from an XML alignment file
	--threshold=double -t double	Filters the similarities under threshold
	--cutmethod=hard|perc|prop|best|span -T hard|perc|prop|best|span	method for computing the threshold
	--debug[=n] -d [n]		Report debug info at level n
	-Dparam=value			Set parameter
	--help -h			Print this message

Alignment API implementation 3.2 ($Id$)

Details below are for developing with the Alignment API.

Bug reports

Package content

Whatever your mode of getting ontolign you will get an alignapi directory containing the following subdirectories:

• README.TXT this file
• README.AServ instructions for setting up an Alignment Server
• LICENSE.TXT the terms under which the software is licensed to you.
• build.xml: ant file to compile and generate jar-files.
• dtd: the align.dtd and align.owl alignment specification;
• lib: contains align.jar, alignwn.jar, procalign.jar, alignsvc.jar and other necessary jarfiles;
• html: a few html presentation files
• html/tutorial: a tutorial on using the API
• distrib: contains a few files for building the distribution
• classes: the compiled classes (in the zip file, the classes are included)
• examples: some examples of use of the API and the Server.
• javadoc: generated javadoc (in the zip file the doc are pregenerated);
• src: source classes:
  • org.semanticweb.owl.align: the API
  • fr.inrialpes.exmo.align.impl: basic implementation
  • fr.inrialpes.exmo.align.util: utility wrapper functions
  • fr.inrialpes.exmo.align.ling: WordNet-based implementation
  • fr.inrialpes.exmo.align.service: Alignment Service

Developing with the Alignement API

Requirements

For extending you will need Java compiler (tested in Java standard edition 1.5). Other libraries are included. It is also very usefull to have Ant.

Compilation and use

Generating the jar-files corresponding to the Alignment API can be achieved by launching:

$ ant jar

Only compiling the necessary files is obtained by:

$ ant compile

Recompiling all files is achieved by:

$ ant compileall

Typical development with the API

We can distinguish four types of developments in the API:

• Developing the API: modifying the code of the API for adding functions or fixing bugs;
• Extending the API: creating new instances of the API interface (new alignment methods, new renderers, new server plug-ins, etc.);
• Embedding the API: creating an application using the API which directly embedded the API libraries and invoke them;
• Using the API as a server: creating an application using the API which communicates loosely with an instance of Alignment Server.

In theory, only the first aspect requires recompiling and modifying the Alignment API code. However, it may be useful for others (for instance for debugging).

The alignment API

The OWL-API is extended with the (org.semanticweb.owl.align) package. Which describes the Alignment API. This API is, in turns, an "implementation" of the Alignment format.

It is basically made of three interfaces:

Alignment

Represents the alignment of two ontology by a specific method. It contains a specification of the alignment and a list of cells.

Cell

Represents a couple of aligned entities together with their confidence measure and alignement relation.

Relation

Represents the specification of the relation holding between two aligned entities.

More information about the attributes of these classes can be found in the format description.

Addtionnally, there is an AlignmentProcess interface which contains a method for calling a particular alignment method (it is a sub-interface of Alignment) and an AlignmentException.

Implementing and extending the API

A (default) impplementation of this API can be found in the fr.inrialpes.exmo.align.impl package.

Adding new alignments methods amounts to create a new AlignmentProcess class implementing the interface. Generally, this can extend the proposed fr.inrialpes.exmo.align.impl.BasicAlignment class and implement AlignmentProcess.

The BasicAlignment has the good taste of defining the storage sructures for ontologies and alignment specification as well as the methods for dealing with alignment display. The only method it does not implement is alignment itself. All methods can be refined (no one is final).

The NameEqAlignment class extends the BasicAlignment by aligning classes bearing the exact same name for properties and classes).

A more elaborate implementation is the EditDistNameAlignment class which uses an edit distance on class names. It thus have to build a matrix of distance and to choose the alignment from the distance. It can be called by:

$ java -jar lib/procalign.jar file://$CWD/examples/rdf/onto1.owl file://$CWD/examples/rdf/onto2.owl -i fr.inrialpes.exmo.align.impl.method.StringDistAlignment
<?xml version='1.0' encoding='utf-8' standalone='no'?>
<rdf:RDF xmlns='http://knowledgeweb.semanticweb.org/heterogeneity/alignment#'
         xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'
         xmlns:xsd='http://www.w3.org/2001/XMLSchema#'
         xmlns:align='http://knowledgeweb.semanticweb.org/heterogeneity/alignment#'>
<Alignment>
  <xml>yes</xml>
  <level>0</level>
  <type>**</type>
  <method>fr.inrialpes.exmo.align.impl.method.StringDistAlignment</method>
  <time>4</time>
  <onto1>
    <Ontology rdf:about="http://www.example.org/ontology1">
      <location>file:///Java/alignapi/examples/rdf/onto1.owl</location>
      <formalism>
        <Formalism align:name="OWL1.0" align:uri="http://www.w3.org/2002/07/owl#"/>
      </formalism>
    </Ontology>
  </onto1>
  <onto2>
    <Ontology rdf:about="http://www.example.org/ontology2">
      <location>file:///Java/alignapi/examples/rdf/onto2.owl</location>
      <formalism>
        <Formalism align:name="OWL1.0" align:uri="http://www.w3.org/2002/07/owl#"/>
      </formalism>
    </Ontology>
  </onto2>
  <map>
    <Cell>
      <entity1 rdf:resource='http://www.example.org/ontology1#journalarticle'/>
      <entity2 rdf:resource='http://www.example.org/ontology2#journalarticle'/>
      <relation>=</relation>
      <measure rdf:datatype='http://www.w3.org/2001/XMLSchema#float'>1.0</measure>
    </Cell>
  </map>
</Alignment>
</rdf:RDF>