Understanding Mule Configuration

A connector is a concrete instance of a Mule transport, whose properties describe how that transport is used. All Mule endpoints use transports which inherit the connector’s properties.

Here are some examples of connectors:

❶ The vm connector specifies that all of its endpoints use persistent queues. ❷ The file connector specifies that each of its endpoints will be polled once a second, and also the directory that files will be moved to once they are processed.

Note that properties may be specified either by attributes or by child elements. You can determine how to specify connector properties by checking the reference for that connector’s transport.

The relationship between an endpoint and its connector is actually quite flexible:

A Mule endpoint is an object that messages can be read from (inbound) or written to (outbound), and that specifies properties that define how that will be done. Endpoints can be specified two different ways:

A global endpoint specifies a set of properties, including its location. Inbound and outbound endpoints that reference the global endpoint inherit its properties. Example:

The vm endpoint in ❶ specifies its location and refers to the connector shown above. It uses the generic address attribute to specify its location. The file endpoint at ❷ specifies the directory it reads from (or writes to), and uses the default file connector. Because it is configured as a generic endpoint, it must specify its location via address.

Note that every endpoint uses a specific transport, but that this can be specified in two different ways:

The prefix style is preferred, particularly when the location is complex.

One of the most important attributes of an endpoint is its message exchange pattern (MEP, for short), that is, whether messages go only one way or if requests return responses. This can be specified at several levels:

A transformer is an object that transforms the current Mule message. The Mule core defines a basic set of transformers, and many of the modules and transports define more, for instance the JSON module defines transformers to convert an object to JSON and vice-versa, while the Email transport defines transformers that convert between byte arrays and MIME messages. Each type of transformer defines XML configuration to define its properties. Here are some examples of transformers:

The transformer at ❶ converts the current message to JSON, specifying special handling for the conversion of the org.mule.tck.testmodels.fruit.Orange class. The transformer at ❷ adds an invocation-scoped property to the current message.

Like endpoints, transformers can be configured as global elements and referred to where they are used, or configured at their point of use.

For more about Mule transformers, see Using Transformers.

A filter is an object that determines whether a message should be processed or not. As with transformers, the Mule core defines a basic set of transformers, and many of the modules and transports define more. Here are some examples of filters:

The filter at ❶ continues processing of the current message only if it matches the specified pattern. The filter at ❷ continues processing of the current message only if it is an XML document.

There are a few special filters that extend the power of the other filters. The first is message-filter:

As above, ❶ continues processing of the current message only if it matches the specified pattern. But now any messages that don’t match, rather than being dropped, are sent to a dead letter queue for further processing. ❷ continues processing of the current message only if it is an XML document, but throws an exception otherwise.

Other special filters are and-filter, or-filter, and not-filter, which allow you to combine filters into a logical expression:

This processes a message only if it’s either priority 1 or a priority 2 message from a country other than Canada.

Filters once again can be configured as global elements and referred to where they are used, or configured at their point of use. For more about Mule filters see Using Filters

For a current reference to using expressions in Mule, see Mule Expression Language MEL.

As we’ve seen, many Mule objects can be defined globally. The advantage of this is that they can be reused throughout the application, by referring to them where they’re needed. There’s a common pattern for this:

For each type of object, there is a generic element used to refer to it.

For example

In addition, there are places where the names of global objects are the values of an attribute, for instance:

Previously, we looked at declarations of global endpoints. Here we see endpoints in flows, where they are used to receive (inbound) and send (outbound) messages. Inbound endpoints appear only at the beginning of the flow, where they supply the message to be processed. Outbound endpoints can appear anywhere afterward. The path of a message through a flow depends upon the MEPs of its endpoints:

❶ This receives a message over an HTTP connection. The message payload is set to an array of the bytes received, while all HTTP headers become inbound message properties. Because this operation is request-response (the default for HTTP), at the end of the flow, the current message returns to the caller.

❸ This calls a JDBC query, using the current message as a parameter, and replaces the current message with the query’s result. Because this endpoint is request-response, the result of the query becomes the current message.

