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.
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.
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.
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...'.
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:
An element changed task contains an entry describing the elements before the change: <elementDescriptor/>. An element descriptor has the attributes:
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:
The following XML file contains several migration steps. It shows:
<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>
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.