org.jibx.ws.soap.client
Class SoapClient

java.lang.Object
  org.jibx.ws.client.Client
      org.jibx.ws.soap.client.SoapClient

public final class SoapClient
extends Client

A client for accessing SOAP web services.

Typically, this class will be configured to use JiBX bindings for marshalling the request payload and unmarshalling the response payload for example using:

 SoapClient soapClient = new SoapClient("http://mystockws.com", BindingDirectory.getFactory(Ticker.class));
 response = soapClient.call(request);
 

To configure a client with different bindings for Request and Response classes:

 SoapClient soapClient = new SoapClient(path);
 soapClient.setOutBodyBindingFactory(BindingDirectory.getFactory(Request.class));
 soapClient.setInBodyBindingFactory(BindingDirectory.getFactory(Response.class));
 response = soapClient.call(request);
 

If a SOAP Fault occurs, the call method will throw a SoapFaultException. Any detail elements of the SOAP fault are skipped unless handlers are configured to read the SOAP fault detail elements, see addInFaultDetailsHandler(InHandler) or addInFaultDetailsBindingFactory(IBindingFactory).

By default an encoding of UTF-8 is used, the outbound XML is unformatted and contains an XML declaration of <?xml version="1.0" encoding="UTF-8"?>. The encoding, XML declaration and formatting of the outbound message can be overridden by calling Client.setMessageOptions(MessageOptions).

Constructor Summary

SoapClient(String location)
Create a SOAP 1.1 client to connect to a service at the specified location.

SoapClient(String location, IBindingFactory factory)
Create a SOAP 1.1 client to connect to a service at the specified location.

SoapClient(String location, IBindingFactory factory, MessageOptions options)
Create a SOAP 1.1 client to connect to a service at the specified location.

SoapClient(String location, IBindingFactory factory, MessageOptions options, SoapProtocol protocol)
Create a SOAP client to connect to a service at the specified location.

Method Summary

void	addInFaultDetailsBindingFactory(IBindingFactory factory) Adds a JiBX binding factory for the inbound SOAP fault details.
void	addInFaultDetailsHandler(InHandler inFaultDetailsHandler) Adds a handler to use for reading the SOAP fault details.
void	addInHeaderHandler(InHandler headerHandler) Adds the specified header handler to the inbound processing.
void	addOutHeader(Object obj) Adds the specified object as a header to the outbound message.
void	addOutHeaderHandler(OutHandler headerHandler) Adds the specified header handler to the outbound processing.
Object	call(Object request) Call the service with specified operation name.
void	removeAllHandlers() Removes all header handlers and inbound fault details handlers.
void	removeInFaultDetailsHandlers() Removes all inbound fault details handlers.
void	removeInHeaderHandlers() Removes all inbound header handlers.
void	removeOutHeaderHandlers() Removes all outbound header handlers.
void	setBindingFactory(IBindingFactory factory) Sets a single JiBX binding factory to be used for for marshalling and unmarshalling the SOAP body and unmarshalling any SOAP fault details.
void	setInHeaderHandlers(List inHeaderHandlers) Sets the inbound header handlers.
void	setOperationName(String operationName) Sets the name of the operation to be called.
void	setOutHeaderHandlers(List outHeaderHandlers) Sets the outbound header handlers.
void	setProtocol(SoapProtocol protocol) Set SOAP protocol version.
void	setSoapEncodingStyle(String encodingStyle) Sets the optional SOAP encodingStyle attribute on the SOAP envelope.
void	setSoapFaultResolver(SoapFaultResolver soapFaultResolver) Sets the SOAP fault resolver.

Methods inherited from class org.jibx.ws.client.Client

close, setInBodyBindingFactory, setMessageOptions, setOutBodyBindingFactory, setTransportOptions

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SoapClient

public SoapClient(String location)
           throws WsConfigurationException

Create a SOAP 1.1 client to connect to a service at the specified location.

Parameters:

location - the location of the service

Throws:

WsConfigurationException - on configuration exception, for instance the location is invalid.

SoapClient

public SoapClient(String location,
                  IBindingFactory factory)
           throws WsBindingException,
                  WsConfigurationException

Create a SOAP 1.1 client to connect to a service at the specified location. The client will use the specified JiBX binding factory for marshalling and unmarshalling the SOAP body and unmarshalling any SOAP fault details.

Parameters:

location - the location of the service

factory - the factory containing bindings for the outbound SOAP body, inbound SOAP body and inbound SOAP fault details. Bindings are only required for non-empty outbound or inbound SOAP bodies. If SOAP fault details are received that do not match any of the bindings, the SOAP fault details will be skipped.

Throws:

WsBindingException - if client cannot be created due to an error with the JiBX bindings

WsConfigurationException - on configuration exception, for instance the location is invalid.

SoapClient

public SoapClient(String location,
                  IBindingFactory factory,
                  MessageOptions options)
           throws WsBindingException,
                  WsConfigurationException

Create a SOAP 1.1 client to connect to a service at the specified location. The client will use the specified JiBX binding factory for marshalling and unmarshalling the SOAP body and unmarshalling any SOAP fault details.

Parameters:

location - the location of the service

factory - the factory containing bindings for the outbound SOAP body, inbound SOAP body and inbound SOAP fault details. Bindings are only required for non-empty outbound or inbound SOAP bodies. If SOAP fault details are received that do not match any of the bindings, the SOAP fault details will be skipped.

options - output options

Throws:

WsBindingException - if client cannot be created due to an error with the JiBX bindings

WsConfigurationException - on configuration exception, for instance the location is invalid.

SoapClient

public SoapClient(String location,
                  IBindingFactory factory,
                  MessageOptions options,
                  SoapProtocol protocol)
           throws WsBindingException,
                  WsConfigurationException

Create a SOAP client to connect to a service at the specified location. The client will use the specified JiBX binding factory for marshalling and unmarshalling the SOAP body and unmarshalling any SOAP fault details.

Parameters:

location - the location of the service

factory - the factory containing bindings for the outbound SOAP body, inbound SOAP body and inbound SOAP fault details. Bindings are only required for non-empty outbound or inbound SOAP bodies. If SOAP fault details are received that do not match any of the bindings, the SOAP fault details will be skipped.

options - output options

protocol - the version of the SOAP protocol for the client to use

Throws:

WsBindingException - if client cannot be created due to an error with the JiBX bindings

WsConfigurationException - on configuration exception, for instance the location is invalid.

Method Detail

setProtocol

public void setProtocol(SoapProtocol protocol)

Set SOAP protocol version. See SoapProtocol for supported protocols.

Parameters:

protocol - the version of SOAP protocol

setBindingFactory

public void setBindingFactory(IBindingFactory factory)
                       throws WsBindingException

Sets a single JiBX binding factory to be used for for marshalling and unmarshalling the SOAP body and unmarshalling any SOAP fault details. This binding factory should include bindings for any elements that are to be contained in the outbound or inbound SOAP body (if any) and in custom SOAP fault details (if any).

For finer grain control of the different elements use Client.setOutBodyBindingFactory(IBindingFactory), Client.setInBodyBindingFactory(IBindingFactory) and addInFaultDetailsBindingFactory(IBindingFactory).

Overrides:

setBindingFactory in class Client

Parameters:

factory - the binding factory to use for outbound and/or inbound SOAP bodies, and/or SOAP fault details

Throws:

WsBindingException - if marshaller cannot be created due to an error with the JiBX bindings

setOperationName

public void setOperationName(String operationName)

Sets the name of the operation to be called. For SOAP over HTTP the SOAP Action will be set to this value. This is not normally required for document/literal services since the element type of the marshalled request object is expected to identify the actual operation to be performed. The operation name should only be set if you have a specific need to set the SOAPAction header.

Parameters:

operationName - the operation name

setSoapEncodingStyle

public void setSoapEncodingStyle(String encodingStyle)

Sets the optional SOAP encodingStyle attribute on the SOAP envelope. If this method is not called, or the encodingStyle parameter is set to null, then no encodingStyle attribute is added.

Parameters:

encodingStyle - value to set in encodingStyle attribute

setOutHeaderHandlers

