Package com.opencloud.slee.resources.soap

The Rhino SLEE SOAP Resource Adaptor allows SLEE services to receive SOAP requests as events, and initiate SOAP requests to external systems.


Interface Summary
IncomingSOAPRequestActivity An incoming request activity, created when a SOAP request is received by the RA.
OutgoingSOAPRequestActivity An outgoing request activity, created when an application sends a SOAP request.
SOAPActivity Superclass for SOAP request and response activities.
SOAPActivityContextInterfaceFactory SOAP Activity Context Interface Factory, implemented by the SLEE.
SOAPEvent Superclass for events carrying a SOAP message payload.
SOAPProvider Provider interface for applications that want to process or send SOAP requests.
SOAPRequest A SOAP request event.
SOAPResponse A SOAP response event.

Package com.opencloud.slee.resources.soap Description

The Rhino SLEE SOAP Resource Adaptor allows SLEE services to receive SOAP requests as events, and initiate SOAP requests to external systems.

SAAJ and message factories

The SOAP RA uses the SAAJ API (previously part of JAX-RPC) to represent SOAP messages in both requests and responses. The SOAPMessage class is the top-level object used to represent a SOAP message, for both request and response payloads.

The SOAPProvider provider interface provides methods to obtain appropriate javax.xml.soap.MessageFactory and javax.xml.soap.SOAPFactory instances. These methods should be used in preference to the SAAJ newInstance() methods, as using newInstance() is likely to fail in a SLEE environment due to classloader structure.

SBBs can obtain a SOAPProvider instance via JNDI by specifying an appropriate <resource-adaptor-entity-binding> entry in the SBB deployment descriptor.

Handling incoming SOAP requests

When the SOAP RA receives a SOAP request, it creates a new IncomingSOAPRequestActivity activity and fires a SOAPRequest event on that activity. The address of the fired event is the requested URL path (from the HTTP request line) (NB: address is Not Yet Implemented).

Services that are interested in handling SOAP requests should:

To respond to a request, a SBB should use the IncomingSOAPRequestActivity.sendResponse() method, providing the SOAP message to send as a response. This can be done either directly from the SOAPRequest event handler, or asynchronously at some later point (for example, after data for the response has been collected from a separate external system). When a response is provided, the IncomingSOAPRequestActivity is automatically ended by the resource adaptor.

If no SBB processes a SOAPRequest event, or if there is no SOAP response provided by a SBB within a configurable timeout, the SOAP RA will send a SOAP Fault response and end the IncomingSOAPRequestActivity.

Sending SOAP requests to other systems

The SOAPProvider interface provides methods that allow SBBs to send synchronous or asynchronous SOAP requests.

SOAP requests consist of a SOAPMessage payload and a URL specifying the location to deliver the request to. Responses consist of a SOAPMessage payload, and HTTP-level status codes (numeric code and reason), encapsulated together in the SOAPResponse class.

If a connection error or HTTP-level error occurs such that no SOAP response is available from the remote server, a SOAP response containing an appropriate SOAP fault is synthesized and returned.

Synchronous SOAP requests are made by invoking the SOAPProvider.sendSyncRequest() method. This method blocks until a response is available, and returns that response.

Asynchronous SOAP requests are initiated by invoking the SOAPProvider.sendRequest() methods. These methods causes a new OutgoingSOAPRequestActivity activity to be created and associated with the request. When the request completes, a SOAPResponse event is fired on the outgoing activity. SBBs that wish to receive the response should attach to the activity returned by sendRequest.

By default, an outgoing SOAP request activity is ended when a response is received. This can be prevented by passing false as endOnResponse when calling sendRequest(). In this case, the outgoing activity must be explicitly ended by a SBB calling OutgoingSOAPRequestActivity.endActivity() when the activity is no longer needed.

Configuration Properties

The SOAP resource adaptor has a number of configuration properties:

Hostname or IP address to accept connections on
Numeric port to accept connections on
Milliseconds to wait for a SBB to generate a response to an incoming request. If this timeout is exceeded, the SOAP RA will return a SOAP Fault to the requesting client.
Milliseconds of idle time to allow on a persistant incoming connection before it is closed. Should generally be longer than the corresponding outgoing idle timeout of the peer.
Maximum number of outgoing connections to make to a single host.
Milliseconds to wait for a response from a remote server before returning an error response (SOAP fault) to the initiating SBB.
Milliseconds of idle time to allow on a persistent outgoing connection before it is closed. Should generally be shorter than the corresponding incoming idle timeout of the peer.
Maximum number of outgoing requests on a single connection that may be in flight simultaneously (i.e. without waiting for a response to previous requests).
Maximum time in milliseconds that an outgoing request may be queued waiting for an available outgoing connection before returning an error response (SOAP fault) to the initiating SBB.
Time in milliseconds between reconnect attempts to a failed server.
The value of the Server: header to report in SOAP responses.
The value of the User-Agent: header to report in SOAP requests.
Maximum value in bytes for the Content-Length header of the encapsulating HTTP messages which have a message body. If this value is exceeded, an error response (SOAP fault) is issued.