developers

Technologies used

For migration of AMALTHEA models, plane java approach has been used ( non EMF) along with the following 3rd party libraries :

JDOM 2
JAXEN
XALAN
XERCES

Framework for model migration

Using the above specified technologies, eclipse plugin based framework for model migration is developed.

org.eclipse.app4mc.amalthea.converters.common plugin consists of Model migration framework

Components of Model Migration Framework

Converters
Cache Builders
Pre Processor
Post Processor

All the above specified components are contributed as extension points in the plugin org.eclipse.app4mc.amalthea.converters.common

Detailed description of each component can be found below:

Converters: This component is responsible for converting the model (xmi) content from one version to another. A Converter component is executed for selected model files and the corresponding referred model files for migration ( each execution is w.r.t. specific model file).

Converter can be registered by adding extension definition for : org.eclipse.app4mc.amalthea.model.converters and defining the following parameters :

ID : This is the unique identifier of a Converters component with which it is identified
Name : Name of the component
Input model version : AMALTHEA model version in which the input model content is present.
Output model version : AMALTHEA model version to which the input model content should be converted to.

First version of APP4MC was 0.7.0

From version 0.9.3 of APP4MC, there will not be any support for migration of AMALTHEA models based on ITEA releases (itea.103, itea.110, itea.111)

Converter Class : Java class implementing org.eclipse.app4mc.amalthea.converters.common.base.IConverter interface and providing the definition for method : public void convert(final File targetFile, final Map<File, Document> fileName_documentsMap, final List<ICache> caches) throws Exception
enabled : By specifying true/false - > specific converter invocation can be enabled or disabled

Converter dependencies : A Converter can be dependent on other Converter components. During the execution of a specific Converter component first its dependencies are invoked and then dependent converter is invoked.

Converter dependencies can be specified at the extension level in the following way:

Cache Builders: This component is responsible for building the required cache, by querying the input models or storing the necessary information - > before executing the Converters for specific migration step ( e.g. 0.9.0 to 0.9.1)
Scope of each Cache Builder component is only during a step of model migration ( e.g. 0.9.0 to 0.9.1)

Cache Builder can be registered by adding extension definition for : org.eclipse.app4mc.amalthea.model.converters.cachebuilders and defining the following parameters :

ID : This is the unique identifier of a Cache Builder component with which it is identified
name : Name of the component
class : Java class implementing org.eclipse.app4mc.amalthea.converters.common.base.ICache interface and providing implementation for following methods : public void buildCache(final Map<File, Document> fileName_documentsMap), public Map<File, Map<String, Object>> getCacheMap(), public void clearCacheMap()
enabled : By specifying true/false - > specific Cache Builder components invocation can be enabled or disabled
input-model-version : AMALTHEA model version in which the model content is present.

Each Cache Builder component is tightly coupled to a specific AMALTHEA model version

Pre Processor: This component is responsible for fetching/modifying specific information before invocation of Cache Builders/Converters components.

This component is tightly coupled to input version of the AMALTHEA model files which are selected (explicitly/implicitly) for model migration. Each Pre-Processor component is executed only once for the input model files, irrespective of number of migration steps.

Pre Processor component can be registered by adding extension definition for : org.eclipse.app4mc.amalthea.model.converters.preprocessor and defining the following parameters :

ID : This is the unique identifier of a Pre-Processor component with which it is identified
class : Java class implementing org.eclipse.app4mc.amalthea.converters.common.base.IPreProcessor interface and providing implementation for method : public void process(final File targetFile, final Map<File, Document> fileName_documentsMap) throws Exception
input-model-version : AMALTHEA model version in which the model content can be present. There is a possibility to specify multiple input-model-version’s, during the runtime if the supplied AMALTHEA models version matches to at least one of the specified versions - > then corresponding pre-processor is executed

Each Pre processor component is tightly coupled to the specified AMALTHEA model versions

Post Processor: This component is responsible for adding/modifying specific information after invocation of Cache Builders/Converters components for a specific migration step ( e.g. 0.9.0 to 0.9.1)

This component is tightly coupled to input and output version of the AMALTHEA model files which are selected (explicitly/implicitly) for model migration. Each Pre-Processor component is executed after the migration step if the below criteria is full filled:

Post Processor component can be registered by adding extension definition for : org.eclipse.app4mc.amalthea.model.converters.postprocessor and defining the following parameters :

ID : This is the unique identifier of a Post-Processor component with which it is identified
class : Java class implementing org.eclipse.app4mc.amalthea.converters.common.base.IPostProcessor interface and providing implementation for method : public void process(final Map<File, Document> fileName_documentsMap, final AbstractHelper helper) throws Exception
input-model-version : AMALTHEA model version in which the model content can be present. There is a possibility to specify multiple input-model-version’s.
output-model-version : AMALTHEA model version to which the model content is converted as a part of one of the migration step. There is a possibility to specify multiple output-model-version’s.

Example how Post-Processor’s are invoked:

If Post-Processor is defined with input-model-versions :0.9.0, 0.9.1 and output version 0.9.2.In case if the migration is invoked from 0.9.0 to 0.9.2 for the specified AMALTHEA models.Following migration steps are to be performed internally:

0.9.0 to 0.9.1
0.9.1 to 0.9.2

In this case post-processor is invoked after migration step 0.9.1 to 0.9.2

Flexibility of post-processors is, they are defined in a generalized way to specify in the direction which they should be invoked as a part of model migration.

Model migration sequence

Sequence in which various components are invoked during model migration

How to add custom Model Migration components

As described above, Model Migration framework is part of org.eclipse.app4mc.amalthea.converters.common plugin. This plugin should be added as a dependency to the custom plugin which shall contain Model Migration components.

Below are the various extension points available as a part of Model Migration framework:

For defining custom Model Migration, minimum requirement is to define a extension for org.eclipse.app4mc.amalthea.model.converters extension point and specify the class which has the implementation for migrating the model contents.

CacheBuilders, PreProcessor, PostProcessor components are optional - > based on the scenarios to migrate the model elements, it must me decided if these components are required.