Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.2)
  3. Essentials of Using Mule ESB 3

  4. Message Property Scopes

Message Property Scopes

Background

Mule has the following scopes:

  • Inbound - properties/headers coming from the client’s request

  • Invocation - used mostly internally by Mule for the duration of this service’s call, not typically utilized nor meant for end-user

  • Outbound - values deemed to be sent out from this service. They become either request properties for the next service, or response properties in case of a synchronous invocation

  • Session - values which are passed from invocation to invocation (note that session scope handling has been much improved in Mule 3.x)

To better understand scopes think of e.g. left-to-right flow of the message as it passes through the inbound, hits the component and goes to the outbound. Mule properties may move between scopes, either implicitly ('magic' set of correlation properties handled internally by Mule), or explicitly, when mandated and configured by a user (using message-properties-transformer).

Mule 2.x has always had property scopes, although they were mostly used internally and not enforced in the user-facing code. E.g. a call in 2.x like:

message.getProperty("Content-Type")

resulted in the property lookup in every scope. Another side-effect was that property set ended up having more values than wanted, sometimes interfering with the flow (requiring a user to remove those from the message explicitly).

Mule 3.x introduced a much more stringent concept, which resulted in the changes outlined below.

API

  1. message.getProperty() has been deprecated in favor of scope-specific variants e.g. message.getInboundProperty(). See MuleMessage javadoc for more details. The deprecated call now looks only in the outbound scope, as that was the most common use case for it.

  2. message.getPropertyNames() has been deprecated as returned a flattened set of all scope properties. Replaced with scope-specific methods, e.g. message.getInboundPropertyNames()

  3. message.setProperty() has been deprecated in favor of scope-specific variants e.g. message.getOutboundProperty(). See MuleMessage javadoc for more details. The deprecated call now sets the properties only in the outbound scope, as that was the most common use case for it.

  4. message.get/setSessionProperty() convenience methods have been introduced for working with the session-scoped properties.

Configuration Changes

  1. message-properties-transformer puts much more stress on the scope attribute now as a result of these changes. By default, an outbound scope is used, customize via the scope attribute on the transformer

  2. message-property-filter now supports an optional scope attribute

  3. Expression syntax has been enhanced to support scopes. The scope part is optional, and is case-insensitive. Default scope is outbound. General syntax is:

<evaluator>:<scope>:<expression>

For example:

header:INBOUND:foo

Internal Behavior

  1. Session handler serializes session contents and saves them in the outbound scope. The receiving end looks for and deserializes the session from the inbound scope.

  2. Inbound properties are no longer propagated automatically. By default, none of the inbound user properties are copied to the outbound scope. A user may explicitly propagate a property when needed. Note how in this example the default outbound scope is used as a target one, this can be customized via the scope attribute of the transformer:

<outbound>    <pass-through-router>        <vm:outbound-endpoint path="middle" exchange-pattern="request-response">            <message-properties-transformer scope="outbound">                <!-- Propagate 'myFooProperty' from the inbound to outbound -->                <add-message-property key="myFooProperty" value="#[header:INBOUND:myFooProperty]"/>            </message-properties-transformer>        </vm:outbound-endpoint>    </pass-through-router></outbound>

  1. VM-to-VM calls behave as expected of other transports, namely outbound properties end up in the inbound scope for the receiving VM endpoint.