Under Construction.

Notes on Migrating MuleForge 1.4.x Transports to 2.0

This page contains notes from the recent migration of the SFTP Transport to 2.0.

These notes may help you migrate existing MuleForge Transport project from Mule 1.4.x to 2.0. Migration of Non-Transport and 1.3.3 Transport projects is not covered here, although you may be able to use this information to do that.

Why Migration Is Needed

Mule 2.0 does not support backward compatibility with Transports written for Mule 1.x. There are a number of code and configuration changes required to make to your 1.x Transport compatible with Mule 2.x. This document walks you through the process of migrating your Mule 1.4.x Transport to 2.0.

Note that once your Transport is migrated to Mule 2.0, it will no longer work with Mule 1.x. You will essentially need to maintain a version of your Transport for each major Mule version (1.3.x, 1.4.x, 2.0.x).

Key Migration Artifacts

Example Migration

This section presents all the steps used to migrate the SFTP Transport to Mule 2.0.

Preparation

The following preparation is suggested before getting started with the migration:

1. Background Reading.  Start off by reading some of the Mule 2.0 Documentation, such as What's New in Mule 2.0 and Creatng an XML Namespace.
2. Create a Reference Archetype. Optionally, you may want to run the Transport Archetype, which will create a starter Transport project which may be a useful reference during the migration process.  Doing a diff between your current project and the archetype project will give you an idea of a standard 2.0 Transport layout.
3. Branch.  While not required, you may want to create a branch in your Muleforge SVN space for your migration work.  It is suggested that you name it "mule-2.0.x" to signify that it is a Mule 2.0-compatible version of the Transport.

Migration Steps

Use of an IDE like Eclipse or IDEA is highly recommended and assumed for when carrying out the steps below.

Migration to 2.0 involves the following steps: 

1. Update Dependencies in POM.  Start by updating the dependencies in your Maven POM file (pom.xml).   Specifically, you'll want to start off by changing the following:
   • Change the <version> in the POM from "1.4.x" to "2.0.1-SNAPSHOT" (or appropriate minor version of 2.0.x).
   • Most standard MuleForge POM files have a  property  called <muleVersion> which is used by in Mule dependencies laster in the POM.  Change <muleVersion> value from 1.4.x to "2.0.1-SNAPSHOT".  To match the standard in the Transport Archetype project, you may also want to change <muleVersion> to <mule.version>.
   • Some Maven artifactId values have changed in 2.0  For example, "mule-transport-stream" is now "mule-transport-stdio".  You'll need to update these in your POM.
   • There are also many other  changes you might want to consider.   Compare your POM to the the one generated by the Transport Archetype for more possibilities.
   • After updating your POM, update your project classpath so that the new dependencies are available in your IDE.  (For example, run "mvn eclipse:eclipse" and import the project into Eclipse).
2. Update API in Core Transport Java Classes.  The location of your Core Transport classes is probably in a package like org.mule.providers.<transportId>.  In the case of SFTP, this iset ncluded the classes SftpConnector, SftpMessageReceiver, SftpMessageDispatcher, and SftpMessageDispatcherFactory.   You will need to change all the references to the old Mule API in these classes.  Some of the common changes made were:

   1.4.x API	2.0.x API
   org.mule.umo.UMOMessageReceiver	org.mule.api.transport.MessageReceiver
   org.mule.umo.UMOMessageDispatcher	org.mule.api.MessageDispatcher
   org.mule.umo.UMOEndpointURI	org.mule.api.EndpointURI
   org.mule.umo.UMOEndpoint	org.mule.api.InboundEndpoint
   org.mule.umo.UMOImmutableEndpoint	org.mule.api.OutboundEndpoint
   org.mule.umo.UMOException	org.mule.api.MuleException
   org.mule.umo.UMOMessage	org.mule.api.MuleMessage
   org.mule.umo.UMOEvent	org.mule.api.MuleEvent
   org.mule.umo.lifecycle.InitialisationException	org.mule.api.lifecycle.InitialisationException

   Also, it is recommended that you refactor your org.mule.providers package structure to org.mule.transport, for consistency with other 2.0 Transports.
   Once your project is compiling again, you can move on to the next step, which is required before actually testing the changes made here.

3. Create a Configuration Handler.  This topic is covered in detail in the "Writing a Configuration Handler" section of the XML Namespace guide.  However, here are a few notes that may help.
   • Defining the XML Schema.  The easiest thing to do for SFTP was to use an XSD for a similar Transport.  Given the similarity between transports, the FTP XML Schema was used as a starting point for the SFTP schema.  In general, try browsing the src/main/resources/META-INF folders of existing 2.0 transports for XSDs to see if you have a close match for your Transport.   Then use the "Defining the Schema" section of the XML Namespace as a guide in making modifications.  
     Just as a checkpoint, you have completed this task when:
     • You have created a valid XML Schema file and placed it in src/main/resources/META-INF.   For SFTP, the schema definition was named "mule-sftp.xsd" and had a targetNamespace of "http://www.mulesource.org/schema/mule/sftp/2.0". 
     • You have created a spring.schemas mapping file and placed it in src/main/resources/META-INF.  This mapping ensures that your schema is loaded locally instead of from the schemaLocation specified in your XSD.
   • Write the Namespace Handler.  This is a fairly simple Java class that map the XML elements defined in the schema to a parser.  Again, here you may want to find a suitable starting point for your Transport.   For SFTP, the FTP Namespace Handler was used as a starting point.   See the "Definition Parsers" section of the XML Namespace guide for more details. 
     Just as a checkpoint, you have completed this task when:
     • You have created a Namespace handler Java class.  The SFTP Namespace Handler was placed in the org.mule.transport.sftp.config package. 
     • You have added the spring.handlers mapping file in src/main/resources/META-INF.
   • Testing all this covered in Step 4.
4. Testing.   There are 3 areas of testing relevant to the migration:
   • Configuration Handler Test Case.  This is covered in the "Testing" section of the XML Namespace guide.  Pretty easy to set up and test.  For SFTP, the SftpNameSpaceHandlerTestCase and associated sftp-namespace-config.xml file were ultimately produced.
   • Connector Test Cases.  The Transport Archetype provides a few good starter tests for any Transport.  For SFTP, this included SftpConnectorFactoryTestCase, SftpConnectorTestCase, and SftpEndpointTestCase, among others. See the SFTP Test Cases for details.
   • Functional Test Cases.  Most of the work to migrate test cases involves updating your current Functional Test Cases.  There are two parts to this:
     • Updating your Functional Test classes to use the Mule 2.0 API.   This included all the changes from Step2, along with minor changes like using MuleClient.request() instead of MuleClient.receive(), and new package neame for MuleClient (org.mule.module.client).  See Functional tests in SFTP Test Cases for examples.
     • Updating your Mule configurations used by Functional Tests.  This step provides the most insight into the changes made in 2.0, because here is where you change actual Mule configurations to use the 2.0 format.  Here are some Before and After snapshots of Mule configurations from SFTP Test Cases.