❶❹ The confirmation for a completed order, which was returned from the sub-flow, is e-mailed. Note that we use the email-address that had previously been saved in a message property. Because this endpoint is one-way (the only MEP for email transports), the current message does not change.

❶❽ Any orders that were not processed correctly are put on a JMS queue for manual examination. Because this endpoint is one-way (the default for JMS), the current message does not change.

Thus the message sent back to the caller will be the confirmation message, in case of success, or the same string sent to the JMS error queue in case of failure.

As described above, transformers change the current message. There are a few examples here. Note that they are defined where used. They could also have been defined globally and referred to where used.

❷ The message, which is a byte array, is converted to a string, allowing it to be the key in a database look-up.
❹ The order read from the database is converted to an XML document.
❶❶ The email address is stored in a message property. Note that, unlike most transformers, the message-properties-transformer does not affect the message’s payload, only its properties.
❶❼ The message that caused the exception is converted to a string. Note that since the same strategy is handling all exceptions, we don’t know exactly what sort of object the message is at this point. It might be a byte array, a string, or an XML document. Converting all of these to strings allows its receiver to know what to expect.

Message enrichment is done using the enricher element. Unlike message transformation, which alters the current message’s payload, enrichment adds additional properties to the message. This allows the flow to build up a collection of information for later processing. For more about enriching messages see Message Enricher.

❽ The enricher calls a connector to retrieve information that it stores as a message property. Because the connector is called within an enricher, its return value is processed by the enricher rather than becoming the message.

The logger element allows debugging information to be written from the flow. For more about the logger see Logger Component Reference

❻ Each order fetched from the database is output, but only if DEBUG mode is enabled. This means that the flow is silent, but debugging can easily be enabled when required.

Filters determine whether a message is processed or not.

❺ If the status of the document fetched is not "ready", its processing is skipped.

A router changes the flow of the message. Among other possibilities, it might choose among different message processors, split one message into many, join many messages into one. For more about routers, see Routing Message Processors.

❼ Split the document retrieved from the database into multiple orders, at the XML element order. The result is zero or more orders, each of which is processed by the rest of the flow. That is, for each HTTP message received, the flow is processed once up through the splitter. The rest of the flow might be processed zero, one, or more times, depending on how many orders the document contains.

A component is a message processor written in Java, groovy, or some other language. Mule determines which method to call on a component by finding the best match to the message’s type. To help tailor this search, Mule uses objects called Entry Point Resolvers, which are configured on the component. Here are some examples of that:

❶ Causes the two methods preProcessXMLOrder and preProcessTextOrder to become candidates. Mule chooses between them by doing reflection, using the type of the message.
❷ Calls the method whose name is in the message property methodToCall.
❸ Calls the generate method, even though it takes no arguments.

Entry point resolvers are for advanced use. Almost all of the time, Mule finds the right method to call without needing special guidance.

❶❷ This is a Java component, specified by its class name, which is called with the current message. In this case, it preprocesses the message. For more about entry point resolvers, see Entry Point Resolver Configuration Reference.

An Anypoint connector calls a cloud service.

❾ Calls authorize.net to authorize a credit card purchase, passing it information from the message. For more about connectors, see Anypoint Connectors.

A processor chain is a list of message processors, which will be executed in order. It allows you to use more than one processor where a configuration otherwise allows only one, exactly like putting a list of Java statements between curly braces.

❶❻ Performs two steps as part of the exception strategy. It first transforms and then mails the current message.

A sub-flow is a flow that can be called from another flow. It represents a reusable processing step. Calling it is much like calling a Java method – the sub-flow is passed the current message, and when it returns the calling flow resumes processing with the message that the sub-flow returns.

❶❸ Calls a flow to process an order that has already been pre-processed and returns a confirmation message.

An exception strategy is called whenever an exception occurs in its scope, much like an exception handler in Java. It can define what to do with any pending transactions and whether the exception is fatal for the flow, as well as logic for handling the exception.

