Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.8)
  3. Reference
  4. General Configuration Reference

  5. Endpoint Configuration Reference

Endpoint Configuration Reference

Mule runtime engine version 3.8 reached its End of Life on November 16, 2021. For more information, contact your Customer Success Manager to determine how to migrate to the latest Mule version.

This page discusses the configuration of the flow-level inbound and outbound endpoints, which are the flow-level elements of endpoint-based Anypoint Connectors. Note that none of the information on this page applies for operation-based connectors. See Anypoint Connectors for more information about connectors in general.

Endpoints are used to connect flows. An endpoint is a specific channel on which a flow can send messages and from which another flow or external 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.

Basic Configuration

In its most basic form, an endpoint acts as a flow-level inbound or outbound implementation of a transport and its underlying data source or message channel. 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 are specified as a URI such as the examples above. This form is still supported, and may prove to be more practical depending on your application. However, 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

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@#[message.outboundProperties['host']]"/>

<jms:outbound-endpoint host="localhost" queue="#[app.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="#[message.inboundProperties['endpointType']]//localhost:8080/service"/>

Global Connection Configuration

In many cases, the global connection configuration associated with an endpoint can simply be assumed based on the transport and created implicitly. However, if more than one global connector configuration of the same transport exists, or if non-default settings are used, you must refer to the connector configuration 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 are 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>

Transactions

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 results 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 is reprocessed. The idempotent-redelivery-policy ensures that it won’t be reprocessed more then 3 times; after that, it’s sent to vm:error-queue, where it can be handled as an error case.

The redelivery policy uses an ObjectStore to keep track of a counter for the amount of attempts that have been done. Mule uses an internal ObjectStore by default, but you can set it up so that you use a custom one if you prefer. To change this ObjectStore, add an object-store-ref property:

MimeType Example
<idempotent-redelivery-policy maxRedeliveryCount="3" object-store-ref="src/main/app/myObjStore">
  <dead-letter-queue>
    <vm:outbound-endpoint path="error-queue" />
  </dead-letter-queue>
</idempotent-redelivery-policy>

Embedding Message Processors Inside an Endpoint

The following message processors can be nested inside an endpoint:

  • 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 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 get applied to the response message in the order in which they are listed.

