This document currently describes the library prototype implementation of OMWG versioning component. See earlier deliverables for requirements and design descriptions.
The versioning library prototype extends WSMO API, with WSMO4J as its default implementation.
The public API of the versioning library prototype is in the package
org.omwg.versioning and its subpackages. The following three subsections detail various parts of the API.
A version identifier is represented by the interface
org.omwg.versioning.VersionIdentifier and it can be any string. There is a special VersionIdentifier instance called NO_VERSION which is a special case used for ontologies that currently do not have any version identifier.
Version identifiers are stored in the URIs identifying ontologies and their components, so that multiple versions can coexist simply in one knowledge base. For this purpose, the library prototype extends WSMO API’s interface
org.wsmo.common.URIRef into the interface
org.omwg.versioning.common.URIRef which gets a new method returning the version identifier contained in the URI reference.
For representing additional information about a version, like the creator of the version, the date the version was created or any other metadata, the versioning library prototype contains the interface
org.omwg.versioning.VersionInformation. Instances of this class are associated with a version identifier and contain a general map of properties, but also provide three convenience accessors for the creation date, the user and the comment of this version.
Users are tentatively represented with the interface
org.omwg.versioning.UserCredentials and it simple implementation
org.omwg.versioning.SimpleUserCredentials that store only a string user name. We envision that future extensions to the WSMO API will deal with user credentials and then the versioning library will use WSMO API’s mechanism for dealing with users.
Since only ontologies are versioned (for rationale, see the requirements document), the interface
org.omwg.ontology.Ontology from WSMO API has been extended into
org.omwg.versioning.ontology.Ontology. This interface now provides a convenience accessor for the current version identifier (which is also available in the ontology’s URI).
Instances of this interface can either be committed, i.e. unchanged since the ontology was loaded or last committed, or changed. When an ontology that is committed is changed in any way (for example adding a concept to the ontology, or adding an attribute to a concept in this ontology), the ontology creates a new version identifier automatically and becomes changed. When all changes intended on the ontology are made, the ontology can be committed, in which case any new changes will start a new version. In case a user decides that the changes are wrong, the ontology can go back to the previous version, dropping all changes and restoring the previous state. The following is a summary of the methods available for version lifecycle:
- Commits the current ontology version, returning the version identifier.
- Checks whether the ontology is unchanged since it was loaded or last commited.
- Drops all changes done to the ontology since the load or the last commit.
In order to access the versioning library prototype implementation extending WSMO API,
org.wsmo.common.Factory.getWSMOFactory(Map) should be called with the parameter
FACTORY_PROVIDER_CLASS with the value
The current implementation of the WSMO parser relies on the default WSMO factory provider instead of being parametrized, therefore using the parser together with the versioning library prototype implementation the default factory provider class must be changed in
The versioning library prototype implementation is a layer of facades over most of the interfaces in an underlying implementation of the WSMO API (by default, the underlying implementation is WSMO4J). These facades make sure that when a component of an ontology is changed, the ontology gets to know about it. All accessor operations go directly to the underlying structure, but all change operations are intercepted.
When a change is being made to a committed ontology, the ontology first stores all the underlying objects as backup, then copies them into a new structure copying the previous one (a back-up copy), and only then is the requested change done. When committing the changes, the back-up copy is released and an internal
isCommitted flag is set. When, on the other hand, the changes are being dropped, the back-up underlying objects are restored as the primary structure and the structure containing the changes is left for garbage collection.
Representing Version Identifiers
org.omwg.versioningimpl.common.URIRefImpl implementation puts the version identifier at the end of the path component of a URI, separated with a comma (
VERSION_SEPARATOR). For example version 3 of
http://example.com/ontology would be
http://example.com/ontology,3 and version 17 of
http://example.com/ontology#foo would be
http://example.com/ontology,17#foo. This approach slightly prefers that ontology identifiers don’t contain query or fragment identifier URI components, as those would appear after the version ID.
This simple prototype implementation of a versioning library shows that a simple explicit version lifecycle API can be implemented over an existing ontology API (like WSMO API). This thin layer can either be folded into the ontology API which would thus gain native support for versioning, or it can be utilized in an ontology editing tool, keeping the underlying ontology API independent of the used versioning strategy.