SOAP processing model controls the execution of the processing. The model defines different phases the execution would walk through, and the user can extend the Processing Model at specific places.Extensibility of the SOAP processing model is provided through handlers.
The architecture identified two basic actions a SOAP processor should perform, sending and receiving SOAP messages. The architecture provides two pipes (or flows) to perform these two basic actions. The Axis Engine or the driver of Axis2 defines two methods, send() and receive(), to implement these two pipes. The two pipes are named In Pipe and Out Pipe, and complex Message Exchange Patterns (MEPs) are constructed by combining these two pipes.
Extensibility of the SOAP processing model is provided through handlers. When a SOAP message is being processed, the handlers that are registered will be executed. The handlers can be registered in global, service, or operation scope and the final handler chain is calculated combining the handlers from all the scopes.
The handlers act as interceptors and they process parts of the SOAP message and provide add-on services. Usually handlers work on the SOAP headers, yet they may access or change the SOAP body as well.
When a SOAP message is being sent through the Client API, an Out Pipe activates. The Out Pipe will invoke the handlers and end with a Transport Sender that sends the SOAP message to the target endpoint. The SOAP message is received by a Transport Receiver at the target endpoint, which reads the SOAP message and starts the In Pipe. The In Pipe consists of handlers and ends with the Message Receiver, which consumes the SOAP message.
The processing explained above happens for each and every SOAP message that is exchanged. After processing one message, Axis2 may decide to create other SOAP messages, in which case more complex message patterns emerge. However, Axis2 always views the SOAP message in terms of processing a single message. The combination of the messages are layered on top of that basic framework.
The two pipes do not differentiate between the Server and the Client. The SOAP Processing Model handles the complexity and provides two abstract pipes to the user. The different areas or the stages of the pipes are called ‘phases’ within Axis2. A Handler always runs inside a specific phase, and the phase provides a mechanism to specify the ordering of handlers. Both Pipes have built-in phases, and both define the areas for ‘User Phases’ which can be defined by the user.
Axis2 Default Processing Model
Axis2 has some inbuilt handlers that run in inbuilt phases and they create the default configuration for Axis2. We will be looking more in to how to extend the default processing Model in the next section.
There are three special handlers defined in Axis2.
- Dispatchers – Finds the service and the operation the SOAP message is directed to. Dispatchers always run on the In-Pipe and inside the Dispatch phase. The in-built dispatchers dispatch to a particular operation depending on various conditions like WS-Addressing information, URI information, SOAP action information, etc. ( See more information on Dispatching)
- Message Receiver – Consumes the SOAP message and hands it over to the application. The message receiver is the last handler of the in-pipe
- Transport Sender – Sends the SOAP message to the SOAP endpoint the message is destined to. Always runs as the last handler in the out-pipe
Processing an Incoming SOAP Message
An incoming SOAP message is always received by a Transport Receiver waiting for the SOAP messages. Once the SOAP message arrives, the transport Headers are parsed and a Message Context is created from the incoming SOAP message. This message context encapsulates all the information, including the SOAP message itself, transport headers, etc., inside it. Then the In Pipe is executed with the Message Context. Let us see what happens at each phase of the execution. This process can happen in the server or in the client.
- Transport Phase – The handlers are in the phase that processes transport specific information such as validating incoming messages by looking at various transport headers, adding data into message contexts, etc.
- Pre-Dispatch Phase- The main functionality of the handlers in this phase is to populate message context to do the dispatching. For example, processing of addressing headers of the SOAP message, if any, happens in this phase. Addressing handlers extract information and put them in to the message context.
- Dispatch Phase – The Dispatchers run in this phase and try to find the correct service and operation this particular message is destined for.
The post condition of the dispatch phase (any phase can contain a post condition) checks whether a service and an operation were found by the dispatchers. If not, the execution will halt and return a “service not found’ error.
- User Defined Phases – Users can engage their custom handlers here.
- Message Validation Phase – Once the user level execution has taken place, this phase validates whether SOAP Message Processing has taken place correctly.
- Message Processing Phase – The Business logic of the SOAP message is executed here. A Message Receiver is registered with each Operation. This message receiver (associated to the particular operation) will be executed as the last handler of this phase.
There may be other handlers in any of these phases. Users may use custom handlers to override the processing logic in each of these phases.
Processing of the Outgoing Message
The Out Pipe is simpler because the service and the operation to dispatch are known by the time the pipe is executed. The Out Pipe may be initiated by the Message Receiver or the Client API implementation. Phases of the Out Pipe are described below:
- Message Initialize Phase – First phase of the Out Pipe. Serves as the placeholder for the custom handlers.
- User Phases – Executes handlers in user-defined phases.
- Transports Phase – Executes any transport handlers taken from the associated transport configuration. The last handler would be a transport sender which will send the SOAP message to the target endpoint.
Extending the SOAP Processing Model
Above, we discussed the default processing model of Axis2. Now let us discuss the extension mechanism for the SOAP processing model. After all, the whole effort of making this SOAP engine/processing model was focused on making it extendable. The idea behind introducing step-wise processing of the SOAP message in terms of handlers and phases is to allow easier modification of the processing order. The notion of phases makes it easier to place handlers in between other handlers. This enables modification of the default processing behavior. The SOAP Processing Model can be extended with handlers or modules.
Extending the SOAP Processing Model with Handlers
The handlers in a module can specify the phase they need to be placed in. Furthermore, they can specify their location inside a phase by providing phase rules. Phase rules will place a handler,
- as the first handler in a phase,
- as the last handler in a phase,
- before a given handler,
- or after a given handler.
Extending the SOAP Processing Model with Modules
Axis2 defines an entity called a ‘module’ that can introduce handlers and Web service operations. A Module in terms of Axis2 usually acts as a convenient packaging that includes:
- A set of handlers and
- An associated descriptor which includes the phase rules
Modules have the concept of being ‘available’ and ‘engaged’. ‘Availability’ means the module is present in the system, but has not been activated, i.e., the handlers included inside the module have not been used in the processing mechanism. When a module is ‘engaged’ it becomes active and the handlers get placed in the proper phases. The handlers will act in the same way as explained in the previous section. Usually a module will be used to implement a WS-* functionality such as WS-Addressing. Apart from the extension mechanism based on the handlers, the WS-* specifications may suggest a requirement for adding new operations. For example, once a user adds Reliable Messaging capability to a service, the “Create Sequence” operation needs to be available to the service endpoint. This can be implemented by letting the modules define the operations. Once the module is engaged to a service, the necessary operations will be added to that service. A service, operation, or the system may engage a module. Once the module is engaged, the handlers and the operations defined in the module are added to the entity that engaged them. Modules cannot be added (no hot deployment) while the Axis2 engine is running, but they will be available once the system is restarted.
