To create a Message Channel instance, use the 'channel' element:

<channel id="exampleChannel"/>

You can also specify the channel's capacity:

<channel id="exampleChannel" capacity="100"/>

The default channel type is Point to Point. To create a Publish Subscribe channel, provide a value of true for the 'publish-subscribe' attribute of the channel element:

<channel id="exampleChannel" publish-subscribe="true"/>

When the MessageBus detects and registers channels, it will establish a dispatcher for each channel. The default dispatcher settings were previously displayed in Table 2.2, “Properties of the DispatcherPolicy”. To customize these settings for a particular channel, add the 'dispatcher-policy' sub-element and provide one or more of the attributes shown below:

<channel id="exampleChannel" publish-subscribe="true">
    <dispatcher-policy max-messages-per-task="25"
                       receive-timeout="10"
                       rejection-limit="3"
                       retry-interval="500"
                       should-fail-on-rejection-limit="false"/>
</channel>

To create a Datatype Channel that only accepts messages containing a certain payload type, provide the fully-qualified class name in the channel element's datatype attribute:

<channel id="numberChannel" datatype="java.lang.Number"/>

Note that the type check passes for any type that is assignable to the channel's datatype. In other words, the "numberChannel" above would accept messages whose payload is java.lang.Integer or java.lang.Double. Multiple types can be provided as a comma-delimited list:

<channel id="stringOrNumberChannel" datatype="java.lang.String,java.lang.Number"/>

Message channels may also have interceptors as described in Section 2.3, “ChannelInterceptor”. One or more <interceptor> elements can be added as sub-elements of <channel>. Provide the "ref" attribute to reference any Spring-managed object that implements the ChannelInterceptor interface:

<channel id="exampleChannel">
    <interceptor ref="trafficMonitoringInterceptor"/>
</channel>

In general, it is a good idea to define the interceptor implementations in a separate location since they usually provide common behavior that can be reused across multiple channels.

To create a Message Endpoint instance, use the 'endpoint' element with the 'input-channel' and 'handler-ref' attributes:

<endpoint input-channel="exampleChannel" handler-ref="exampleHandler"/>

The configuration above assumes that "exampleHandler" is an actual implementation of the MessageHandler interface as described in Section 2.4, “MessageHandler”. To delegate to an arbitrary method of any object, simply add the "handler-method" attribute.

<endpoint input-channel="exampleChannel" handler-ref="somePojo" handler-method="someMethod"/>

In either case (MessageHandler or arbitrary object/method), when the handling method returns a non-null value, the endpoint will attempt to send the reply message to an appropriate reply channel. To determine the reply channel, it will first check for a value in the message header's 'returnAddress' property. If that value is available, it will then check its type. If it is a MessageChannel, the reply message will be sent to that channel. If it is a String, then the endpoint will attempt to resolve the channel by performing a lookup in the ChannelRegistry. If the message header does not contain a 'returnAddress' property at all, then it will fallback to its own 'defaultOutputChannelName' property. If neither is available, then a MessageHandlingException will be thrown. To configure the default output channel when using the XML namespace, provide the 'default-output-channel' attribute:

<endpoint input-channel="exampleChannel"
          handler-ref="somePojo"
          handler-method="someMethod"
          default-output-channel="replyChannel"/>

Endpoint's also support MessageSelectors as described in Section 2.7, “MessageSelector”. To configure selectors with namespace support, simply add one or more <selector> sub-elements to the endpoint definition:

<endpoint id="endpoint" input-channel="channel" handler-ref="handler">
    <selector ref="exampleSelector"/>
</endpoint>

When the MessageBus registers the endpoint, it will activate the subscription by assigning the endpoint to the input channel's dispatcher. The dispatcher is capable of handling multiple endpoint subscriptions for its channel and delegates to a scheduler for managing the tasks that pull messages from the channel and push them to the endpoints. To configure the polling period for an individual endpoint's schedule, provide a 'schedule' sub-element with the 'period' in milliseconds:

<endpoint input-channel="exampleChannel" handler-ref="exampleHandler"/>
    <schedule period="3000"/>
