Migrating Mule 2.1 to 2.2

Table of Contents

Click here to expand...

This page describes the major configuration and code changes in Mule 2.2 to help Mule 2.1 users understand what has changed between releases. If you are migrating from an earlier 1.x version of Mule ESB, please read Migrating Mule 1.x to 2.0 and Migrating Mule 2.0 to 2.1 respectively.

Spring Security 2.0

In Mule 2.2, Acegi security has been deprecated and support for Spring Security 2.0 has been added. You should migrate your configurations to use Spring Security 2.0 as described here (login required).

Endpoint Configuration

The @remoteSync attributes on endpoints has been removed. This also removes the confusion around how endpoint synchronicity is configured and behaves. As of Mule 2.1 the synchronicity of an endpoint had to be specifically defined on every endpoint (otherwise the default for the Mule instance is used). Now the following rules apply when configuring endpoints:

1. If the endpoint is asynchronous a result is never returned
2. If the endpoint is transacted a response cannot be read from a back channel (i.e. JMSReplyTo)
3. If the endpoint is synchronous, it will always return a result even if the result is null, a NullPayload will be returned. This behaviour tries to open a back channel to receive a result, this is the equivalent to @remoteSync=true. The new @responseTimeout configuration option on the endpoint allows Mule to timeout if nothing has been received via a back channel.

Back channel A back channel is a communication channel that allows a a call over an endpoint to return data. In client sockets, this would be the input stream on the socket, for JMS, the JMSReplyTo feature provides a channel for the remote server to send a result back. Transports such as file and FTP do not have a back channel.

JMS Temporary Destinations

When a JMS outbound endpoint is synchronous and not transacted, Mule will attempt to open a back channel to receive a result. If a replyTo destination is not set, it will attempt to use a temporary destination. This behavior can be turned off using the new @disableTemporaryReplyToDestinations flag on the JMS connector or endpoint.

Including Custom Header Properties

Previously, if you wanted custom header properties to be included in an outbound HTTP endpoint, you had to add them to an http.custom.headers property map on the outbound endpoint. Now, you simply set them as properties. The old approach is still supported.

Single Endpoint for Filtering Routers

The outbound filtering router now accepts only one endpoint. To use multiple endpoints, use a different outbound router and specify filters on the individual endpoints.

Deprecated MessageBuilder API

The MessageBuilder API, including ReflectionMessageBuilder and ScriptMessageBuilder, has been deprecated. Use a component with bindings instead. For more information, see Component Bindings.

MuleMessage API

Some new methods were added to the MuleMessage and MessageAdapter APIs for allowing users to set properties on a specified scope.

There have been two new methods added:

Expressions

There have been several changes to expressions. You can now use an asterisk to indicate optional properties (see Expressions Configuration Reference). Additionally, there have been several API changes as described in this section.

Expression API Packages Changes

The Expression API has been refactored to reflect the correct package structure. The following changes were made:

Expression Evaluator API

The API for the ExpressionEvaluator has changed slightly to make it strongly typed. The message is now a MuleMessage not a java.lang.Object.

Object evaluate(String expression, MuleMessage message);

Expression Manager

The ExpressionManager (was ExpressionEvaluatorManager) is no longer a singleton object. To obtain a reference to the manager, you get it from the MuleContext using the getExpressionManager() method. Objects that need the MuleContext can implement org.mule.api.context.MuleContextAware .

Nested Router Classes Names Changed

The Nested Router classes have been renamed to Component Binding. There were several class changes associated with this name change. For example, the NestedRouterTestCase.java classes were renamed to ComponentBindingTestCase.java, NestedCollectionTestCase.java was renamed to BindingCollectionTestCase.java, the nested package was renamed to binding, and more. For a complete list, see http://fisheye.codehaus.org/changelog/mule/?cs=13410.

Other API Changes

The following defines other minor API refactorings. Changes in this section are minor and only include package or name changes.

Transport Behavior

Some transport such as FTP and File, which do not support a back channel, were returning the current message as the response when called synchronously. This gives the impression that a result was received from a remote call, which is incorrect. The behavior has now been changed in Mule 2.2 so that synchronous FTP and File endpoints will return null ( NullPayload ).

Testing

A new test component type has been introduced into the test namespace.

<test:web-service-component/>

This is a component that can be used for testing web services. This component has the same properties as the test:component but it also implements three other service interfaces: org.mule.api.component.simple.EchoService , org.mule.tck.testmodels.services.DateService and org.mule.tck.testmodels.services.PeopleService . The other service interfaces that are implemented are org.mule.api.lifecycle.Callable .
When using this with WS endpoints such as CXF, be sure to set the serviceClass property of the endpoint to the type of service you are using.

Define the 'serviceClass' Property for CXF

Due to a change in the <test:component>, which also applies to the <test:web-service-component>, you now need to set the service class on the CXF inbound endpoint when using these components. The service class can be one of the following:

• org.mule.api.component.simple.EchoService
• org.mule.tck.testmodels.services.DateService
• org.mule.tck.testmodels.services.PeopleService
• org.mule.api.lifecycle.Callable

For example, to expose the PeopleService for testing, use:

<service name="PeopleService">
    <inbound>
        <cxf:inbound-endpoint address="http://localhost:62109/mule/services/people"
                       serviceClass="org.mule.tck.testmodels.services.PeopleService"/>
    </inbound>
    <test:web-service-component/>
</service>

Schema Changes

The table below lists the schema changes that have been made since 2.1 and describes how to migrate this change in your application.

CXF Endpoint Handling

By default, Mule now applies transformers, security, and filters on CXF endpoints to the raw XML message instead of to the payload that is received from CXF. To change this behavior, set the applyTransformersToProtocol, applySecurityToProtocol, and applyFiltersToProtocol attributes to false as needed. For example:

<cxf:inbound-endpoint address="http://localhost/service" applyTransformersToProtocol="false"/>

Maven OSGi Libraries

Significant work was done to clean up the use of OSGi rebundled dependencies in Mule. Mule now uses it's own custom OSGi plugin which preserves the original groupId, artifactId, POM, and sources for an artifact. This plugin just changes two things: it adds an OSGi bundle manifest and it also changes the version so that it includes a "-osgi" at the end.

If you found yourself excluding a lot of dependencies with Mule 2.0/2.1 because they conflicted with the normal groupIds/artifactIds, you should not have to do this any more.

Mule Enterprise Edition Changes

This section describes changes that apply to Mule Enterprise Edition only.

New Schema Namespace Conventions

The Mule Enterprise Edition schema namespace conventions have been revised to simplify the upgrade path from the Community Edition to the Enterprise Edition:

• Use www.mulesource.org instead of www.mulesource.com
• The URI has the /ee sub-tree
• Schema filename has the -ee suffix

For example:

http://www.mulesource.org/schema/mule/ee/jdbc/2.2 http://www.mulesource.org/schema/mule/ee/jdbc/2.2/mule-jdbc-ee.xsd

Changes to Retry Strategies

The retry stategies schema has been merged with other new elements into a more generic Mule EE core schema:

http://www.mulesource.org/schema/mule/ee/core/2.2 http://www.mulesource.org/schema/mule/ee/core/2.2/mule-ee.xsd

Retry schema elements have been renamed for better grouping when using the MULE IDE's auto-completion feature:

Additionally, the three policy elements now accept the asynchronous attribute, which specifies whether the retry policy should run in a separate, non-blocking thread.