EnkiRepositoryUpgrade

Under Construction: Details on how to manage repository upgrades

Overview

Upgrading repository versions without using XMI import and export requires modification of Enki/Hibernate's per-metamodel database schema. In addition it must be possible to upgrade an Enki/Hiberate schema by direct manipulation of the database rather than via XMI import/export. This page documents the tools necessary to accomplish the upgrade.

Table Modification DDL

Manual Upgrade

The basic steps are:

1. Generate an Enki/Hibernate schema for the old version of your metamodel.
2. Generate the same for the new version of your metamodel.
3. Write a DDL script that make the necessary modifications to table structures and indexes.

In addition, if the multiplicity or ordering of any association end was modified, you'll need to write DML statements to move the associated associations data to the correct table. Likewise if any association had the high-cardinality association tag added or removed, data will need to be transferred. See the section on advanced, automated upgrade for some examples.

The best way to determine how to transfer the data is to identify the same associations in both models and examine the data in the association tables.

Automated Upgrade

This section outlines the requirements for a Schema Delta Tool that can automate all or part of the manual steps described above.

The purpose of the Schema Delta Tool is to generate the necessary SQL statements to convert version A of an Enki/Hiberate repository to version B. It must not destroy any data.

New attributes and associations on an existing class cause the corresponding table to be altered to include new columns representing the attributes and associations. The FarragoCatalogChangeRules forbids adding new required (e.g. multiplicity 1) attributes unless they are numeric or boolean values. The tool can support these by providing a default value for the column. The default value should be zero (0) for numeric types and false for boolean types.

Trivial Version

A trivial version of a Schema Delta Tool can be implemented by using the existing Enki Ant task and the org.eigenbase.enki.hibernate.ant.ExportSchemaSubTask. The tool should generate the complete schema DDL for the old metamodel version. It may obtain the UML from source control or require that the user retrieve the file and specify its location. Once the schema DDL is generated it is applied to the database. Next the tool generates the schema DDL for the new metamodel version using the ExportSchemaSubTask's update mode. This will use Hibernate's internal tools to generate only the necessary changes to support the new metamodel version.

This is referred to as the trivial version because it cannot handle any modifications to association end multiplicity and ordering or the application or removal of the high-cardinality association tag.

Advanced Version

A more advanced version of the Schema Delta Tool can be implemented by comparing the old and new metamodel versions. Some possible mechanisms for this are:

1. Import both models into Netbeans MDR and look for identically named associations with different parameters.
2. By inspecting the UML files via XSLT or a custom XML comparison tool.

Once the association changes are known, it is possible to generate DML statements to copy data for existing associations to the correct association tables.

Example 1: 1-to-1 becomes 1-to-many, unordered:

insert into FEM_AssocOneToMany (mofId, type, reversed, parentType, parentId) 
    select mofId, type, false, parentType, parentId from FEM_AssocOneToOne where type = 'abc';

insert into FEM_AssocOneToManyChildren (mofId, childType, childId) 
    select mofId, childType, childId from FEM_AssocOneToOne where type = 'abc';

delete from FEM_AssocOneToOne where type = 'abc';

Note that the reversed flag is false because the second end of the association is the many end. Otherwise, the 1-to-1 child data would become the 1-to-many parent data, the 1-to-1 parent data would become the 1-to-many child data and reversed would be true.

Example 2: 1-to-many unordered becomes 1-to-many unordered, high cardinality:

insert into FEM_AssocOneToManyHC (mofId, type, reversed, parentType, parentId) 
    select mofId, type, reversed, parentType, parentId from FEM_AssocOneToMany where type = 'abc';

insert into FEM_AssocOneToManyHCChildren (mofId, childType, childId) 
    select mofId, childType, childId from FEM_AssocOneToManyChildren where type = 'abc';

delete from FEM_AssocOneToManyChildren where mofId in (select mofId from FEM_AssocOneToMany where type = 'abc');

delete from FEM_AssocOneToMany where type = 'abc';

1-to-many to many-to-many conversions are also possible. Note that Enki/Hibernate stores many-to-many associations as a one-to-many relationship for each object that belongs to the associations first end and again as a one-to-many relationship for each object that belongs to the association's second end. As in the manual case generating some actual data in a metamodel will be instructive.

The advanced version of the tool should block some type of changes:

• Unordered associations cannot be converted to ordered associations deterministically.
• Association ends with an upper bound greater than 1 (e.g., "many" ends) cannot be converted to ends with an upper bound equal to 1 (e.g., "single" ends).

There may be other restrictions.

View Modification DDL

Manual

Upgrade steps:

1. Drop the all-of-type/class views.
2. Modify tables as necessary (See #Table Modification DDL).
3. Regenerate view creation DDL from metamodel
4. Recreate views.

Automated

If Enki/Hibernate is running with the org.eigenbase.enki.hibernate.createSchema option set to AUTO_VIEW, the views will be updated automatically when the repository is started. Note however, that any views that correspond to classes removed from the model will not be deleted.