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.
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() );
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.
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().
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.
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.
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.
JWNLDistance.Initialize() now throws an AlignmentException... you must do something with it.
Please report any tweak that we did not mention here so that we can update this document.
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.