In JBoss ESB, the structure of a service consists of a simple action pipeline that is responsible for processing each request in a sequential manner. There are no restrictions placed on the content or structure of the requests or on the functionality that can be exposed through a service.
The service pipeline is the real workhorse of JBoss ESB, responsible for the following:
- Controlling the lifecycle of each action
- Validation and delivery of the message through the action processors
- Generating appropriate responses once the request is complete.
A service can consist of any number of actions, each processing the output from the preceding action in the pipeline.
The pipeline treats each action as if it was an implementation of the org.jboss.soa.esb.actions.ActionPipelineProcessor interface, containing the lifecycle and processing methods supported by the pipeline. If the service action does not directly implement this interface then the pipeline will create an adapter which is responsible for invoking the methods using the overriding mechanism (see the Dynamic Methods section later in this chapter).
One instance of each action will be instantiated on initialization of the action pipeline, and created in the sequence defined by the configuration of the service pipeline. Each action must contain a public constructor with a single
ConfigTree parameter, used to pass in the configuration of the action, unless it is an annotated action when annotated fields and methods can be used to configure the action.
Action lifecycle methods are represented by the org.jboss.soa.esb.actions.ActionLifecycle interface, consisting of the following methods:
public void initialise() throws ActionLifecycleException ; public void destroy() throws ActionLifecycleException ;
These are invoked during the initialization and destruction phases of the action pipeline. Actions should restrict their initialization and cleanup tasks to within the lifecycle methods, they should not occur within the creation of the action or within the processing methods.
The service pipeline will initialize each action in the order defined within the service definition and, once complete, will be able to process any messages delivered to the service. The following sequence diagram highlights the successful initialization of a pipeline:
If an exception occurs during the initialization of an action then the pipeline will invoke the destroy method of each preceding action, in reverse order, before terminating the pipeline. The following sequence diagram highlights the processing of a failure durng the initialization phase:
The service pipeline will continue to process messages until such time as it is asked to stop. Once current processing is complete the pipeline will invoke the destroy method of each action, in reverse order, before terminating the pipeline. The following sequence diagram highlights the termination phase of the pipeline:
You have already seen our MyAction class in action. Override the initialise() and
destroy() methods, from AbstractActionLifecycle, with some printlns and see how these methods are invoked.
Action processing methods are represented by the org.jboss.soa.esb.actions.ActionPipelineProcessor interface, which extends the ActionLifecycle interface to add the following methods:
public Message process(final Message message)
throws ActionProcessingException ;
public void processException(final Message message,final Throwable th) ;
public void processSuccess(final Message message) ;The implementations of these methods must be thread-safe, as they may be invoked concurrently.
The service pipeline is responsible for obtaining the incoming message and controlling its progression through the actions in the pipeline. The process method of each action processor will be invoked, in the same order as the actions are defined within the service, using the response from the preceding action as the message input parameter. Each action processor can therefore choose whether to reuse the same message instance or create a new instance for subsequent processors.
If the message processing is successful then the service pipeline will invoke the processSuccess method of each action processor, in reverse order. The following sequence diagram highlights a successful invocation of a service pipeline:
If the message processing causes an exception to be thrown from any of the process method invocations then the service pipeline will invoke the processException method of each processor, in reverse order starting from the processor which generated the exception. The following sequence diagram highlights an exception being thrown by one of the action processors within the pipeline:
