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

  4. Configuring Endpoints

Configuring Endpoints

Endpoints are used to connect services. An endpoint is a specific channel on which a service can send messages and from which another service can receive messages. For example, a purchasing component may receive an order request over HTTP. Once the order has been processed by the component, a JMS message may be sent over a topic to notify an auditing system, and a response can be sent back over HTTP.

This page describes how to configure an endpoint. For details on the various attributes and elements you can configure on an endpoint, see Endpoint Configuration Reference.

Basic Configuration

In its most basic form, an endpoint consists of a transport and a transport-specific channel/destination/resource used to identify the channel and location where two services can exchange information. For example:

URI-style Endpoints 
<inbound-endpoint address="udp://localhost:65432"/>

<jetty:inbound-endpoint address="http://localhost:60211/mycomponent1" exchange-pattern="request-response" />

<outbound-endpoint address="smtp://user:secret@smtp.host"/>

<inbound-endpoint address="jms://test.queue"/>

Traditionally, endpoints in Mule ESB have been specified as a URI such as the examples above. This form is still supported, and indeed may prove to be more practical depending on your application. However, as of Mule 2.0, the recommended way to specify endpoints is via transport-specific namespaces, as shown in the following examples.

Transport-specific Endpoints 
<file:inbound-endpoint path="./.mule/in"
comparator="org.mule.transport.file.comparator.OlderFirstComparator" reverseOrder="true"/>

<ssl:endpoint name="clientEndpoint" host="localhost" port="60198"/>

<jetty:endpoint name="serverEndpoint" host="localhost" port="60203" path="services/Foo" />

<imaps:endpoint name="global1s" host="localhost" password="secret" port="123" user="bob"/>

<rmi:endpoint name="BadType" host="localhost" port="1099" object="MatchingUMO" method="reverseString"/>

<quartz:endpoint name="qEP6" repeatCount="10" repeatInterval="1000" jobName="job"/>

<jms:inbound-endpoint queue="test.queue"/>

Dynamic Endpoints

Starting in Mule 3, an outbound endpoint can also be dynamic. This means that the endpoint’s URI is the value of an expression, which is evaluated just before a message is sent to it. This allows the target of a message to be determined by its contents or the value of any message property. Dynamic endpoints can use either of the endpoint formats shown above.

Dynamic Endpoints 
<outbound-endpoint address="smtp://user:secret@#[header:OUTBOUND:host]"/>

<http:outbound-endpoint host="localhost" port="#[header:INBOUND:portNumber]" path="orderService"/>

<jms:outbound-endpoint host="localhost" queue="#[mule:registry.defaultJmsQueue]"/>

The only part of an endpoint URI that cannot be dynamic is the scheme. Don’t do this:

Illegal Dynamic Endpoint 
<outbound-endpoint address="#[header:INBOUND:endpointType]//localhost:8080/service"/>

Connector

In many cases, the connector associated with an endpoint can simply be assumed based on the transport and created implicitly. However, if more than one connector of the same transport exists, or if non-default settings are used for the connector, you must refer to the connector from the endpoint using the connector-ref attribute.

Specifying a connector 
<inbound-endpoint address="tcp://localhost:65432" connector-ref="tcpConnector1"/>
<tcp:inbound-endpoint host="localhost" port="65433" connector-ref="tcpConnector2"/>

Properties

Properties on endpoints can be used to customize behavior. Any properties set on the endpoint can be used to override default properties on the associated transport’s connector. For example, an SMTP outbound endpoint might set the fromAddress property to workflow1 to override a default connector value of sysadmin. Any standard properties for an endpoint will be available as attributes in the XML schema if transport-specific endpoints are used. It is also possible to specify a non-standard property. For example:

Setting properties 
<!-- Standard properties -->
<quartz:endpoint name="qEP6" repeatCount="10" repeatInterval="1000" jobName="job"/>

<!-- Non-standard properties -->
<quartz:endpoint name="qEP7" jobName="job2">
    <property key="actionOnTimeout" value="self-destruct"/>
    <property key="precision" value="2.5"/>
</quartz:endpoint>

Exchange Pattern

By default, endpoints are one-way; that is, they accept (or send) messages, but do not return (or receive) responses to those messages. To set an endpoint to wait for a response, you set exchange-pattern="request-response". This setting is not required by HTTP/S, SSL, TCP, and Servlet endpoints, which are request-response by default.

For more information on configuring messaging styles on an endpoint, see Service Messaging Styles.

Transaction

A transaction can begin or commit when an event is received or sent via an endpoint. The endpoint must be synchronous, and transaction support depends largely on the particular transport being used. For more information see Transaction Management.

