Migrating your Mule ESB 2.2.x Transport to 3.1.1

A few days ago I decided to do the exercise of migrating an existing transport (JPA) to be compliant with Mule 3.1.1, and after a couple of hours reading and a few minutes of coding I finally got it working. I would like to share some tips that may help you to migrate your own transport.

1. RTM: I mentioned hours of reading, but it wasn’t that hard. You may be able to migrate your transport just following this blog post, but in case you need more information, you can read Migrating Mule 2.2 to 3.0 or if your transport is older you can check the correct guide here.
2. Edit your project pom.xml file and change the version of Mule to a newer one (in my case 3.1.1). In most cases you will just have to edit the property mule.version. If not you will have to update all the Mule dependencies inside the Maven build file. You may also want to upgrade the version of your transport too. This will cause your project to display some compilation errors.
   
3. If your Connector class extends AbstractConnector, you will need to have a constructor that receives an instance of org.mule.api.MuleContext.
4. Edit your transport properties file (META-INF/services/org/mule/transport/{your-transport}.properties*) and apply the following changes:
   • Replace message.adapter with message.factory. If you were using org.mule.transport.DefaultMessageAdapter as message.adapter, you just need to replace if with org.mule.transport.DefaultMuleMessageFactory for message.factory. For more information you can visit Mule 3.x Message Adapter removal.
   • Add the following properties inbound.exchange.patterns and outbound.exchange.patterns to define the supported exchange patterns for both the inbound and outbound endpoint of your transport. Possible values are one-way and request-response (use a comma if both values are supported).
   • Add the property default.exchange.pattern to set the default exchange pattern (one-way or request-response).

   * Important: If the configuration file yourtransport.properties is located in META-INF/services/org/mule/providers you should move it to META-INF/services/org/mule/transport/, if not you’ll get “org.mule.api.registry.ServiceException: Failed to load transport: org/mule/transport yourtransport”.
   

   # This file is the service descriptor for your transport
   # It ties all the implementation classes together so that Mule can
   # construct endpoints for your transport protocol at runtime
   # For a full list of properties that can be set here see -
   # http://mule.mulesource.org/x/FwKV
   
   # The connector class for your transport. This is always required
   connector=org.mule.transport.{your-transport}.{your-transport}Connector
   
   # Remove as part of the migration from 2.x to 3.x
   #message.adapter=org.mule.transport.DefaultMessageAdapter
   message.factory=org.mule.transport.DefaultMuleMessageFactory
   
   ...
   
   # Added for 3.x support
   inbound.exchange.patterns=one-way, request-response
   outbound.exchange.patterns=one-way, request-response
   default.exchange.pattern=one-way

5. If you need to create a MuleMessage you can now use the method createMuleMessage(Object) defined int the class AbstractTransportMessageHandler.
   
6. The method routeMessage in org.mule.transport.AbstractMessageReceiver class changed its signature and now receives a Transaction instead of a boolean.
   
7. Exceptions in Mule 3 are handled by the System Exception Handler, so for example, instead of using the method handleException to handle them, just throw them (the SystemExceptionHandler will take care of the exception).
8. XML/XSD schemas must be updated:
   • References to www.mulesource.org must change to www.mulesoft.org
   • Namespaces don’t have the version at the end of the URL, so for example http://www.mulesource.org/schema/mule/core/2.2 changes to http://www.mulesource.org/schema/mule/core
   • Versions change from 2.2 to 3.1.
   latest report

   Learn why we are the Leaders in API management and iPaaS

   Read reports

   With this in mind, you should change the following files (mule-{your-transport}.xsd, spring.handlers and spring.schemas) inside META-INF.
   

   <xsd:schema xmlns="http://www.mulesoft.org/schema/mule/{your-transport}"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:mule="http://www.mulesoft.org/schema/mule/core"
               xmlns:schemadoc="http://www.mulesoft.org/schema/mule/schemadoc"
               targetNamespace="http://www.mulesoft.org/schema/mule/{your-transport}"
               elementFormDefault="qualified"
               attributeFormDefault="unqualified">
   
       <xsd:import namespace="http://www.w3.org/XML/1998/namespace"/>
       <xsd:import namespace="http://www.mulesoft.org/schema/mule/core"
                   schemaLocation="http://www.mulesoft.org/schema/mule/core/3.1/mule.xsd" />
       <xsd:import namespace = "http://www.mulesoft.org/schema/mule/schemadoc"
                   schemaLocation = "http://www.mulesoft.org/schema/mule/schemadoc/3.1/mule-schemadoc.xsd"/>
   

   
   
   

9. AbstractMuleTestCase exposes the property muleContext that should now be passed to several methods used inside test cases.
   
10. If you have Mule XML configuration files in your project (used as example or inside test cases) you need to upgrade them to the new version of Mule. Besides the changes described before (modifying www.mulesource.org to www.mulesoft.org, removing the version from the namespaces and changing the schema versions) you should also modify the synchronous=”[true|false]” to exchange-pattern=”[one-way|request-response]”. As stated before you should check the corresponding Migration Guide.

If you have your own Mule 2.x compliant transport, you may want to migrate it to the newer versions of Mule to reach a broader audience of users. I will be glad to hear about your own migration experience too.