Note that any of these elements could be declared locally (that is, 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 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 transformers are 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 with 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 executes before the expression filter and the other one after. The custom transformer configured in the <response> element is applied to the response message.

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 is added to the end of the list of message processors configured a child elements and therefore be executes last. If you need them to execute before something else like a filter or need to use global endpoints in conjunction with locally defined endpoints in a specific order, then use <transformer> elements instead.

Filters

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 results 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>

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...

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

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

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.

Custom Message Sources

You can replace any inbound endpoint in a flow with a custom message source. This allows you to use any class as a message source to the flow, including connectors. You configure the custom message source using the <custom-source> element. In the element you identify the class for the custom source. You can further configure the custom message source using Spring bean properties.

The following code example configures a custom message source for a flow:

<flow name="useMyCustomSource">
   <custom-source class="org.my.customClass">
      <spring:property name="threads" value="500"/>
   </custom-source>
   <vm:outbound-endpoint path="output" exchange-pattern="one-way"/>
</flow>

Generic Endpoint Reference

The following reference tables list the attributes that can be configured for the generic endpoint in Mule.

Inbound Endpoint

An inbound endpoint receives messages via the associated transport. As with global endpoints, each transport implements its own inbound endpoint element.

Attributes of inbound-endpoint

Name Description

name

Identifies the endpoint in the registry. There is no need to set the 'name' attribute on inbound or outbound endpoints, only on global endpoints.

Type: name (no spaces)
Required: no
Default: none

ref

A reference to a global endpoint, which is used as a template to construct this endpoint. A template fixes the address (protocol, path, host, etc.), and may specify initial values for various properties, but further properties can be defined locally (as long as they do not change the address in any way).

Type: string
Required: no
Default: none

address

The generic address for this endpoint. If this attribute is used, the protocol must be specified as part of the URI. Alternatively, most transports provide their own attributes for specifying the address (path, host, etc.). Note that the address attribute cannot be combined with 'ref' or with the transport-provided alternative attributes.

Type: string
Required: no
Default: none

responseTimeout

The timeout for a response if making a synchronous endpoint call.

Type: integer
Required: no
Default: none

encoding

String encoding used for messages.

Type: string
Required: no
Default: none

connector-ref

The name of the connector associated with this endpoint. This must be specified if more than one connector is defined for this transport.

Type: string
Required: no
Default: none

transformer-refs

A list of the transformers that is applied (in order) to the message before it is delivered to the component.

Type: list of names
Required: no
Default: none

responseTransformer-refs

A list of the transformers that are applied (in order) to the synchronous response before it is returned via the transport.

Type: list of names
Required: no
Default: none

disableTransportTransformer

Don’t use the default inbound/outbound/response transformer which corresponds to this endpoint’s transport, if any.

Type: boolean
Required: no
Default: none

mimeType

The MIME type, for example, text/plain or application/json.

Type: string
Required: no
Default: none

exchange-pattern

Exchange pattern.

Type: enumeration
Required: no
Default: none

Child Elements of inbound-endpoint

Name Cardinality Description

abstract-reconnection-strategy

0..1

A placeholder for a reconnection strategy element. Reconnection strategies define how Mule should attempt to handle a connection failure.

abstract-multi-transaction

0..1

A placeholder for multi-transaction elements. Multi-transactions allow a series of operations to be grouped together spanning different transports, e.g. JMS and JDBC, but without the overhead of XA. The trade-off is that XA reliability guarantees aren’t available, and services must be ready to handle duplicates. This is very similar to a 1.5 PC concept. EE-only feature.

response

0..1

abstract-redelivery-policy

0..1

A placeholder for a redelivery policy. Redelivery policies determine what action to take when the same message is redelivered repeatedly.

abstract-transaction

0..1

A placeholder for transaction elements. Transactions allow a series of operations to be grouped together.

abstract-transformer

0..1

A placeholder for transformer elements. Transformers convert message payloads.

abstract-filter

0..1

A placeholder for filter elements, which control which messages are handled.

abstract-security-filter

0..1

A placeholder for security filter elements, which control access to the system.

abstract-intercepting-message-processor

0..1

A placeholder for intercepting router elements.

abstract-observer-message-processor

0..1

A placeholder for message processors that observe the message but do not mutate it used for example for logging.

processor

0..1

A reference to a message processor defined elsewhere.

custom-processor

0..1

abstract-mixed-content-message-processor

0..1

A placeholder for message processor elements.

property

0..*

Sets a Mule property. This is a name/value pair that can be set on components, services, etc., and which provide a generic way of configuring the system. Typically, you shouldn’t need to use a generic property like this, since almost all functionality is exposed via dedicated elements. However, it can be useful in configuring obscure or overlooked options and in configuring transports from the generic endpoint elements.

properties

0..1

A map of Mule properties.

Outbound Endpoint

An outbound endpoint sends messages via the associated transport. As with global endpoints, each transport implements its own outbound endpoint element.

Attributes of outbound-endpoint

Name Description

name

Identifies the endpoint in the registry. There is no need to set the 'name' attribute on inbound or outbound endpoints, only on global endpoints.

Type: name (no spaces)
Required: no
Default: none

ref

A reference to a global endpoint, which is used as a template to construct this endpoint. A template fixes the address (protocol, path, host, etc.), and may specify initial values for various properties, but further properties can be defined locally (as long as they do not change the address in any way).

Type: string
Required: no
Default: none

address

The generic address for this endpoint. If this attribute is used, the protocol must be specified as part of the URI. Alternatively, most transports provide their own attributes for specifying the address (path, host, etc.). Note that the address attribute cannot be combined with 'ref' or with the transport-provided alternative attributes.

Type: string
Required: no
Default: none

responseTimeout

The timeout for a response if making a synchronous endpoint call.

Type: integer
Required: no
Default: none

encoding

String encoding used for messages.

Type: string
Required: no
Default: none

connector-ref

The name of the connector associated with this endpoint. This must be specified if more than one connector is defined for this transport.

Type: string
Required: no
Default: none

transformer-refs

A list of the transformers to apply (in order) to the message before it is delivered to the component.

Type: list of names
Required: no
Default: none

responseTransformer-refs

A list of the transformers to apply (in order) to the synchronous response before it is returned via the transport.

Type: list of names
Required: no
Default: none

disableTransportTransformer

Don’t use the default inbound/outbound/response transformer which corresponds to this endpoint’s transport, if any.

Type: boolean
Required: no
Default: none

mimeType

The MIME type, for example, text/plain or application/json.

Type: string
Required: no
Default: none

exchange-pattern

Exchange pattern.

Type: enumeration
Required: no
Default: none

Child Elements of outbound-endpoint

Name Cardinality Description

abstract-reconnection-strategy

0..1

A placeholder for a reconnection strategy element. Reconnection strategies define how Mule should attempt to handle a connection failure.

abstract-multi-transaction

0..1

A placeholder for multi-transaction elements. Multi-transactions allow a series of operations to be grouped together spanning different transports, for example, JMS and JDBC, but without the overhead of XA. The trade-off is that XA reliability guarantees aren’t available, and services must be ready to handle duplicates. This is very similar to a 1.5 PC concept. EE-only feature.

response

0..1

abstract-redelivery-policy

0..1

A placeholder for a redelivery policy. Redelivery policies determine what action to take when the same message is redelivered repeatedly.

abstract-transaction

0..1

A placeholder for transaction elements. Transactions allow a series of operations to be grouped together.

abstract-transformer

0..1

A placeholder for transformer elements. Transformers convert message payloads.

abstract-filter

0..1

A placeholder for filter elements, which control which messages are handled.

abstract-security-filter

0..1

A placeholder for security filter elements, which control access to the system.

abstract-intercepting-message-processor

0..1

A placeholder for intercepting router elements.

abstract-observer-message-processor

0..1

A placeholder for message processors that observe the message but do not mutate it used for example for logging.

processor

0..1

A reference to a message processor defined elsewhere.

custom-processor

0..1

abstract-mixed-content-message-processor

0..1

A placeholder for message processor elements.

property

0..*

Sets a Mule property. This is a name/value pair that can be set on components, services, etc., and which provide a generic way of configuring the system. Typically, you shouldn’t need to use a generic property like this, since almost all functionality is exposed via dedicated elements. However, it can be useful in configuring obscure or overlooked options and in configuring transports from the generic endpoint elements.

properties

0..1

A map of Mule properties.

Endpoint

A global endpoint, which acts as a template that can be used to construct an inbound or outbound endpoint elsewhere in the configuration by referencing the global endpoint name. Each transport implements its own endpoint element, with a more friendly syntax, but this generic element can be used with any transport by supplying the correct address URI. For example, "vm://foo" describes a VM transport endpoint.

Attributes of Endpoint

Name Description

name

Identifies the endpoint so that other elements can reference it. This name can also be referenced in the MuleClient.

Type: name (no spaces)
Required: yes
Default: none

ref

A reference to a global endpoint, which is used as a template to construct this endpoint. A template fixes the address (protocol, path, host, etc.), and may specify initial values for various properties, but further properties can be defined locally (as long as they do not change the address in any way).

Type: string
Required: no
Default: none

address

The generic address for this endpoint. If this attribute is used, the protocol must be specified as part of the URI. Alternatively, most transports provide their own attributes for specifying the address (path, host, etc.). Note that the address attribute cannot be combined with 'ref' or with the transport-provided alternative attributes.

Type: string
Required: no
Default: none

responseTimeout

The timeout for a response if making a synchronous endpoint call.

Type: integer
Required: no
Default: none

encoding

String encoding used for messages.

Type: string
Required: no
Default: none

connector-ref

The name of the connector associated with this endpoint. This must be specified if more than one connector is defined for this transport.

Type: string
Required: no
Default: none

transformer-refs

A list of the transformers to apply (in order) to the message before it is delivered to the component.

Type: list of names
Required: no
Default: none

responseTransformer-refs

A list of the transformers to apply (in order) to the synchronous response before it is returned via the transport.

Type: list of names
Required: no
Default: none

disableTransportTransformer

Don’t use the default inbound/outbound/response transformer which corresponds to this endpoint’s transport, if any.

Type: boolean
Required: no
Default: none

mimeType

The MIME type, for example, text/plain or application/json.

Type: string
Required: no
Default: none

exchange-pattern

+ Type: enumeration
Required: no
Default: none

Child Elements of Endpoint

Name Cardinality Description

abstract-reconnection-strategy

0..1

A placeholder for a reconnection strategy element. Reconnection strategies define how Mule should attempt to handle a connection failure.

abstract-multi-transaction

0..1

A placeholder for multi-transaction elements. Multi-transactions allow a series of operations to be grouped together spanning different transports, for example, JMS and JDBC, but without the overhead of XA. The trade-off is that XA reliability guarantees aren’t available, and services must be ready to handle duplicates. This is very similar to a 1.5 PC concept. EE-only feature.

response

0..1

abstract-redelivery-policy

0..1

A placeholder for a redelivery policy. Redelivery policies determine what action to take when the same message is redelivered repeatedly.

abstract-transaction

0..1

A placeholder for transaction elements. Transactions allow a series of operations to be grouped together.

abstract-transformer

0..1

A placeholder for transformer elements. Transformers convert message payloads.

abstract-filter

0..1

A placeholder for filter elements, which control which messages are handled.

abstract-security-filter

0..1

A placeholder for security filter elements, which control access to the system.

abstract-intercepting-message-processor

0..1

A placeholder for intercepting router elements.

abstract-observer-message-processor

0..1

A placeholder for message processors that observe the message but do not mutate it used for example for logging.

processor

0..1

A reference to a message processor defined elsewhere.

custom-processor

0..1

abstract-mixed-content-message-processor

0..1

A placeholder for message processor elements.

property

0..*

Sets a Mule property. This is a name/value pair that can be set on components, services, etc., and which provide a generic way of configuring the system. Typically, you shouldn’t need to use a generic property like this, since almost all functionality is exposed via dedicated elements. However, it can be useful in configuring obscure or overlooked options and in configuring transports from the generic endpoint elements.

properties

0..1

A map of Mule properties.