Version Migration

This document addresses the issue how simantics application migrates from one version to the next. The scope includes software and ontology development.

Ontology Migration

An ontology is a compilation of concepts (=types and relations).

   http://Layer0-1.0 
       http://Layer0-1.0/ConsistOf
       http://Layer0-1.0/DependsOn
       http://Layer0-1.0/Project
       http://Layer0-1.0/Library

Ontology, Type and Relations are versioned. The version number is visible in the URI.

   http://Layer0-2.0 
       http://Layer0-2.0/Collection               (1)
       http://Layer0-1.0/ConsistOf                (3)
       http://Layer0-1.0/DependsOn                (3)
       http://Layer0-2.0/Project                  (2b)
       http://Layer0-2.0/Library                  (2a)
           Inherits http://Layer0-1.0/Library

A new version of an ontology is a publication. It is a compilation of new concepts (1), revisions of concepts from previous ontology version (2), and a subset of old concepts with old assumptions and old version number (3). Unused concepts of previous ontology are NOT included in the new.

1. New concepts that have never been published before. The first version number is same as the ontology version number.
2. Old concept is revisioned, it has new assumptions. The version number of concept is the same as the new ontology. There are two types of modifications:
   • Incremental Modification (2a) It adds restriction and inherits the previous version. Example, new property is added to a type.
   • Assumption Overriding Modification (2b) An incompatible change to the assumptions. Other than name, there is no retention to the old version. Old and new version do not co-exist in the same publication.
3. Old concepts that are re-published unmodified. Version number is the number of first publication.

Rules

1. A new ontology version cannot modify any statement that has been published in earlier revision of the same major version. Either a new type is introduced, or the ontology is published as next major version. # The dependency version numbering to ontologies from plugins and features should never be open-ended. Be aware that single number version description, eg. "1.0.0" is by OSGi definition, upwards open. Instead use range that is limited to one major version.

  Require-Bundle: org.simantics.layer0;bundle-version="[1.0.0,2.0.0)"

Model Migration

A project in a database contains models of different features and versions. When a feature is migrated to new version, the software is updated first and then the models (if required).

An example scenario. A project was created with DEVS-1.0 feature. Users had installed the project, had used DEVS-1.0 application, and had created DEVS-1.0 models. Now, the project is decided to be updated to the new version DEVS-2.0. Using project management tool, the project admin sets up the database for DEVS-2.0 by installing the new features and ontologies. Then he updates the software to DEVS-2.0 and starts the application. At this point the application and the database are incompatible, as the software demands instances of http://DEVS-2.0/DevsModel and database has http://DEVS-1.0/DevsModels. For each model the admin selects Migrate to 2.0. An action that makes migration modifications to the models. When required the user is consulted.

DEVS-2.0 feature presents an adapter for http://DEVS-1.0/DevsModel that implements ModelMigration interface. <source lang="java"> public interface ModelMigration {

/** * Migrate old models to newer version. The operation is a atomic, * if it fails no modifications are done and MigrationException is thrown.

*

* Optionally a shell may be provided for wizards and user input. * If shell is not provided the migration tool must work without input and * make best guesses. * * @param session database session * @param models models to be migrated * @param shellForInteraction optional shell for user input * @throws MigrationException */ void migrateModel(Session session, Resource[] models, Shell shellForInteraction) throws MigrationException; /** * Get the version number of the outcome model. * * @return version number */ String getResultVersion(); /** * Get a list of source versions supported by this Model Migration class. * * @return a list of versions. Do not modify. */ Collection<String> getSupportedVersions(); } </source>