</endpoint>

Note

Individual endpoint schedules only apply for "Point-to-Point" channels, since in that case only a single subscriber needs to receive the message. On the other hand, when a Spring Integration channel is configured as a "Publish-Subscribe" channel, then the dispatcher will drive all endpoint notifications according to its own default schedule, and any 'schedule' element configured for those endpoints will be ignored.

One of the most important configuration options for endpoints is the concurrency policy. Each endpoint is capable of managing a thread pool for its handler, and the values you provide for that pool's core and max size can make a substantial difference in how the handler performs under load. These settings are available per-endpoint since the performance characteristics of an endpoint's handler is one of the major factors to consider (the other major factor being the expected volume on the channel to which the endpoint subscribes). To enable concurrency for an endpoint that is configured with the XML namespace support, provide the 'concurrency' sub-element and one or more of the properties shown below:

<endpoint input-channel="exampleChannel" handler-ref="exampleHandler"/>
    <concurrency core="5" max="25" queue-capacity="20" keep-alive="120"/>
</endpoint>

Recall the default concurrency policy values as listed in Table 2.5, “Properties of the ConcurrencyPolicy”.

Tip

The default queue capacity of 0 triggers the creation of a SynchronousQueue. In many cases, this is preferable since the direct handoff eliminates the chance of a message handling task being "stuck" in the queue (thread pool executors will favor adding to the queue rather than increasing the pool size). Specifically, whenever a dispatcher for a Point-to-Point channel has more than one subscribed endpoint, a task that is rejected due to an exhausted thread pool can be handled immediately by another endpoint whose pool has one or more threads available. On the other hand, when a particular channel/endpoint may be expecting bursts of activity, setting a queue capacity value might be the best way to accommodate the volume.

As described in Section 2.5, “MessageBus”, the MessageBus plays a central role. Nevertheless, its configuration is quite simple since it is primarily concerned with managing internal details based on the configuration of channels and endpoints. The bus is aware of its host application context, and therefore is also capable of auto-detecting the channels and endpoints. Typically, the MessageBus can be configured with a single empty element:

<message-bus/>

The Message Bus provides default error handling for its components in the form of a configurable error channel, and the 'message-bus' element accepts a reference with its 'error-channel' attribute:

<message-bus error-channel="errorChannel"/>

<channel id="errorChannel" publish-subscribe="true" capacity="500"/>

When exceptions occur in an endpoint's execution of its MessageHandler callback, those exceptions will be wrapped in ErrorMessages and sent to the Message Bus' 'errorChannel' by default. To enable global error handling, simply register a handler on that channel. For example, you can configure Spring Integration's PayloadTypeRouter as the handler of an endpoint that is subscribed to the 'errorChannel'. That router can then spread the error messages across multiple channels based on Exception type.

The 'message-bus' element accepts two more optional attributes. First is the size of the dispatcher thread pool. The dispatcher threads are responsible for polling channels and then passing the messages to handlers. When the endpoints are concurrency-enabled as described in the previous section, the invocation of the handling methods will happen within the handler thread pool and not the dispatcher pool. Finally, the Message Bus is capable of automatically creating channel instances (with default settings) if an endpoint registers a subscription by providing the name of a channel that the bus does not recognize.

<message-bus dispatcher-pool-size="25" auto-create-channels="true"/>

The most convenient way to configure Channel Adapters is by using the namespace support. The following examples demonstrate the namespace-based configuration of source and target adapters (Spring Integration 1.0 M1 includes namespace support for JMS and Files):

<jms-source connection-factory="connectionFactory" destination="inputQueue" channel="inputChannel1"/

<jms-target connection-factory="connectionFactory" destination="outputQueue" channel="outputChannel1"/>

<file-source directory="/tmp/input" channel="inputChannel2" poll-period="10000"/>

<file-target directory="/tmp/output" channel="outputChannel2"/>

The next section will describe Spring Integration's support for annotation-driven configuration. To enable those features, add this single element to the XML-based configuration:

<annotation-driven/>