Mule 3 Migration Guide
Transcript of Mule 3 Migration Guide
Mule ESB Migration Guide
Migrating Mule ESB 2.2 to Mule ESB 3
Migrating Mule ESB 2.2 to Mule ESB 3.0[ ] [ ] [ ] [ ] [ ] [ Access to MuleContext Deployment Model MuleMessage CXF Migration Consistent use of Mule's expression language Queueing in
] [ ] [ ] [ ] [ ] [ ] [ the VM connector Inbound Transformers Default Transport Transformers MessageDispatchers Model/Service Inbound Routers ] [ ] [ ] [ ] [ ] [ Outbound Routers Message Info Mapping Endpoint configuration Exception Strategy Reconnection Strategies (ex-Retry Policies)
] [ ] [ ] [ ]Expression Evaluators jBPM Transport Summary of API Changes Schema Namespace change
One of the major changes in Mule 3.0 is that the is no longer available from a static context. This makes the Mule instanceMuleContextproperly contained and easier to embed in other environments such as OSGi.
Access to MuleContext
We have removed the methods for accessing the MuleContext or Registry statically. Therefore, is no longerMuleServer.getMuleContext()static, and has been removed completely. You can now access the in the following ways:org.mule.impl.RegistryContext MuleContext
From within a component class, implement , and Mule will inject the instance for you before theorg.mule.api.MuleContextAwareinitialize lifecycle phase.From within a transformer, extend or , and the 'muleContext' variableAbstractTransformer AbstractMessageAwareTransformeris available in the base class.From a JSP page or Servlet, the MuleContext is available in the ServletContext using
.servletContext.getAttribute(MuleProperties.MULE_CONTEXT_PROPERTY)Inbound and outbound routers have the 'muleContext' variable in the base classes.From any other object configured via a configuration builder (such as XML or scripting), implement
to have the current instance injected.org.mule.api.MuleContextAware
Deployment Model
The deployment model has changed from Mule 2.2.x to Mule 3.0. You can find more information .here
MuleMessage
If you ever need to create an instance (usually Mule will handle this for you), you must pass in the current org.mule.DefaultMuleMessage as described in the previous section.MuleContext
TransactionManagerFactory
The method on now accepts a create() org.mule.api.transaction.TransactionManagerFactory parameter, which can be used to set global transaction configuration on the transaction manager.org.mule.MuleConfiguration
A Spring-based object has been added that can beorg.mule.config.spring.factories.MuleTransactionManagerFactoryBeanused inject the current TransactionManager into other objects. This is useful when configuring XA data sources that need access to theTransactionManager instance.
<mule xmlns="http://www.mulesource.org/schema/mule/core" =xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" =xmlns:spring "http://www.springframework.org/schema/beans" =xmlns:jbossts "http://www.mulesource.org/schema/mule/jbossts" xsi:schemaLocation=" http://www.springframework.org/schema/beanshttp://www.springframework.org/schema/beans/spring-beans-2.5.xsd http://www.mulesource.org/schema/mule/corehttp://www.mulesource.org/schema/mule/core/3.0/mule.xsd http://www.mulesource.org/schema/mule/jbosstshttp://www.mulesource.org/schema/mule/jbossts/3.0/mule-jbossts.xsd">
<jbossts:transaction-manager/>
<!-- grab the transaction manager that is configured in Mule, in this case Ajruna --> <spring:bean id= class="muleTM"
/>"org.mule.config.spring.factories.MuleTransactionManagerFactoryBean"
<!-- Data Source --> <spring:bean id= class="jdbcDataSource" "org.enhydra.jdbc.standard.StandardXADataSource"destroy-method= >"shutdown" <spring:property name= ref= />"transactionManager" "muleTM" <spring:property name= value= />"driverName" "org.apache.derby.jdbc.EmbeddedDriver" <spring:property name= value= />"url" "#{database.connection}" </spring:bean><mule>
Object Serialization
Serialization of objects such as , and need access to the DefaultMuleMessage DefaultMuleSession DefaultMuleEvent MuleContextonce they have been deserialized. The new marker interface provides thisorg.mule.util.store.DeserializationPostInitialisableaccess. This interface works in the same way as the Java interface. It is a marker that expects a private (or protected) method to beCloneablepresent on the object. Implementers of this interface must add the following method to their class:
void initAfterDeserialization(MuleContext muleContext) MuleExceptionprivate throws
This method will get invoked after the object has been deserialized passing in the current {{MuleContext} when using any of the followingserialization mechanisms in Mule:
org.mule.transformer.wire.SerializationWireFormatorg.mule.transformer.wire.SerializedMuleMessageWireFormatorg.mule.xml.transformer.wire.XStreamWireFormatorg.mule.transformer.simple.ByteArrayToSerializable transformerorg.mule.xml.transformer.XmlToObject XStream transformer
The reason for doing this rather than a regular interface method was not to clutter object interfaces with public methods that are only requiredwhen the object is serialized, especially since these objects are part of the public facing API.
AbstractMuleTestCase
A few new methods have been added to (and thus the org.mule.tck.AbstractMuleTestCase) to help wire objects via the Mule Registry. This means that when the objects areorg.mule.tck.functional.FunctionalTestCase
created or passed in, they will be added to the registry, and any required objects will be injected and the object lifecycle will be executed.
<T > T createObject( <T> clazz, ... args) Exceptionprotected extends Object Class Object throws
Create an object of instance . It will then register the object with the registry so that any dependencies are injected and then the object willclazzbe initialized. Note that if the object needs to be configured with additional state that cannot be passed into the constructor, you should create aninstance first, set any additional data on the object, and then call .initialiseObject(Object)
There is also a convenience method that will pass in empty arguments to the method above.createObject(Class)
void initialiseObject( o) RegistrationExceptionprotected Object throws
The is a convenience method that will register an object in the registry using its hashcode as the key. This will cause theinitialiseObjectobject to have any objects injected and lifecycle methods called. Note that the object lifecycle will be called to the same current.
CXF Migration
CXF is no longer a transport inside of Mule. Instead, it is a series of message processors. You'll need to use normal endpoints (non CXF) in yourconfigurations and these message processors in Mule 3. For more information, see upgrading CXF from Mule 2
Consistent use of Mule's expression language
Mule uses the expression language for the , and attributes in the file and FTP transports now.moveToPattern workFileNamePattern outputPatternThe previous patterns will no longer be recognized. See for instructions on converting the patterns.the ExpressionFilenameParser documentation
Queueing in the VM connector
The queueing behaviour in the VM transport was changed so that async endpoints always use queueing and sync endpoint never do, thisprovides suitable default behavior, eliminates the need to configure queuing explicitly and as this issue suggests makes configuring of queuingeasier by not even requiring it. The queueEvents attribute has been removed in 3.0.
Inbound Transformers
Inbound transformer are no longer invoked when the component is invoke but rather as part of the inbound message processing pipeline after thesecurity filter. This has a couple of consequences:
It is no longer possible to skip transformation by having a custom component that does not call .context.transformMessage()Inbound transformation always happens before any inbound router. This was the default in 2.2 so the onlySelectiveConsumerdifference is that now it is not possible to do the equivalent of "transformFirst=false"Inbound transformation always happens before any entry point resolvers. This was the default in 2.2 so the only difference is that now itis not possible to do the equivalent of "transformFirst=false"This change does affect the behavior of which although still respects the type and order of resolversLegacyEntryPointResolverSetused in Mule 1.x, no longer resolves before transformation.
Default Transport Transformers
In Mule 2.x, if you set a transformer on an endpoint, it would replace the default transport-specific transformer (e.g.,JMSMessageToObject/ObjectToJMSMessage in the case of a JMS endpoint). In 3.x, it will replace the default transformer, but rather thenotdefault will get applied any transformers you specify. If you wish to disable the default transformer, you can set the new attribute before
on the endpoint.disableTransportTransformer=true
MessageDispatchers
It is no longer the responsibility of the Dispatcher to transform messages. Any call such as: Object data = event.transformMessage();should be replaced with: Object data = event.getMessage().getPayload();If a Dispatcher needs special functionality before transformers are applied to the message, it can override the method AbstractMessageDispatcher.applyOutboundTransformers(MuleEvent event)
Model/Service
Direct/Pipeline service implementations have been removed. These were not exposed via configuration and are never really used.
Inbound Routers
Inbound routers are now invoked one after another in a pipeline fashion with the result of a router being used as the input for the nextinbound router.Because of this "matchAll" which default to "true" in 2.x no longer makes any sense and has been removed.
Another consequence of this approach is that filtering is easy to achieve by adding a filter where required and so existing inbound routers(apart from selective-consumer which is now simply implemented as a message filter) no longer accept child filter elements.The catchAllStrategy has been conserved but when it is invoked has changed; rather than being invoked when no inbound routers match,it will be invoked if any filters in the pipeline don't match.The ForwardingConsumer and SelectiveConsumer inbound routers are still supported but have been deprecated. You can no longer usethe ForwardingConsumer to selectively skip the component, you should do this with a instead.component interceptor
Outbound Routers
TemplateEndpointRouter has been removed. This functionality is available with almost all other routers (that extendFilteringOutboundRouter) by enabling useTemplates.The useTemplates value of FilteringOutboundRouter (and all subclasses) has i) been exposed in configuration ii) has it's default valuechanged from false to true.
Response Routers
ResponseRouter's no longer exist in code as they are now no different to inbound routers.CollectionAggregator is common to inbound and responseSingleResponseAggregator is now redundant and doesn't need to be configured.
The xml configuration still supports Mule 2.x response specific elementsWhen implementing your own ResponseAggregators you'll now need to extend org.mule.routing.AbstractCorrelationAggregator ratherthan org.mule.routing.response.AbstractResponseAggregator
Message Info Mapping
Now configured directly on the Service rather than having to be configured on the router. Simplifies configuration but not having to specify it onboth outbound and async-reply.
Endpoint configuration
The synchronous attribute on endpoints has been replaced by the exchange-pattern attribute. As a rule of thumb
use one-way where synchronous was set to false beforeuse request-response on endpoints that where synchronous before
Note that some transports do not allow to configure an exchange-pattern on transport specific endpoints. In this case, the transport supports onlya single exchange pattern which is assumed as default for all endpoints.
Exception Strategy
Exception strategies have been revamped for 3.0. See documentation
Reconnection Strategies (ex-Retry Policies)
Retry Policies have been renamed to Reconnection Strategies for 3.1 to avoid misunderstandings. See documentation
Expression Evaluators
Expressions including , , and can retrieve all headers or#[headers:] #[headers-list:] #[attachments:] #[attachments-list:]attachments in a given scope. The notation in Mule 2.2 for doing this was . IN Mule 3.0 the notation uses a '#[headers:all] ' instead of 'all'
or .#[headers:] #[headers:INBOUND:*]
jBPM Transport
The jBPM transport has been overhauled for 3.0, including an upgrade to the latest major version of jBPM (4.3), much simplified configuration,and cleaner integration with Mule from your process definition, including custom process elements.
Summary of API Changes
Mule 2.2 Mule 3.0 Notes
MuleMessage.get/setProperty() Deprecated, replaced with scope-aware methods
MuleMessage.getPropertyNames() Deprecated, replaced with scope-aware methods
MuleMessage.getStringProperty() Deprecated, replaced with scope-aware methods
DefaultMuleMessage(Object) DefaultMuleMessage(Object, MuleContext) more details
DefaultMuleMessage(Object, MuleMessageAdatper) DefaultMuleMessage(Object, MuleMessageAdapter,MuleContext)
more details
DefaultMuleMessage(Object message, Map properties) DefaultMuleMessage(Object message, Map properties,MuleContext muleContext)
more details
TransactionManagerFactory.create() TransactionManagerFactory.create(MuleConfiguration)
Transaction() Transaction(MuleContext)
MuleEndpointURI(String) MuleEndpointURI(String, MuleContext)
FutureMessageResult(Callable callable) FutureMessageResult(Callable callable, MuleContextmuleContext)
MessagingException(Message message, Object payload) Removed
MessagingException(Message message, Object payload,Throwable cause)
Removed
Added EndpointURI.getMuleContext() Implements MuleContextAware
EndpointURIBuilder.build(URI) EndpointURIBuilder.build(URI, MuleContext)
Added URIBuilder(MuleContext)
Added RetryContext.getMuleContext()
RouterResultsHandler.aggregateResults(List <MuleMessage>,MuleMessage)
RouterResultsHandler.aggregateResults(List<MuleMessage>,MuleMessage, MuleContext)
Added Transformer.transform(Object, String) Added so that encodingcan explicitly be passedin
ExceptionMessage.getEndpoint() Returns a string representation instead of EndpointURIinstance
Added DeserializationPostInitialisable A marker interface forpost deserializationinitialization
RegistryContext Removed Singleton class foraccessing the registry
static MuleServer.getMuleContext() MuleServer.getMuleContext() No longer a staticmethod
MuleServer.setMuleContext() Removed No More singletonreferences toMuleContext, you cannow have theMuleContext injectedusing the MuleContextAwareinterface or by using the javax.inject.Injectannotation (as of Mule3.0.0-M3).
AbstractEntryPointResolver.setTransformFirst() Removed Transformation nowalways occurs as part ofinbound endpoint
AbstractEntryPointResolver.isTransformFirst() Removed Transformation nowalways occurs as part ofinbound endpoint
SelectiveConsumer.setTransformFirst() Removed Transformation nowalways occurs as part ofinbound endpoint
SelectiveConsumer.isTransformFirst() Removed Transformation nowalways occurs as part ofinbound endpoint
ServiceCatchAllStrategy Removed
DirectService/DirectModel Removed
PipelineService/PipelineModel Removed
BridgeComponent Removed This was deprecated in2.x and has now beenremoved. For bridging,simply don't specify aComponent on yourService.
AbstractMessageReceiver Signatures updated to use FlowConstruct instead of Service
LifecycleAdapterFactoryDefaultComponentLifecycleAdapterFactoryDefaultComponentLifecycleAdapter
Signatures updated to take additional FlowConstructparameter
MuleEvent/MuleSession/MuleEventContext getService() replacement with getFlowConstruct()
org/mule/transport/file/SimpleFilenameParser use ExpressionFilenameParser see MULE-4479
AbstractMessageDispatcher.returnResponse(MuleEvent event) deprecated
org.mule.routing.response.AbstractResponseRouter response specific routers no longer exists, inbound routersare not used for async reply
org.mule.routing.response.AbstractResponseAggregator no longer exists, logic here is now done as part of async reply
org.mule.routing.response.ResponseCorrelationAggregator response specific routers no longer exist, inbound routers arenow used for async reply, extendorg.mule.routing.AbstractCorrelationAggregator forimplementing custom inbound/response aggregators
org.mule.routing.response.DefaultResponseRouterCollection response router collection no longer exists, an inbound routercollection is used for async reply
org.mule.routing.response.SimpleCollectionResponseAggregator org.mule.routing.SimpleCollectionAggregator
org.mule.routing.response.SingleResponseRouter Removed. No longer required as async-reply does replyaggregation now.
Schema Namespace change
We changed our company name from MuleSource to MuleSoft, and accordingly we changed our domain names too. The new namespaces forMule 3 reflect that and have been simplified a bit. In Mule 2.x namespaces for XML configuration files looked something like this -
<mule xmlns="http://www.mulesource.org/schema/mule/core/2.2" =xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" =xmlns:cxf "http://www.mulesource.org/schema/mule/cxf/2.2" xsi:schemaLocation=" http://www.mulesource.org/schema/mule/core/2.2http://www.mulesource.org/schema/mule/core/2.2/mule.xsd http://www.mulesource.org/schema/mule/cxf/2.2http://www.mulesource.org/schema/mule/cxf/2.2/mule-cxf.xsd">
</mule>
Below is the equivalent in Mule 3. Notice that the version has been removed from the namespace and now is only present in the actual schemalocation, this makes moving from one version of Mule to another easier since only the schema location is updated.
<mule xmlns="http://www.mulesoft.org/schema/mule/core" =xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" =xmlns:cxf "http://www.mulesoft.org/schema/mule/cxf" xsi:schemaLocation=" http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.0/mule.xsd http://www.mulesoft.org/schema/mule/cxf http://www.mulesoft.org/schema/mule/cxf/3.0/mule-cxf.xsd">
</mule>
Core Mule Schema Changes
Affects Change Description
All entry-point-resolvers elements transformFirstattribute removed
Transformation now always occurs as part of inbound endpoint
All selective consumer inbound routerelements
transformFirstattribute removed
Transformation now always occurs as part of inbound endpoint
<bridge-component> Removed This was deprecated in 2.x and has now been removed. Forbridging, simply don't specify a Component on your Service.
<transformers> wrapper for settingtransformers on an endpoint
Removed Simply list any transformer elements on the endpoint without the<transformers> wrapper.
<responseTransformers> wrapper for settingresponse transformers on an endpoint
Renamed to <response> This element was renamed because in the future you will be ableto add other message processors besides transformers.
<no-action-transformer> Moved to test module(mule-tests-functional.jar)
Use the new disableTransportTransformer attribute to explicitlydisable the default transformer for an endpoint.
Scripting
Affects Change Description
Scripted transformers andcomponents
Message properties are no longer bound as globalvariables of the script.
Use message.get<Scope>Property() to access thedesired property.
Testing
For transformer tests add: transformer.setMuleContext(muleContext); to method getTransformer()