Executor Binding

Configuration reference for the Executor message bus binding.

Overview

The Executor Bus Binding is a special bus binding that allows applications to provide send work (via a message) to be processed on a separate thread. The executor binding can be used to perform processor-intensive work in a thread other than an application's main dispatch thread, or can be used as a means to implement outbound gateways in which the executing thread 'pushes' the sent message to an external system.

Work done by the processor of an executor bus is acknowledged and therefore Guaranteed across failures.

For conceptual information about the Executor binding, see Executor Binding.

The Executor Bus is still in incubation and is classified as an experimental feature. The APIs below may change as new features are added to this binding.

Bus Descriptor Format

The Executor binding is configured using decomposed DDL format only.

Decomposed DDL Format

<buses>
  <bus name="email-sender">
    <provider>executor</provider>
    <address>audit-logger</address>
    <properties>
      <processor_factory_classname>com.example.EmailGatewayProcessorFactory</processor_factory_classname>
      <from_address>[e-mail]</from_address>
      <smtp_host>mail.example.com</smtp_host>
      <smtp_port>25</smtp_port>
      <smtp_password>admin</smtp_password>
      <!-- ... additional custom properties ... -->
    </properties>
    <channels>
      <channel name="email-alerts">
        <qos>Guaranteed</qos>
      </channel>
    </channels>
  </bus>
</buses>

<apps>
  <app name="email-gateway-app" mainClass="com.example.EmailGateway">
    <messaging>
      <buses>
        <bus name="email-sender">
          <detachedSend enabled="true">
            <queueDrainerCpuAffinityMask>${EMAIL_SENDER_CPU_AFFMASK::0}</queueDrainerCpuAffinityMask>
          </detachedSend>
          <channels>
            <channel name="email-alerts" join="false"/>
          </channels>
        </bus>
      </buses>
    </messaging>
  </app>
</apps>

Executor Bus Properties

An executor bus exposes the following configuration properties:

Property	Default	Description
processor_factory_classname	-	Specifies a factory classname that will be used by the bus to create its processor. The processor factory class must be a subclass of AbstractExecutorBusProcessorFactory and expose a zero argument constructor.

**This property is required.**

|

Custom Properties

An application can configure additional properties for the bus that can be used by the bus's processor. In the above example, the bus also defines SMTP-related properties that would be used for sending out e-mails. These custom properties are accessible from the processor via the binding descriptor.

Threading

The executor bus does not itself create any additional threads; processing of messages is done directly on the thread calling send.

In the case of a Talon application using detached sends is important because otherwise the bus processing would be done on the application's commit thread. Unless the processor implementation has its own thread or thread pool for performing work, it is usually desirable to configure executor buses for detached send.

Channels

The executor bus will set the channel name on messages it dispatches to the processor. It is good practice for processors that implement their own threading or thread pools to maintain ordered processing on a channel by channel basis.

Attempting to configure an executor bus channel for join will result in a runtime error - an executor bus only supports outbound semantics.

QoS

Provided an executor bus channel is declared as Guaranteed, an AEP Engine will not complete the transaction from which the processing was scheduled until the bus's processor has acknowledged it. This means that if work was sent to the executor bus in response to a received message, the received message won't be acknowledged until the work is done.

If the executor bus channel is defined as BestEffort, the engine will not wait for acknowledgement of work completion before acknowledging received events.

Address and Port

An executor bus must be configured with an address, but a port is optional. The address may be used by a bus's processor factory as a means of looking up a processor if there are multiple executor buses configured for an application.

See Also

• Executor Binding - Conceptual overview

• Configuring Bus Connections - General bus configuration

• ExecutorBusProcessor - Processor interface

• AbstractExecutorBusProcessorFactory - Factory base class