SOAP Specific Features
JiBX/WS currently supports SOAP 1.1. This page documents features specific to the SOAP protocol.
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.
To add an outbound handler to the client, call the
method, or the convenience method
which adds a
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
See the SOAP Headers example application.
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.
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
Otherwise, by default, JiBX/WS will return a SOAP Fault with the fault code set to
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.
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
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.