Transaction example 
<jms:inbound-endpoint queue="in">
    <jms:transaction action="BEGIN_OR_JOIN"/>
</jms:inbound-endpoint>

Encoding

This is the encoding an endpoint used to convert message content. For inbound endpoints, it is used to convert the bytes received to characters. For outbound endpoints, it is used to convert characters about to be sent to bytes. If no encoding is set on the endpoint, the default encoding for the Mule configuration is used. This is turn defaults to UTF-8.

Encoding example 
<inbound-endpoint address="tcp://localhost:65432" encoding="iso-8859-1"/>

MimeType

This is the mime type associated with an endpoint’s messages. When set on an inbound endpoint, it indicates the type of message expected for incoming messages. Receiving a message with a different mime type will result in an exception. When set on an outbound endpoint, the result is to set that mime type on all outgoing messages.

MimeType example 
<inbound-endpoint address="tcp://localhost:65432" mimeType="text/xml"/>

Redelivery Policy

A redelivery policy can be defined on an inbound endpoint. It is similar to the maximum redelivery counts that can be set on JMS brokers, and solves a similar problem: if an exception causes the read of a message to be rolled back over and over, how to avoid an infinite loop? Here’s an example:

MimeType example 
<flow name ="syncFlow" processing-strategy="synchronous">
    <file:inbound-endpoint path="/tmp/file2ftp/ftp-home/dirk">
        <idempotent-redelivery-policy maxRedeliveryCount="3">
            <dead-letter-queue>
                <vm:outbound-endpoint path="error-queue" />
            </dead-letter-queue>
        </idempotent-redelivery-policy>
    </file:inbound-endpoint>

If something later in the flow throws an exception, the file won’t be consumed, and will be reprocessed. The idempotent-redelivery-policy ensures that it won’t be reprocessed more then 3 times; after that, it will be send to vm:error-queue, where it can be handled as an error case.

Message Processors

What is a message processor? It’s a very simple interface for anything which takes a Mule message and does something with it (transforms it, filters it, splits it, etc.). One of the big advantages to everything implementing this simple interface is that message processors can be chained together in any order, there can be any number of them, and they can easily be swapped around. This sort of thing was not at all possible prior to Mule 3.

In the case of endpoints, the following message processors are allowed:

  • Transformers

  • Filters

  • Security Filters

  • Aggregators

  • Splitters

  • Custom Message Processors

You can put any number of these message processors as child elements on an endpoint (inbound or outbound), and they will get applied in the order in which they are listed to any message passing through that endpoint.

In the case of a synchronous outbound endpoint, there is a response message involved, and so any number of message processors can also be put inside a response wrapper and will get applied to the response message in the order in which they are listed.

Note that any of these elements could be declared locally (i.e., in-line in the endpoint) or globally (and referenced via a ref="foo" attribute).

Transformers

Transformers can be configured on an endpoint encapsulating transformation logic in an endpoint that can then be reused as required.

Transformers are configured on endpoints using child message processors elements. When configured on an inbound endpoint they are used to transform the message received by the endpoint, and when configured on an outbound endpoint they are used to transform the message before it is sent.

Response transformers can be configured inside the nested <response> element. When configured on an inbound endpoint these transformer will be applied to the message just before it is sent back over the transport, and when configured on an outbound endpoint they are applied on the message received from the invocation of the outbound endpoint if there is one.

As will all message processors configured on endpoints, the order in which they are configured is the order in which they are executed.

<inbound-endpoint address="file://./test-data/in">
  <xml-to-object-transformer/>
  <expression-filter expression=""/>
  <transformer ref="ExceptionBeanToErrorMessage"/>
  <response>
    <custom-transformer class=""/>
  </response>
</inbound-endpoint>

In the above example you can see two request transformers configured, one of which will be executed before the expression filter and the other one after. The custom transformer configured in the <response> element will be applied to the response message.

