org.jibx.ws.soap.client
Class SoapClient

java.lang.Object
  extended by org.jibx.ws.client.Client
      extended by 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.


Project Web Site