Difference between revisions of "Version Migration"

From Developer Documents
Jump to navigation Jump to search
Line 2: Line 2:
  
 
==Ontology Migration==
 
==Ontology Migration==
−
An ontology is a compilation of ''concepts'' (=types and relations).  
+
An ontology is a compilation of shared ''concepts'' (=types, relations and instances).  
−
     <nowiki>http://Layer0-1.0</nowiki>  
+
     <nowiki>http://www.simantics.org/Layer0-1.0</nowiki>  
−
         <nowiki>http://Layer0-1.0/ConsistOf</nowiki>
+
         <nowiki>http://www.simantics.org/Layer0-1.0/ConsistOf</nowiki>
−
         <nowiki>http://Layer0-1.0/DependsOn</nowiki>
+
         <nowiki>http://www.simantics.org/Layer0-1.0/Library</nowiki>
−
        <nowiki>http://Layer0-1.0/Project</nowiki>
 
−
        <nowiki>http://Layer0-1.0/Library</nowiki>
 
  
−
Ontology, Type and Relations are versioned. The version number is visible in the URI.
+
Ontologies are versioned according to the following scheme
−
    <nowiki>http://Layer0-2.0</nowiki>
 
−
        <nowiki>http://Layer0-2.0/Collection</nowiki>              <small>(1)</small>
 
−
        <nowiki>http://Layer0-1.0/ConsistOf</nowiki>                <small>(3)</small>
 
−
        <nowiki>http://Layer0-1.0/DependsOn</nowiki>                <small>(3)</small>
 
−
        <nowiki>http://Layer0-2.0/Project</nowiki>                  <small>(2b)</small>
 
−
        <nowiki>http://Layer0-2.0/Library</nowiki>                  <small>(2a)</small>
 
−
            Inherits <nowiki>http://Layer0-1.0/Library</nowiki>
 
  
−
A new version of an ontology is a publication. It is a compilation of new concepts <small>(1)</small>, revisions of concepts from previous ontology version <small>(2)</small>, and a subset of old concepts with old assumptions and old version number <small>(3)</small>. Unused concepts of previous ontology are NOT included in the new.
+
    <nowiki><Ontology URI>-<major version>.<minor version></nowiki>  
  
−
# New concepts that have never been published before. The first version number is same as the ontology version number.
+
For example
−
# 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'''  <small>(2a)</small> It adds restriction and inherits the previous version. Example, new property is added to a type.
+
    <nowiki>http://www.simantics.org/Layer0-1.0</nowiki>
−
#* '''Assumption Overriding Modification'''  <small>(2b)</small> 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.
+
 
−
# Old concepts that are re-published unmodified. Version number is the number of first publication.
+
All shared concepts contained in the ontology are accordingly versioned along with the ontology and the version number is visible in the URI. For ontological concepts we define
 +
 
 +
'''versioned URI''' as the proper URI of the resource e.g. <nowiki>http://www.simantics.org/Layer0-1.0/ConsistsOf</nowiki>
 +
 
 +
'''unversioned URI''' where version information is omitted e.g. <nowiki>http://www.simantics.org/Layer0/ConsistsOf</nowiki>
 +
 
 +
Ontologies are deployed as OSGi bundles. Declarations in Simantics software may use the unversioned URI to refer to concepts in the ''latest'' version on an ontology (or the version found from OSGi dependencies).
 +
 
 +
The following simple rules for ontology development are defined to enable version migration
  
 
===Rules===
 
===Rules===
−
# 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.  
+
# All ontology versions shall be completely self-contained. All concepts are declared in all versions of an ontology.
−
  Require-Bundle: org.simantics.layer0;bundle-version="[1.0.0,2.0.0)"
+
# There shall be exactly one ontology in each ontology bundle.
 +
# The '''Bundle-Name''' of an ontology shall be the unversioned URI of the ontology
 +
# The '''Bundle-Version''' of an ontology shall be the ontology version as specified in the ontology URI
  
 
==Model Migration==
 
==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 <nowiki>http://DEVS-2.0/DevsModel</nowiki> and database has <nowiki>http://DEVS-1.0/DevsModels</nowiki>. 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.
+
A project in a database contains models of different versions created with different versions of software features.
 +
 
 +
The database can host multiple versions of ontologies which enables old models to exist and to be imported in the database. A typical software feature can only manipulate models defined with the latest versions of some ontologies.
 +
 
 +
Software features can make model migration from models created with previous versions of the software. Each model is ''associated in the database with a single software feature version'', which then can be used to determine the actions needed for migrating models to the latest ontological definitions.
 +
 
 +
The user can browse the old and new models contained in the database and perform model migration at will.
 +
 
 +
==Release process==
  
−
DEVS-2.0 feature presents an adapter for <nowiki>http://DEVS-1.0/DevsModel</nowiki> that implements ModelMigration interface.
+
A released Simantics feature uses a set of ontologies with specified version numbers. All models associated with a specific software version need access to these ontology versions even after the ontologies have evolved. Thus it is necessary to release and freeze all versions of used ontologies whenever a software is released. Thus the procedure for making a software release includes
−
<source lang="java">
 
−
public interface ModelMigration {
 
  
−
/**
+
# Making copies of all
−
* Migrate old models to newer version. The operation is a atomic,
 
−
* if it fails no modifications are done and MigrationException is thrown.
 
−
* <p>
 
−
* 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>
 
  
 
[[Category: Ontology Development]]
 
[[Category: Ontology Development]]
 
[[Category: Database Development]]
 
[[Category: Database Development]]

Revision as of 05:22, 18 October 2011

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 shared concepts (=types, relations and instances). 

   http://www.simantics.org/Layer0-1.0 
       http://www.simantics.org/Layer0-1.0/ConsistOf
       http://www.simantics.org/Layer0-1.0/Library

Ontologies are versioned according to the following scheme 

   <Ontology URI>-<major version>.<minor version>

For example 

   http://www.simantics.org/Layer0-1.0

All shared concepts contained in the ontology are accordingly versioned along with the ontology and the version number is visible in the URI. For ontological concepts we define

versioned URI as the proper URI of the resource e.g. http://www.simantics.org/Layer0-1.0/ConsistsOf

unversioned URI where version information is omitted e.g. http://www.simantics.org/Layer0/ConsistsOf

Ontologies are deployed as OSGi bundles. Declarations in Simantics software may use the unversioned URI to refer to concepts in the latest version on an ontology (or the version found from OSGi dependencies).

The following simple rules for ontology development are defined to enable version migration

Rules

  1. All ontology versions shall be completely self-contained. All concepts are declared in all versions of an ontology.
  2. There shall be exactly one ontology in each ontology bundle.
  3. The Bundle-Name of an ontology shall be the unversioned URI of the ontology
  4. The Bundle-Version of an ontology shall be the ontology version as specified in the ontology URI

Model Migration

A project in a database contains models of different versions created with different versions of software features.

The database can host multiple versions of ontologies which enables old models to exist and to be imported in the database. A typical software feature can only manipulate models defined with the latest versions of some ontologies.

Software features can make model migration from models created with previous versions of the software. Each model is associated in the database with a single software feature version, which then can be used to determine the actions needed for migrating models to the latest ontological definitions.

The user can browse the old and new models contained in the database and perform model migration at will.

Release process

A released Simantics feature uses a set of ontologies with specified version numbers. All models associated with a specific software version need access to these ontology versions even after the ontologies have evolved. Thus it is necessary to release and freeze all versions of used ontologies whenever a software is released. Thus the procedure for making a software release includes

  1. Making copies of all
Retrieved from "https://dev.simantics.org/index.php?title=Version_Migration&oldid=2383"