Alignment API: Upgrading from version 2.x to 3.3

# Upgrading an Alignment implementation from version 2.x to 3.3 of the Alignment API

Version 3.0 of the Alignment API has been designed to provide matching algorithm designers more flexibility. In particular, the version 3.0 does not necessarily rely on the OWL API, so designers who want to use another OWL API, e.g., Jena, can do so at no cost.

Version 3.3 goes one step further towards providing an API independent access to ontologies. Hence it is possible to switch from one API to another without changing code (see documentation).

This has led to some changes over time in the API.

## Since version 3.3, OWLAPIAlignment, OWLAPICell, getObjectXAsURI() are deprecated

The `OWLAPIAlignment` and `OWLAPICell` introduced in version 3.0 and which were previously discussed below are now deprecated and replaced by `ObjectAlignment` and `ObjectCell`. However, for compatibility purposes, these classes are still available and have been reimplemented in function of the new ones. They still have the same structure, content and behavior as the old ones, but the remainder of the API does not use them anymore.

Moreover, in most of the cases, these classes can be safely replaced by the new ones (bringing the benefit of changing Ontology API).

The main exception is that the `getObjectXAsURI()` is not available in `ObjectCell`. So, call to this method on `ObjectCell` will return `null`. The `Ontology` of the object is necessary to obtain its URI, through the call to:

    ontology.getEntityURI( cell.getObjectX() );

## Don't panic

Those who already implemented an algorithm under the API will have to implement some changes for upgrading from version 2 to version 3. But first do not panic. This document aims at helping you in this simple task.

## From BasicAlignments to ObjectAlignments

Previously you certainly had your class extending `BasicAlignment`. You must now have it extending `ObjectAlignment`. This guarantee that you will still find all the features found in the previous `BasicAlignment`.

If you create on the fly new `Alignment` or new `Cell`, if they must contain `Object` (e.g., `OWLEntity`), then be sure that they are created as `ObjectAlignment` and `ObjectCell` respectively.

The new implementation of `BasicAlignment` provides additional new primitives such as `getOntology1URI()`.

## Parsing alignments

If you used to parse alignments, you certainly used `AlignmentParser` which returned a `BasicAlignment`. Now the `AlignmentParser` returns a `URIAlignment`. To turn this `URIAlignment` into an `ObjectAlignment`, just invoke `ObjectAlignment.toObjectAlignment( URIAlignment )`. It will return the corresponding `ObjectAlignment`.

Moreover, `AlignmentParser.parse( URI )` used to take a Hashtable as a second argument. This is not true anymore: you must suppress this second argument.

## Invoking your alignment

For invoking your alignment class, the sequence used to be the following:

    AlignmentProcess al = new MyAlignment();
    al.init( Ontology, Ontology );
    al.align( Alignment, Parameters );

(You may have used a `MyAlignment( Ontology, Ontology )` constructor and no `init`. Now the sequence above is compulsory). Since version 3.0, the sequence is the same except that the arguments for init() are the `URL` where to find the ontologies instead of the ontology themselves. It is thus necessary for you to change your implementation of `init()` so that it loads the ontologies. Moreover, the init Alignment in `align()` is a `URIAlignment` and not a `ObjectAlignment` so it may be necessary to change it as well.

Fortunately, the `OntologyFactory` class already provides the `loadOntology( URI, OntologyCache )` method that loads the required ontology and a `loadInit( URI )` method that will load the initial alignment.

## Manipulating your alignment

If you manipulated the alignment through the attributes (`onto1` and `onto2`), you must now explicitely cast them as `(Ontology)onto1` because they are now declared as `Object`.

## Misc.

`JWNLDistance.Initialize()` now throws an `AlignmentException`... you must do something with it.

## Report to us

Please report any tweak that we did not mention here so that we can update this document.

## More

You can look at the sources of the Alignment API which contain many examples. In particular, look at the `Procalign` class for example of the use of `OntologyCache`.