JiBX/WS: SOAP

SOAP Specific Features

JiBX/WS currently supports SOAP 1.1. This page documents features specific to the SOAP protocol.

SOAP Headers

JiBX/WS handlers facilitate the reading and writing of SOAP headers.

Writing a SOAP header requires a handler that implements the OutHandler interface. Commonly, the MarshallingOutHandler implementation is used, which marshalls a payload using JiBX bindings. On the server side, the ContextAttributeMarshallingOutHandler implementation retrieves the payload to be written from an attribute on the current outbound message context.

Reading a SOAP header requires that the handler implement the InHandler interface. Commonly, the UnmarshallingInHandler implementation is used, which unmarshalls a payload using JiBX bindings. On the server side, the ContextAttributeUnmarshallingInHandler implementation sets an attribute on the current inbound message context with the payload that has been read.

Configuration

To add an outbound handler to the client, call the SoapClient.addOutHeaderHandler(OutHandler) method, or the convenience method SoapClient.addOutHeader(Object) which adds a MarshallingOutHandler for the specified object. Outbound header handlers are invoked in the order in which they are added.

To add an inbound handler to the client, call the SoapClient.addInHeaderHandler(InHandler) method. For each header, inbound header handlers are invoked in the order in which they are added until a handler returns true from the invoke method, when the processing of that header is deemed to be complete and processing continues with the next header.

The server is configured using handler-class elements in the service definition file. Each handler-class that implements org.jibx.ws.io.InHandler is added as an inbound header handler. Each handler-class that implements org.jibx.ws.io.OutHandler is added as an outbound header handler. Typically the classes ContextAttributeMarshallingOutHandler and ContextAttributeUnmarshallingInHandler are used, since these can write and read the header values from attributes in the current message context.

Example

See the SOAP Headers example application.

SOAP Faults

By default, for the SOAP protocol, the JiBX/WS server is configured with an exception handler that behaves as described below. This behavior can be changed by implementing a custom service exception handler.

Creating a SOAP Fault

The JiBX/WS server code will return a SOAP Fault whenever the service class throws an exception, or an error occurs in the handling of the SOAP message (for example invalid message format).

If the error is due to a failure in processing a SOAP header with the mustUnderstand attribute set, the fault code will be set to SOAP:MustUnderstand (where SOAP is the SOAP namespace), and the fault string set to the exception message.

Otherwise, by default, JiBX/WS will return a SOAP Fault with the fault code set to SOAP:Server (where SOAP is the SOAP namespace), and the fault string set to the exception message. To include a fault detail element containing a stack trace, include the fault element in the service definition file with the include-stack-trace attribute to true.

Alternatively, for full control of the contents of the SOAP Fault, the service method can return a SoapFaultException containing a SoapFault object. In order to add fault detail elements, use the SoapFault.addDetailWriter(OutHandler) method.

Receiving a SOAP Fault

On receipt of a SOAP Fault message, the JiBX/WS framework will throw a SoapFaultException containing a SoapFault object. The client code is responsible for catching this exception and taking appropriate action.

In order to read any fault detail elements, the client code must add a fault detail handler by calling addInFaultDetailsHandler(InHandler). For example, if the server is returning a stack trace in the detail element, call client. addInFaultDetailsHandler(new ExceptionReader()). The SoapClient automatically adds a UnmarshallingInHandler handler for the JiBX binding passed to its constructor, so if the detail element has a mapping in this binding, you do not need to add a handler.

Examples

The SOAP Fault Trace example configures the server to return a stack trace, and adds a handler to the client code to unmarshal this stack trace.

The SOAP Fault Custom example includes an actor element and a custom detail element in the SOAP Fault. The client code relies on the custom detail element being defined in the JiBX binding to unmarshal the detail element.