Notes on Migrating MuleForge 2.2.x Transports to 3.0

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

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

Why Migration Is Needed

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

Note that once your Transport is migrated to Mule 3.0, it will no longer work with Mule 2.2.x. You will essentially need to maintain a version of your Transport for each major Mule version (2.2.1, 3.0.0).

Key Migration Artifacts

Example Migration

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

Preparation

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

• Background Reading. Start off by reading some of the Mule 3.0 Documentation, such as What's new and Migrating to 3.0.
• 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.
• 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-3.0.x" to signify that it is a Mule 3.0-compatible version of the Transport.

Migration Steps

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

Migration to 3.0 involves the following steps:

Update Dependencies in POM

1. Start by updating the dependencies in your Maven POM file (pom.xml).
   Specifically, you'll want to start off by changing the following:
   1. Change the <version> in the POM from "2.2.1" to "3.0.0 (3.0.0-RC2-SNAPSHOT until we release)" (or appropriate minor version of 3.0.x).
   2. Most standard MuleForge POM files have a property called <muleVersion> which is used by Mule dependencies laster in the POM.  Change <muleVersion> value from 2.2.1 to "3.0.0 (3.0.0-RC2-SNAPSHOT until we release)".  To match the standard in the Transport Archetype project, you may also want to change <muleVersion> to <mule.version>.
   3. 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.
   4. 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).

Update the XML Schema

1. 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. 
   Just as a checkpoint, you have completed this task when:
2. References to mulesource have been updated to mulesoft; i.e. http://www.mulesource.org/schema to http://www.mulesoft.org/schema
3. The version number has been removed from the xmlns declaration; i.e. http://www.mulesource.org/schema/mule/core/2.2 to http://www.mulesoft.org/schema/mule/core
4. The version number has been removed from the targetNamespace attribute; i.e. targetNamespace="http://www.mulesource.org/schema/mule/sftp/2.2" to targetNamespace="http://www.mulesoft.org/schema/mule/sftp"
5. There is a new annotation block:

   <xsd:annotation>
       <xsd:documentation>
        The SFTP transport provides connectivity to 
        SFTP servers to allow files to be read and 
        written as messages in Mule.
       </xsd:documentation>
      <xsd:appinfo>
            <schemadoc:short-name>SFTP</schemadoc:short-name>
            <schemadoc:page-title>SFTP Transport</schemadoc:page-title>
            <schemadoc:transport-features receiveEvents="true" dispatchEvents="true"
                  requestEvents="true" retries="false"
                  transactions="false" streaming="true">
                <schemadoc:MEPs supported="one-way, request-response" default="one-way"/>
          </schemadoc:transport-features>
      </xsd:appinfo>
   </xsd:annotation>
   

6. For SFTP, the schema definition was named "mule-sftp.xsd" and had a targetNamespace of "http://www.mulesource.org/schema/mule/sftp/2.0"

Update the Namespace Handler

1. If you use the expression filename parser from the ftp transport, add this line to your NameSpaceHandler.init() method:

   registerBeanDefinitionParser("expression-filename-parser",
   new ChildDefinitionParser("filenameParser", 
   ExpressionFilenameParser.class));
   

2. Updating the <transport>.properties file.
   1. Add a message.factory property: message.factory=org.mule.transport.DefaultMuleMessageFactory
      See the migration guide for more details.
   2. Define the exchange patterns for inbound/outbound/default.

      inbound.exchange.patterns=one-way,request-response
      outbound.exchange.patterns=one-way,request-response
      default.exchange.pattern=one-way
      

3. Update the Functional Test classes to use the Mule 3.0 API.
   See Functional tests in SFTP Test Cases for examples.
4. Update your Mule configurations used by Functional Tests
   This step provides the most insight into the changes made in 3.0, because here is where you change actual Mule configurations to use the 3.0 format. Here are some Before and After snapshots of Mule configurations from SFTP Test Cases.

Notes from legstar transport conversion

1. The legstar protocol uses the metascheme legstar (as in legstar:http://host:port). The problem is with ServiceDescriptorFactory#isFilteredMetaScheme which now filters out my metascheme.
   As a result, the TransportFactory instantiates an HttpConnector instead of a LegStarHttpConnector. I wasn't satisfied with my metascheme anyway (I support 4 sub-transports: tcp, websphere MQ and http).
   1. Solution: I changed my http scheme from legstar:http to legstar (URIs now look like legstar://host:port, rather than legstar:http://host:port).
2. A test for a Dispatcher fails with NPE. This was due to the fact that my Dispatcher was overriding getConnector to return a local reference to the Connector. This was not an issue in Mule 2.0 because AbstractMessageDispatcher did not override the createLifecycleManager method so there was no attempt to access the Connector so early in the constructor.
   1. Solution: I changed the overriding code to cast the connector from the endpoint.
3. Percolation of HTTP headers cause problems. This is a case where my inbound and outbound endpoints both use HTTP. It looks like HTTP headers (such as content-type) are being percolated from 1 endpoint to the other. This is wrong because the payload returned to the
   client (via the inbound endpoint) is not necessarily the same as the one returned from the outbound endpoint. This of course results from response transformers being applied.
   Somehow this was not happening in Mule 2.0
   1. Solution: I fixed this by overriding HttpClientMessageDispatcher#getResponseFromMethod to explictly remove the content-type and content-length which were left over. I think a cleaner solution should be found as part of the pipeline processing.