❶❺ Writes the message that caused the exception to a JMS queue, where it can be examined. For more about exception strategies, see Error Handling.

For flexibility, all of the patterns allow endpoints to be specified in a variety of ways:

All configuration patterns can specify exception strategies, just as flows can.

The allows you to configure, in addition to the inbound and outbound endpoints

Examples:

❶ Copies messages from a JMS queue to a JMS topic, using a transaction. ❷ reads byte arrays from an inbound vm endpoint, transforms them to strings, and writes them to an outbound vm endpoint. The responses are strings, which are transformed to byte arrays, and then written to the outbound endpoint.

This allows you to configure, in addition to the inbound endpoint

Here are some examples:

❶ Is a simple service that echos requests. ❷ is a simple web service that uses a CXF component. Note how little configuration is required to create them.

This allows you to configure, in addition to the inbound and outbound endpoints

Example:

❶ Validates that the payload is of the correct type before calling the order service, using the filter at ❷.

This creates a proxy for a web service. It modifies the advertised WSDL to contain the proxy’s URL.

This allows you to configure, in addition to the inbound and outbound endpoints:

Example:

This creates a proxy for the weather forecasting service located on server1.

Threading profiles determine how Mule manages its thread pools. In most cases the default will perform well, but if you determine that, for instance, your endpoints are receiving so much traffic that they need additional threads to process all of it, you can adjust this, either for selected endpoints or, by changing the default, for all endpoints. The defaults that can be adjusted – and their corresponding elements – are:

Again, the default timeouts will usually perform well, but if you want to adjust them, you can do so either per use or globally. The timeouts that can be adjusted and their corresponding attributes are:

Mule uses JTA to manage XA transactions; thus, to use XA transactions, a JTA transaction manager is required, and must be specified in the configuration. Mule has explicit configuration for many of these, and, as usual, also allows you to specify a custom manager. The element used to specify a transaction manager is a direct child of mule.

The starred transaction managers allow you to configure a JNDI environment before performing the lookup. For more about transaction managers, see Transaction Management.

The Mule security manager can be configured with one or more encryption strategies that can then be used by encryption transformers, security filters, or secure transports such as SSL or HTTPS. These encryption strategies can greatly simplify configuration for secure messaging as they can be shared across components. This security manager is set with the global security-manager element, which is a direct child of mule.

For example, here is an example of a password-based encryption strategy (PBE) that provides password-based encryption using JCE. Users must specify a password and optionally a salt and iteration count as well. The default algorithm is PBEWithMD5AndDES, but users can specify any valid algorithm supported by JCE.

This strategy can then be referenced by other components in the system such as filters or transformers.

For more about Mule security, see Configuring Security.

Mule can generate notifications whenever a message is sent, received, or processed. For these notifications to actually be created and sent, objects must register to receive them. This is done via the global\{{notifications}} element, which is a direct child of mule. It allows you to specify an object to receive notifications as well as specify which notifications to send it. Note that an object will only receive notifications for which it implements the correct interface (these interfaces are defined in the org.mule.api.context.notification package.) Here is an example:

Assume that ComponentMessageNotificationLogger implements the ComponentMessageNotificationListener interface and EndpointMessageNotificationLogger implements EndpointMessageNotificationListener.
❶ and ❷ create the listener beans. ❸ appears to register both beans for both component and endpoint notifications. But since ComponentMessageNotificationLogger only implements the interface for component notification, those are all it will receive (and likewise for EndpointMessageNotificationLogger.

For more about notifications, see Notifications Configuration Reference.

To create a custom agent, simply declare it using the global custom-agent element, which is a direct child of mule. The agent is a Spring bean, so as usual it requires a class name and a set of Spring properties to configure it. In addition it requires a name, which Mule uses to identify it in logging output. Here’s an example:

This creates an agent that issues a heartbeat signal every 30 seconds. Since Mule will start it and stop it, the heartbeat is present precisely when the Mule server is running.

Mule implements various management agents in the management namespace.