Global Endpoints Although globally defined transformers can be referenced from endpoints using the \{\{<transformer ref=""/> element as seen in the above example endpoints also support a shortcut notification.

The transformer-refs and responseTransformer-refs attributes can be used to quickly and easily reference global endpoints.

<inbound-endpoint address="file://./test-data/in" transformer-refs="globalTransformer1 globalTransformer2" responseTransformer-refs="globalTransformer2"/>

Any transformers referenced in this way will be added to the end of the list of message processors configured a child elements and will therefore be executed last. If you need them to be executed before something else like a filter or need to use global endpoints in conjunction with locally defined endpoints in a specific order then you’ll need to use <transformer> elements instead.

Filter

An endpoint can contain a filter to selectively ignore certain messages. The filter can be transport-specific such as a JMS selector or file filter or can be a general-purpose filter such as JXPath. Filtering is not supported by all transports, and setting a filter on an endpoint using some transports will result in an UnsupportedOperationException. For more information, see Using Filters.

Filter example 
<jms:endpoint queue="in.queue">
    <jms:selector expression="JMSPriority > 5"/>
</jms:endpoint>

<vm:endpoint name="fruitBowlEndpoint" path="fruitBowlPublishQ">
    <message-property-filter pattern="foo=bar"/>
</vm:endpoint>

Other Message Processors

Although filters and transformer are the message processor most used within endpoints, you can just as easily configure other message processors. See more information about the available messages processor on in the Message Sources and Message Processors page.

Endpoint Usage

Endpoints can be used in the following places:

  • Inbound Routers

  • Outbound Routers

  • Services

  • Catch-all Strategies

  • Exception Strategies

Inbound Routers

See Inbound Routers.

Inbound router 
<service name="Receiver">
    <inbound>
        <vm:inbound-endpoint path="inbound.channel"/>
        <wire-tap-router>
            <vm:outbound-endpoint path="tapped.channel"/>
        </wire-tap-router>
    </inbound>
    <component class="com.acme.SomeService"/>
</service>

Outbound Routers

See Outbound Routers.

Outbound routers 
<service name="MessageChunker">
    <inbound>
        <jms:inbound-endpoint queue="big.messages"/>
    </inbound>
    <outbound>
        <message-chunking-router messageSize="10">
            <jms:outbound-endpoint queue="small.chunks"/>
        </message-chunking-router>
    </outbound>
</service>

<service name="LenderGatewayService">
    <inbound>
        <inbound-endpoint ref="LenderGateway" />
    </inbound>
    <outbound>
        <chaining-router>
            <outbound-endpoint ref="LenderService" />
            <outbound-endpoint ref="BankingGateway" transformer-refs="SetLendersAsRecipients ObjectToJMSMessage" />
        </chaining-router>
    </outbound>
</service>

Services

As a shortcut, endpoints can be configured directly on the service without a router in some cases.

Implicit router 
<service name="Echo">
    <inbound>
        <!-- Inbound router is implicit -->
        <stdio:inbound-endpoint system="IN"/>
    </inbound>
    <echo-component/>
    <outbound>
        <!-- Outbound router is explicit -->
        <pass-through-router>
            <stdio:outbound-endpoint system="OUT"/>
        </pass-through-router>
    </outbound>
</service>

Catch-all Strategies

A single "catch-all" endpoint can be configured for certain types of routers. See Catch-all Strategies.

Catch-all strategy 
<service name="dataService">
    <inbound>
        <inbound-endpoint ref="dataIn">
            <payload-type-filter expectedType="java.lang.String"/>
        </inbound-endpoint>
        <forwarding-catch-all-strategy>
            <jms:outbound-endpoint queue="error.queue"/>
        </forwarding-catch-all-strategy>
    </inbound>
    ...cut...
</service>

Exception Strategies

A single error endpoint can be configured on an exception strategy. See Error Handling.

Exception strategy 
<service name="dataService">
    <inbound>
        ...cut...
    </inbound>
    <component class="com.acme.DataProcessor"/>
    <outbound>
        ...cut...
    </outbound>
    <default-service-exception-strategy>
        <jms:outbound-endpoint queue="error.queue"/>
    </default-service-exception-strategy>
</service>

Global Endpoints

Global endpoints, while not required, are a recommended best practice for having a nicely organized configuration file. A global endpoint can be thought of as a template for shared endpoint configuration. Global endpoints can be used as they are defined globally, or they can be extended by adding more configuration attributes or elements.

To reference a global endpoint, use the usual <inbound-endpoint> and <outbound-endpoint> elements, and specify the global endpoint name using the ref attribute.

Global endpoint example 
<file:endpoint name="fileReader" reverseOrder="true" comparator="org.mule.transport.file.comparator.OlderFirstComparator"/>
...cut...

<model>
    <service name="Priority1">
        <file:inbound-endpoint ref="fileReader" path="/var/prio1"/>
        ...cut...
    </service>

    <service name="Priority2">
        <file:inbound-endpoint ref="fileReader" path="/var/prio2"/>
        ...cut...
    </service>
</model>

In the above example, the "fileReader" endpoint is used as a template for the inbound endpoints. The properties reverseOrder and comparator only need to be declared once, and the property path changes for each inbound endpoint.