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 (see Release notes for compatible version). 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 ftp://ftp.inrialpes.fr/pub/exmo/software/ontoalign/.
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$)
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:
- README.TXT instructions for starting with the Alignment API
- 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, ontowrap.jar, procalign.jar, alignsvc.jar
and other necessary jarfiles;
- html: documentation
- 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);
- test: unit tests for testng;
- tools: some tools that may be used for engineering the API;
- src: source classes:
- org.semanticweb.owl.align: the API
- fr.inrialpes.exmo.ontowrap: ontology API wrappers
- fr.inrialpes.exmo.align.impl: basic implementation
- fr.inrialpes.exmo.align.cli: command-line interface
- fr.inrialpes.exmo.align.util: utility wrapper functions
- fr.inrialpes.exmo.align.ling: WordNet-based implementation
- fr.inrialpes.exmo.align.parser: Alignment format parsers
- fr.inrialpes.exmo.align.service: Alignment Server
- fr.inrialpes.exmo.align.gen: test generators
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.2.10.jar:lib/slf4j/logback-classic-1.2.10.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.2.10.jar:lib/slf4j/logback-classic-1.2.10.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 (see Release notes for compatible version). 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:
- 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 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
https://moex.gitlabpages.inria.fr/alignapi/align.html