public void setOutHeaderHandlers(List outHeaderHandlers)
                          throws WsConfigurationException

Sets the outbound header handlers. Replaces existing header handlers, if any.

Parameters:

outHeaderHandlers - the list of OutHandler

Throws:

WsConfigurationException - if the list contains objects of type other than OutHandlers.

addOutHeaderHandler

public void addOutHeaderHandler(OutHandler headerHandler)

Adds the specified header handler to the outbound processing. Header handlers are called sequentially in the order that they have been added.

Parameters:

headerHandler - the handler that will write the header

addOutHeader

public void addOutHeader(Object obj)
                  throws WsException

Adds the specified object as a header to the outbound message. For this to work, there must be exactly one JiBX binding compiled for the class of the object. An appropriate handler is created that will marshal the specified object.

Parameters:

obj - the object to include in the header

Throws:

WsException - if binding cannot be found, or other error

removeOutHeaderHandlers

public void removeOutHeaderHandlers()

Removes all outbound header handlers.

setInHeaderHandlers

public void setInHeaderHandlers(List inHeaderHandlers)
                         throws WsConfigurationException

Sets the inbound header handlers. Replaces existing header handlers, if any.

Parameters:

inHeaderHandlers - the list of InHandler

Throws:

WsConfigurationException - if the list contains objects of type other than InHandlers.

addInHeaderHandler

public void addInHeaderHandler(InHandler headerHandler)

Adds the specified header handler to the inbound processing. For each SOAP header, the header handlers are invoked sequentially in the order that they have been added, until a handler returns true from the InHandler.invoke(InContext, org.jibx.runtime.IXMLReader) method, when the processing of that header is deemed to be complete, and processing carries on with the next header.

Parameters:

headerHandler - the handler that will write the header

removeInHeaderHandlers

public void removeInHeaderHandlers()

Removes all inbound header handlers.

addInFaultDetailsBindingFactory

public void addInFaultDetailsBindingFactory(IBindingFactory factory)
                                     throws WsBindingException

Adds a JiBX binding factory for the inbound SOAP fault details. Only required if SOAP fault details are to be read. Handlers will be called sequentially. The first handler that can read a particular fault detail will set the details on the SoapFault and all other handlers will be skipped.

Parameters:

factory - the JiBX binding factory to use for reading the inbound SOAP body

Throws:

WsBindingException - if unmarshaller cannot be created due to an error with the JiBX bindings

addInFaultDetailsHandler

public void addInFaultDetailsHandler(InHandler inFaultDetailsHandler)

Adds a handler to use for reading the SOAP fault details. Only required if SOAP fault details are to be read. Handlers will be called sequentially. The first handler that can read a particular fault detail will set the details on the SoapFault and all other handlers will be skipped.

Parameters:

inFaultDetailsHandler - the handler to use for reading the SOAP fault details

removeInFaultDetailsHandlers

public void removeInFaultDetailsHandlers()

Removes all inbound fault details handlers.

removeAllHandlers

public void removeAllHandlers()

Removes all header handlers and inbound fault details handlers.

setSoapFaultResolver

public void setSoapFaultResolver(SoapFaultResolver soapFaultResolver)

Sets the SOAP fault resolver. If set to a non null value, this resolver will be called in place of the default default soap fault handling, when a SOAP fault occurs.

Parameters:

soapFaultResolver - the resolver

call

public Object call(Object request)
            throws IOException,
                   WsException

Call the service with specified operation name.

Specified by:

call in class Client

Parameters:

request - object to be marshalled to XML as body of request (may be null, for an empty request body)

Returns:

response object unmarshalled from body of response (may be null, for an empty response body)

Throws:

IOException - on error in communicating with service

WsException - on error in SOAP request processing, or a WsConfigurationException if either:

• the service location has not been set before invoking this method, or
• request is non null and a binding factory or handler has not been set for the outbound SOAP body, or
• the SOAP response contains a non-empty SOAP body and a binding factory or handler has not been set for the inbound SOAP body.

SoapFaultException - if the service returns a SOAP fault, and a custom SoapFaultResolver has not been set.