Quick start with the Alignment API in Java

This is the very basic for starting with the Alignment API and checking that everything should be fine. Another quick start guide exists for the Alignment server. We also have an on-line tutorial on using the Alignment API and more systematic documentation.

Fetching the Alignment API and starting

Requirements

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

Fetching the ZIP'ed version

The simplest way to use the Alignment API is to get the lastest 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: align.html 1840 2013-03-24 17:20:12Z euzenat $)
Congratulations, you are done. We invite you to learn more by using the tutorial and the documentation.

Details below are for developing with the Alignment API.

Package content

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

Logging

Since version 4.5 (and fully in version 4.6), the alignment API uses extensively SLF4J. We invite the interested reader to read their documentation which is very clear (contrary to many logging explainations).

Following best practices in this domain, the Alignment API does not ship with any SLF4J implementation. It is up to the user to select the implementation (s)he likes the most and put it in the classpath.

This means that, when launched without a looging implementation, this will return:

$ java -cp lib/procalign.jar fr.inrialpes.exmo.align.cli.EvalAlign -i fr.inrialpes.exmo.align.impl.eval.SemPRecEvaluator file:test/output/bibref2.rdf file:test/output/bibref.rdf SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder". SLF4J: Defaulting to no-operation (NOP) logger implementation SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details. ... resulting output
When adding some logger implementation in the classpath, e.g., logback, it will return:
$ java -cp lib/slf4j/logback-core-1.0.9.jar:lib/slf4j/logback-classic-1.0.9.jar:lib/procalign.jar fr.inrialpes.exmo.align.cli.EvalAlign -i fr.inrialpes.exmo.align.impl.eval.SemPRecEvaluator file:test/output/bibref2.rdf file:test/output/bibref.rdf 13:24:09.191 [main] INFO f.i.e.a.impl.eval.SemPRecEvaluator - Created one SemPREvaluator 13:24:09.601 [main] DEBUG f.i.e.a.impl.eval.SemPRecEvaluator - Computing entailment (semantics: null) 13:24:09.606 [main] DEBUG f.i.e.a.impl.eval.SemPRecEvaluator - http://ebiquity.umbc.edu/v2.1/ontology/publication.owl#publication ----> file:///Java/alignapi/examples/rdf/edu.umbc.ebiquity.publication.owl 13:24:09.607 [main] DEBUG f.i.e.a.impl.eval.SemPRecEvaluator - http://purl.org/net/nknouf/ns/bibtex ----> file:///Java/alignapi/examples/rdf/edu.mit.visus.bibtex.owl 13:24:10.770 [main] DEBUG f.i.e.a.impl.eval.SemPRecEvaluator - fr.inrialpes.exmo.align.impl.ObjectAlignment@847a8f3 is consistent 13:24:10.792 [main] WARN f.i.e.a.impl.eval.SemPRecEvaluator - Cannot be translated. 13:24:10.924 [main] WARN f.i.e.a.impl.eval.SemPRecEvaluator - Cannot be translated. 13:24:10.931 [main] WARN f.i.e.a.impl.eval.SemPRecEvaluator - Cannot be translated. 13:24:10.931 [main] WARN f.i.e.a.impl.eval.SemPRecEvaluator - Cannot be translated. 13:24:10.942 [main] DEBUG f.i.e.a.impl.eval.SemPRecEvaluator - Computing entailment (semantics: null) 13:24:10.957 [main] DEBUG f.i.e.a.impl.eval.SemPRecEvaluator - http://ebiquity.umbc.edu/v2.1/ontology/publication.owl#publication ----> file:///Java/alignapi/examples/rdf/edu.umbc.ebiquity.publication.owl 13:24:10.958 [main] DEBUG f.i.e.a.impl.eval.SemPRecEvaluator - http://purl.org/net/nknouf/ns/bibtex ----> file:///Java/alignapi/examples/rdf/edu.mit.visus.bibtex.owl 13:24:11.228 [main] DEBUG f.i.e.a.impl.eval.SemPRecEvaluator - fr.inrialpes.exmo.align.impl.ObjectAlignment@7371b4ca is consistent 13:24:11.303 [main] WARN f.i.e.a.impl.eval.SemPRecEvaluator - Cannot be translated. ... resulting output
and when configuring the implementation for using a different format, it will do:
$ java -cp lib/slf4j/logback-core-1.0.9.jar:lib/slf4j/logback-classic-1.0.9.jar:lib/procalign.jar fr.inrialpes.exmo.align.cli.EvalAlign -Dlogback.configurationFile=logback.xml -i fr.inrialpes.exmo.align.impl.eval.SemPRecEvaluator file:test/output/bibref2.rdf file:test/output/bibref.rdf 13:32:19.711 [main] INFO f.i.e.a.impl.eval.SemPRecEvaluator - Created one SemPREvaluator 13:32:21.232 [main] WARN f.i.e.a.impl.eval.SemPRecEvaluator - Cannot be translated. 13:32:21.400 [main] WARN f.i.e.a.impl.eval.SemPRecEvaluator - Cannot be translated. 13:32:21.409 [main] WARN f.i.e.a.impl.eval.SemPRecEvaluator - Cannot be translated. 13:32:21.410 [main] WARN f.i.e.a.impl.eval.SemPRecEvaluator - Cannot be translated. 13:32:21.785 [main] WARN f.i.e.a.impl.eval.SemPRecEvaluator - Cannot be translated. 13:32:21.796 [main] WARN f.i.e.a.impl.eval.SemPRecEvaluator - Cannot be translated. 13:32:21.797 [main] WARN f.i.e.a.impl.eval.SemPRecEvaluator - Cannot be translated. 13:32:21.797 [main] WARN f.i.e.a.impl.eval.SemPRecEvaluator - Cannot be translated. ... resulting output

Such an approach to dealing with logging events should provide full satisfaction to users as it provides to us.

Developing with the Alignement API

Requirements

For extending you will need a Java compiler (tested in Java standard edition 1.6). Other libraries are included. It is also very usefull to have Ant. The Alignment API is not officially published in Maven repositories due to various hassles required by doing this. If you want to help, you are welcome.

Compilation and use

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

$ ant jar
This recompiles the necessary files.

Only compiling the necessary files is obtained by:

$ ant compile

Recompiling all files is achieved by:

$ ant compileall

Executing the tests:

$ ant test

Checking all java warnings and other static analysis tools:

$ ant lint

Clean up what has been generated:

$ ant clean

Other options may be obtained by ant usage or through inspecting the build.xml file.

Typical development with the API

We can distinguish four types of developments in the API:

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

Documentation

Most documentation is available from here. An exception is the javadoc which is only available on your local machine. It can be recompiled by:

$ ant javadoc


http://alignapi.gforge.inria.fr/align.html

$Id: align.html 1840 2013-03-24 17:20:12Z euzenat $