- Menu
- Sitemap
Guide - Automated Source Code Migration
1 Introduction
This document is a guide to help users to create and apply source code migration scripts. Such scripts refactor existing source code of cartridges. While dbmigrate-scripts migrate server data, source code migration scripts migrate sources and artifacts inside cartridges. Therefore these cartridges need to be re-build and deployed afterwards in order to work.
2 Source Code Migration Task Models
Source code migration task models are scripts that describe refactoring steps. Since refactoring is an essential part of development and software maintenance cartridges might introduce code-incompatible changes between major releases. These changes could require changes of other code or artifacts located in other cartridges that reference or depend on the changed artifacts. Source code migration steps will compute such references and apply necessary changes.
The migration scripts are XML-files that are located in the cartridge-content folder. The name of the migration scripts has suffix *.migrationtask.
2.1 Create and Edit Source Code Migration Task Models
Intershop Studio provides a wizard that can be used to create an empty Source Code Migration Task Model.
An editor is available that allows to create and edit migrations tasks.
2.2 Apply Source Code Migration Task Models
Intershop Studio contains actions and wizards that allows to apply migration steps. In order to apply the migration your cartridges need to be imported into the workspace. There is no support to easily undo migration steps. So it is recommended to at least save the original state of your cartridges. Select a cartridge and use menu 'Edit/Apply Migration Taks...'.
3 Source Code Migration Tasks
3.1 General Elements
Source code migration models describe refactoring steps and tasks. These steps are declared as <migrationTasks xsi:type="migrationtask:ElementChangedTask">
(Element Changed Task). To structure models tasks can be grouped inside <migrationTasks xsi:type="migrationtask:MigrationTaskContainerTask"> (Migration Task Container Task). Migration task might contain following attributes:
- name: A name of the task. Used for labels
- description: A brief description. Used, e.g., in tool tips.
3.2 Element Changed Task
An element changed task contains an entry describing the elements before the change: <elementDescriptor/>. An element descriptor has the attributes:
- elementType: A URI describing the type of the element. E.g., http://www.intershop.de/pipelet/2010-Pipelet. In case of refactored Java types 'javaType' is used instead of a URI.
- elementName: The name of an element, e.g., a start node name 'Start'
- elementQualifiedName: The qualified name, e.g., for s start node 'Pipeline-Start'.
The actual change is specified in a<changeDescriptor/>. There exist the ElementAttributeChangeDescriptor to describe renamed or move elements. An attribute change descriptor supports following attributes:
- attributeName: The name of the affected attribute. Supported are: 'name', 'qualifiedName' and 'href'
- attributeOldValue: The old value before the change
- attributeNewValue: The new, refactored value
3.3 Example Source Code Migration Task Model
The following XML file contains several migration steps. It shows:
- How to handle the renaming and/or move of Java types
- How to declare that a pipeline start node, a pipelet, an ISML-template, or an localized text was renamed and/or moved.
<migrationtask:MigrationTaskModel xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:migrationtask="http://www.intershop.de/migrationtask/2013" name="Migration tasks of cartridge 'testcartridge' for target version '7.5'"
version="7.5" cartridge="testcartridge">
<migrationTasks xsi:type="migrationtask:ElementChangedTask" name="" description="Pipelet 'TestPipelet': Renamed and moved to newtestcratridge:TestPipeletNew">
<elementDescriptor elementType="http://www.intershop.de/pipelet/2010-Pipelet"
elementURI="" elementName="TestPipelet" elementQualifiedName="TestPipelet"/>
<changeDescriptor xsi:type="migrationtask:ElementAttributeChangeDescriptor" attributeName="href"
attributeOldValue="enfinity:/testcartridge/pipelets/TestPipelet.xml" attributeNewValue="enfinity:/newtestcartridge/pipelets/TestPipeletNew.xml"/>
</migrationTasks>
<migrationTasks xsi:type="migrationtask:ElementChangedTask" name="" description="Renamed Start Node 'Start' to 'StartNew'">
<elementDescriptor elementType="http://www.intershop.de/pipeline/2010-StartNode"
elementURI="" elementName="Start" elementQualifiedName="TestPipeline-Start"/>
<changeDescriptor xsi:type="migrationtask:ElementAttributeChangeDescriptor" attributeName="name"
attributeOldValue="Start" attributeNewValue="StartNew"/>
</migrationTasks>
<migrationTasks xsi:type="migrationtask:ElementChangedTask" name="" description="Renamed Start Node 'TestPipeline-Start' to 'TestPipelineNew-StartNew'">
<elementDescriptor elementType="http://www.intershop.de/pipeline/2010-StartNode"
elementURI="" elementName="Start" elementQualifiedName="TestPipeline-Start"/>
<changeDescriptor xsi:type="migrationtask:ElementAttributeChangeDescriptor" attributeName="qualifiedName"
attributeOldValue="TestPipeline-Start" attributeNewValue="TestPipelineNew-StartNew"/>
</migrationTasks>
<migrationTasks xsi:type="migrationtask:ElementChangedTask" name="" description="Renamed and moved Template 'folder/test' to 'newfolder/newtest'">
<elementDescriptor elementType="http://www.intershop.de/template/2010-Template"
elementURI="" elementName="test" elementQualifiedName="folder/test"/>
<changeDescriptor xsi:type="migrationtask:ElementAttributeChangeDescriptor" attributeName="qualifiedName"
attributeOldValue="folder/test" attributeNewValue="newfolder/newtest"/>
</migrationTasks>
<migrationTasks xsi:type="migrationtask:ElementChangedTask" name="" description="Renamed LocalizedTest 'test_a' to 'test_a_new'">
<elementDescriptor elementType="http://www.intershop.de/localization/2010-LocalizationText"
elementURI="" elementName="test_a" elementQualifiedName="test_a"/>
<changeDescriptor xsi:type="migrationtask:ElementAttributeChangeDescriptor" attributeName="qualifiedName"
attributeOldValue="test_a" attributeNewValue="test_a_new"/>
</migrationTasks>
<migrationTasks xsi:type="migrationtask:ElementChangedTask" name="" description="Renamed and moved Java class 'testcartridge.capi.TestInterface' to 'testcartridge.capi.otherpackage.TestInterfaceNew'">
<elementDescriptor elementType="javaType" elementURI="" elementName="TestInterface"
elementQualifiedName="testcartridge.capi.TestInterface"/>
<changeDescriptor xsi:type="migrationtask:ElementAttributeChangeDescriptor" attributeName="name"
attributeOldValue="testcartridge.capi.TestInterface" attributeNewValue="testcartridge.capi.otherpackage.TestInterfaceNew"/>
</migrationTasks>
</migrationtask:MigrationTaskModel>
Disclaimer
The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.