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.

To use an executor bus the application must:

1. Implement an ExecutorBusProcessor that handles the processing
2. Expose it the executor via a ExecutorBusProcessorFactory configured for the bus
3. ... and acknowledge completed work via the provided Acknowledger as work is completed. 
4. Send the processor work in the form of messages that the processor will complete. 

Configuring an Executor Bus

The below example configuration demonstrates how one could configure an executor bus that will be used sends out e-mails:

Executor Bus Properties

An executor bus exposes the following configuration 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 smpt related properties that would be used for sending out e-mails. 

Threading

Note also that the <app> element configured the bus to use detachedSends. This is because 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 (sending e-mails) would be done on the application's commit thread. So 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 there own threading or thread pools to maintain ordered processing on a channel by channel basis. 

Qos

Providing an executor bus channel is declared as Guaranteed, an AepEngine will not complete the transaction from which the processing was scheduled until the bus's processor has acknowledged it. This means that if works was sent to the executor bus in response to a received message the received message won't be aknowledged 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 acknowleding 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 process factory as a means of looking up a processor if there are multiple executor buses configured for an application. 

Implementing an Executor Bus Processor

An executor bus needs an ExecutorBusProcessor to perform processing which is supplied to the bus when it is created by its executor bus processor factory. The ExecutorBusProcessor interface defines a single method, the process method which is defined as follows:

Tying into Executor Bus Lifecycle

An AepEngine creates message bus instances when the application assumes the primary role. Processors that need to open connections to external systems to perform their processing may implement LifecycleAwareExecutorBusProcessor to hook into the correspondings bus lifecycle. In this case the executor bus will call the processor's onExecutorBusOpen, onExecutorBusStart and onExecutorBusClose methods. 

Accessing Executor Bus Configuration Properties

If processor related configuration is present in the executor bus configuration (e.g. properties like smtp_host in the example configuration above), those properties can be retrieved from the provider config portion of the binding's descriptor. See the sample executor code below for an example: 

Acknowledger

Regardless of whether or not an executor bus channel is configured to be Guaranteed, the bus will pass a non null Acknowledger to the application and the application must call its acknowledge method when processing has been completed. The acknowler's can be called by any thread asynchronously, but its acknowledge method may only be called once as the Acknowledger implementation is pooled. 

Sample Executor Code

The below pseudo code illustrates how an executor bus processor can be implemented. 

Implementing an Executor Bus Processor Factory

Example: Creating an E-mail Alert Gateway

To tie the above concepts together this example shows how one could create a gateway that bridges alerts received from solace out through the email gateway we discussed above. Below we will:

• Configure 2 buses, an alert-bus using solace, and the email-gateway executor bus we've described above. 
• Create an Application that 
  • Creates the EmailSender gateway and registers it with the executor bus factory that we discussed above. 
  • Defines an EventHandler that listens to messages of type MyAppAlertMessage received from solace.
  • Copies the MyAppAlertMessage message and forwards it over the email-sender bus to sent out over e-mail. 

Because the e-mail gateway bus is acknowledging its work after sending each e-mail, this application will guarantee that e-mail alerts will be sent, and by virtue of clustering will be highly available.