org.osesb.connectors.jaxrpc
Class JAXRPCDynamicClient

java.lang.Object
  org.osesb.connectors.jaxrpc.JAXRPCDynamicClient

Direct Known Subclasses:

JAXRPCDynamicSendMessageClient

public class JAXRPCDynamicClient
extends java.lang.Object

This class is an ancestor for jax-rpc clients that use jax-rpc dynamic invocation to invoke Web Services.

With the dynamic invocation interface (DII), a client can call a service end-point when the signature of the remote procedure and the name of the service are unknown until runtime. DII does not use platform-generated client stubs, therefore, DII clients do not require proprietary libraries; any jax-rpc compliant SOAP library will do.

However, osESB uses Axis for the client SOAP engine and this Class takes advantage of Axis' provisioning for setting properties on the Call object, which is passed to the MessageContext, which in turn can be accessed by client-side handlers.

There is a limitation (or inconvenience) when using dynamic invocation instead of client stubs when complex SOAP parameters and return types are involved. For interaction with web services that involve complex types, it is recommended that wsdl2java be used to generate the service-specific library of Java classes necessary for the interaction. This approach avoids configuring the <bean-mapping> tags for the client, which can be cumbersome.

JAXRPCDynamicClient uses the target service's WSDL document to create a jax-rpc Call Object, which is then used to invoke the service. An instance of JAXRPCDynamicClient is associated with a particular service end point as well as a List of client-side handlers. The jax-rpc Call object is cached (but can be reset) and JAXRPCDynamicClient can be pooled. See org.osesb.objectpools.JAXRPCClientKeyedPoolFactory.

The wsdl location can be configured as a URL or as an entry in the configured instance of the XMLRepository. See org.osesb.configuration.JAXRPCClientConfiguration#loadWSDLLocation() and the org.osesb.xmlrepository package.

Instances of JAXRPCDynamicClient are constructed with a org.osesb.configuration.JAXRPCClientConfiguration, which contains properties for creating the jax-rpc Call Object for the service end-point. A JAXRPCClientConfiguration file must include at least the following XML tags. Except for the javax.xml.rpc.ServiceFactory tag, the values of the tags are obtained by inspecting the WSDL document for the service end-point.

• javax.xml.rpc.ServiceFactory, which specifies the name of the javax.xml.rpc.ServiceFactory class for the SOAP client library in the class path.
• targetNamespace, the target namespace of the service end-point.
• serviceName, the name of the service end-point.
• portName, the name of the service end-point port.
• operationName, the name of the method being invoked.
• wsdlLocation, the URL giving the address of the WSDL document for the service end-point.

A JAXRPCClientConfiguration can also include entries for jax-rpc, client-side handlers, which implement the javax.xml.rpc.handler.Handler interface. The handleRequest() and handleResponse() methods of that interface are invoked by the SOAP client engine as follows:

• handleRequest() is invoked before a RPC request is communicated to the target service endpoint.
• handleResponse() is invoked before a RPC response is returned to the client from the web service endpoint.

Handlers can be configured as part of a org.osesb.configuration.JAXRPCClientConfiguration or can be added using this Class's addHandler() method. In either case, the createCall() method registers client-side handlers with the SOAP engine before the jax-rpc Call object is returned. Handlers that are added to the SOAP processing pipeline using the addHandler() method can include parameters that are Objects. Handler configurations within a JAXRPCClientConfiguration file can ONLY include String parameters. However, Object parameters can be added to any named handler using the addHandlerParameter() method in this Class.

A handler configuration content model within a JAXRPCClientConfiguration looks like:

<!-- client side handler chain, executed in order -->
      <!-- handler class must implement the javax.xml.rpc.handler.Handler interface -->
      <handler-chain>
          <handler>
              <handler-class>org.osesb.connectors.jaxrpc.test.JAXRPCClientSecurityHandler</handler-class>
              <init-params>
                  <!-- optional name for the jax-rpc handler (default is none) -->
                  <init-param name="name" value="SecurityHandler"/>
                  <!-- optional debugFlag for the jax-rpc handler (default is false) -->
                  <init-param name="debugFlag" value="true"/>
                  <!--  If the enabled parameter is false, then the handler remains configured, but
                  the handleRequest() and handleResponse() methods should return true without processing.
                  (default is true) -->
                  <init-param name="enabled" value="true"/>
                  <!--  If the requestEnabled parameter is false, then the handler remains configured, but
                  the handleRequest() method should return true without processing.
                  (default is true) -->
                  <init-param name="requestEnabled" value="true"/>
                  <!--  If the responseEnabled parameter is false, then the handler remains configured, but
                  the handleResponse() method should return true without processing.
                  (default is true) -->
                  <init-param name="responseEnabled" value="true"/>
              </init-params>
          </handler>
      </handler-chain>
 

The configured service is invoked using one of two methods:

• The invokeService() method , which takes only an Object[] of parameters and returns an Object as the result. Note that for asynchronous services (a.k.a. notifications), the result is null.
• The invokeService() method , which takes an Object[] of parameters, a username, and a password. This method also returns an Object as the result. When the invokeService() method of JAXRPCDynamicClient (or a descendant) is passed a username, JAXRPCClientSecurityHandler (or a descendant) is used to generate a security header entry for the SOAPHeader. The format of the security header entry is determined by a descendant of WSSSecurityProfile, which can be configured for the JAXRPCClientSecurityHandler.

When invokeService() is passed a username and password and if a security handler Class, like org.osesb.connectors.jaxrpc.security.JAXRPCClientSecurityHandler, is not already in the handler list, then addDefaultSecurityHandler() is invoked by invokeService() to add a default security handler Class to this.handlerList. That is, if a security handler is not configured as part of the JAXRPCClientConfiguration and a security handler has not been added to the handlerList using addHandler(), then a default security handler is determined according to the following ordered lookup:

1. The JAXRPCClientSecurityHandler, or descendant thereof, that is identified by the SecurityConstants.WSSE_CLIENT_SECURITYHANDLER_SYSTEMPROPERTY System Property.
2. The JAXRPCClientSecurityHandler, or descendant thereof, that is identified by SecurityConstants.DEFAULT_WSSE_CLIENT_SECURITYHANDLER_CLASS.

If a communications error occurs or if an error occurs at the service end-point, invokeService() will reconstruct the jax-rpc Call Object and retry the service end-point according to the JAXRPCClientConfiguration property 'retryCount'.

The jax-rpc Call Object, which is the result of consuming the target service's WSDL document, is maintained acrosss invocations of invokeService(). If an error occurs while invoking a service end-point, the Call object is reset.

JAXRPCDynamicClient supports transactions in a manner that is analogous to transacted JMS sessions, where messages are stored in an internal buffer until a commit or rollback is issued on the JMS Session

If the 'transactedClient' property of a JAXRPCClientConfiguration is set to true, JAXRPCDynamicClient (or descendent) will hold service invocation parameters, security credentials, and attachments in an internal buffer until commit() or rollback() is called. commit() returns an Object[] that holds one entry for each successful service invocation that commit() executes. Each entry contains the response from the web service as an Object. If the service response includes attachments, the entry is an org.osesb.eaimessage.EAIObjectMessageWithAttachments Object. If the service response does not include attachments, the entry is an org.osesb.eaimessage.EAIObjectMessage Object.

If any invocation throws an Exception, commit() throws the Exception.

A JAXRPCDynamicClientTransactionManager is instantiated by JAXRPCDynamicClient hold service invocation parameters, security credentials, and attachments in an internal buffer until commit() or rollback() is called.

JAXRPCDynamicClient(s), and descendants thereof, can be pooled. See org.osesb.objectpools.JAXRPCClientKeyedPoolFactory.

Since:

Version .9

Field Summary

protected javax.xml.rpc.Call	call The jax-rpc Call Object as configured in jaxrpcClientConfiguration.
protected java.util.List	handlerList The jax-rpc, client-side handlers as a list of javax.xml.rpc.handler.HandlerInfo Objects.
protected JAXRPCClientConfiguration	jaxrpcClientConfiguration The JAXRPCClientConfiguration passed to the Constructor.
protected JAXRPCDynamicClientTransactionManager	jaxrpcDynamicClientTransactionManager JAXRPCDynamicClient supports transactions in a manner that is analogous to transacted JMS sessions, where messages are stored in an internal buffer until a commit or rollback is issued on the JMS Session If the 'transactedClient' property of a JAXRPCClientConfiguration is set to true, JAXRPCDynamicClient (or descendent) will hold service invocation parameters, security credentials, and attachments in an internal buffer until commit() or rollback() is called.
protected static org.apache.commons.logging.Log	log The logging implementation for this class.
protected java.util.List	requestAttachmentList requestAttachmentList is a List of org.osesb.connectors.jaxrpc.attachments.AttachmentDescriptor(s) that are used to add attachments to outgoing SOAPMessages.
protected java.util.List	responseAttachmentList responseAttachmentList is a List of org.osesb.connectors.jaxrpc.attachments.AttachmentDescriptor(s) that encapsulate attachments that were detached from an incoming SOAPMessage.
protected java.lang.String	thisClassName The full name of this class.

Constructor Summary

JAXRPCDynamicClient(JAXRPCClientConfiguration jaxrpcClientConfiguration)
Creates a new instance of JAXRPCDynamicClient.

Method Summary

protected void	addDefaultAttachmentHandler() If the requestAttachmentList is not empty when invokeService() is called and if an attachment handler Class, like org.osesb.connectors.jaxrpc.attachments.JAXRPCClientAttachmentHandler, is not already in the handler list, then addDefaultAttachmentHandler() is invoked by invokeService() to add a default attachment handler Class to this.handlerList.
protected void	addDefaultJMSTransportHandler() If a JAXRPCDynamicClient (or descendant) is configured with a JAXRPCClientConfiguration that includes a JMSClientConfiguration, a JAXRPCClientJMSTransportHandler (or descendent) is used to send the SOAP message using the JMS client configured by the JMSClientConfiguration, which can be: org.osesb.connectors.jms.JMSQueueSender org.osesb.connectors.jms.JMSTopicPublisher If a JMSClientConfiguration is present when invokeService() is called and if a jms transport handler Class, like org.osesb.connectors.jaxrpc.jmstransport.JAXRPCClientJMSTransportHandler, is not already in the handler list, then addDefaultJMSTransportHandler() is invoked by invokeService() to add a default jms transport handler Class to this.handlerList.
protected void	addDefaultSecurityHandler() When the invokeService() method of JAXRPCDynamicClient (or a descendant) is passed a username, JAXRPCClientSecurityHandler (or a descendant) is used to generate a security header entry for the SOAPHeader.
protected void	addDefaultWSAddressingHandler() If a JAXRPCDynamicClient (or descendant) is configured with a JAXRPCClientConfiguration that includes a JAXRPCWSAddressingConfiguration, a JAXRPCClientAddressingHandler (or descendent) is used to add ws-addressing entries to the SOAPHeader.
void	addHandler(javax.xml.rpc.handler.HandlerInfo handlerInfo) The jax-rpc, client-side handlers as a list of javax.xml.rpc.handler.HandlerInfo Objects.
void	addHandlerParameter(java.lang.String handlerName, java.lang.String parameterName, java.lang.Object parameterValue) Add a parameter to a named handler.
void	addRequestAttachment(byte[] bytes) Add a byte[] as an attachment to the to the Call object.
void	addRequestAttachments(AttachmentDescriptor[] attachmentDescriptors) Add attachments to the to the Call object, where attachment properties and contents are specified as org.osesb.connectors.jaxrpc.attachments.AttachmentDescriptor(s).
void	addRequestAttachments(java.io.File[] fileAttachments) Add File attachments to the Call object.
void	addRequestAttachments(java.io.InputStream[] streamAttachments) Add InputStream attachments to the Call object.
void	clearRequestAttachmentList() Clear the requestAttachmentList.
void	clearResponseAttachmentList() Clear the responseAttachmentList.
void	clearTransactionList() Clear the List of TransactionBufferEntry(s) for the JAXRPCDynamicClientTransactionManager.
void	clearVolatileCallProperties() Invoked immediately after a service invocation completes to reset volatile properties, which are passed to handlers using the MessageContext.
java.lang.Object[]	commit() Invoke the configured service with the service invocation parameters, security credentials, and attachments held in jaxrpcDynamicClientTransactionManager.
protected javax.xml.rpc.Call	createCall() Create a jax-rpc Call Object based on jaxrpcClientConfiguration.
JAXRPCClientConfiguration	getJAXRPCClientConfiguration() Return the JAXRPCClientConfiguration for this JAXRPCDynamicClient.
java.lang.String	getMessageIDForLastOutgoingMessage() Return the value for the ws-addressing <wsa:MessageID> from the last invocation, which may have been set by a client-side addresssing handler and will be valid if any of the JAXRPCWSAddressingConfiguration methods, generateMessageID(), hasReplyTo(), or hasFaultTo() returned true when the last message was sent.
java.util.List	getResponseAttachments() Retrieve the attachments extracted from the SOAP response message by the handleResponse() method of JAXRPCClientAttachmentHandler (or descdendent).
java.lang.Object	invokeService(java.lang.Object[] serviceParameters) Invoke the service configured in jaxrpcClientConfiguration with the given service parameters and no security.
java.lang.Object	invokeService(java.lang.Object[] serviceParameters, java.lang.String username, java.lang.String password) Invoke the service configured in jaxrpcClientConfiguration with the given service parameters and optional UsernameToken security.
protected java.lang.Object	invokeService(java.lang.Object[] serviceParameters, java.lang.String username, java.lang.String password, boolean invokedByCommit) Invoke the service configured in jaxrpcClientConfiguration with the given service parameters and optional UsernameToken security.
protected boolean	isVoidReturnType(javax.xml.rpc.Call call) Normalize the return from the getReturnType() method of a javax.xml.rpc.Call object.
static void	main(java.lang.String[] args) Main method for testing.
void	reset() Resets this JAXRPCDynamicClient by setting the Call object to null so that it is re-created the next time invokeService() is called.
void	rollback() Clear the List of TransactionBufferEntry(s) for the JAXRPCDynamicClientTransactionManager.

Methods inherited from class java.lang.Object

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

Field Detail

log

protected static org.apache.commons.logging.Log log

The logging implementation for this class.

thisClassName

protected java.lang.String thisClassName

The full name of this class.

jaxrpcClientConfiguration

protected JAXRPCClientConfiguration jaxrpcClientConfiguration

The JAXRPCClientConfiguration passed to the Constructor.

handlerList

protected java.util.List handlerList

The jax-rpc, client-side handlers as a list of javax.xml.rpc.handler.HandlerInfo Objects.

jax-rpc, client-side handlers implement the javax.xml.rpc.handler.Handler interface. The handleRequest() and handleResponse() methods of that interface are invoked by the SOAP client engine as follows:

• handleRequest() is invoked before a RPC request is communicated to the target service endpoint.
• handleResponse() is invoked before a RPC response is returned to the client from the web service endpoint.

The javax.xml.rpc.handler.GenericHandler class is an abstract class that implements the Handler interface. Typically, handlers are sub-classed from GenericHandler, which includes an init() method that can be used to pass parameters to a handler.

Handlers can be configured as part of a org.osesb.configuration.JAXRPCClientConfiguration or can be added using this Class's addHandler() method. In either case, the createCall() method registers client-side handlers with the SOAP engine before the jax-rpc Call object is returned. Handlers that are added to the SOAP processing pipeline using the addHandler() method can include parameters that are Objects. Handler configurations within a JAXRPCClientConfiguration file can ONLY include String parameters. However, Object parameters can be added to any named handler using the addHandlerParameter() method in JAXRPCDynamicClient.

requestAttachmentList

protected java.util.List requestAttachmentList

requestAttachmentList is a List of org.osesb.connectors.jaxrpc.attachments.AttachmentDescriptor(s) that are used to add attachments to outgoing SOAPMessages.

Attachments are added using the addRequestAttachments() methods prior to calling invokeService(). The attachments are added to the Call object using it's setProperty() method. Attachments are added to the SOAPMessage by org.osesb.connectors.jaxrpc.attachments.JAXRPCClientAttachmentHandler, or a descendant of JAXRPCClientAttachmentHandler.

If the requestAttachmentList is not empty when invokeService() is called and if an attachment handler Class, like org.osesb.connectors.jaxrpc.attachments.JAXRPCClientAttachmentHandler, is not already in the handler list, then addDefaultAttachmentHandler() is invoked by invokeService() to add a default attachment handler Class to this.handlerList. That is, if an attachment handler is not configured as part of the JAXRPCClientConfiguration and an attachment handler has not been added to the handlerList using addHandler(), then a default attachment handler is determined according to the following ordered lookup:

1. The JAXRPCClientAttachmentHandler, or descendant thereof, that is identified by the AttachmentConstants.CLIENT_ATTACHMENTHANDLER_SYSTEMPROPERTY System Property.
2. The JAXRPCClientAttachmentHandler, or descendant thereof, that is identified by AttachmentConstants.DEFAULT_CLIENT_ATTACHMENTHANDLER_CLASS.

There are two methods for adding attachments. One adds an attachment element to the SOAPHeader the other does not. Attachment header entries are added ONLY for AttachmentDescriptor(s) that were added to requestAttachmentList using JAXRPCDynamicClient's addRequestAttachments(AttachmentDescriptor[] attachmentDescriptors) method and ONLY for AttachmentDescriptor(s) with a 'generateAttachmentDescriptor' property set to true.

responseAttachmentList

protected java.util.List responseAttachmentList

responseAttachmentList is a List of org.osesb.connectors.jaxrpc.attachments.AttachmentDescriptor(s) that encapsulate attachments that were detached from an incoming SOAPMessage.

responseAttachmentList holds the attachments that were detached from an incoming SOAPMessages by the handleResponse method of JAXRPCClientAttachmentHandler (or descendent). After invokeService completes, invoke getAttachments() to retrieve attachments sent by the invoked service.

In order to retrieve attachments from an incoming SOAPMessage, JAXRPCClientAttachmentHandler (or descendent) must be explicitly configured in the <handler-chain> element of the JAXRPCConfiguration file for this JAXRPCDynamicClient.

jaxrpcDynamicClientTransactionManager

protected JAXRPCDynamicClientTransactionManager jaxrpcDynamicClientTransactionManager

JAXRPCDynamicClient supports transactions in a manner that is analogous to transacted JMS sessions, where messages are stored in an internal buffer until a commit or rollback is issued on the JMS Session

If the 'transactedClient' property of a JAXRPCClientConfiguration is set to true, JAXRPCDynamicClient (or descendent) will hold service invocation parameters, security credentials, and attachments in an internal buffer until commit() or rollback() is called. commit() returns an Object[] that holds one entry for each successful service invocation that commit() executes. Each entry contains the response from the web service as an Object. If the service response includes attachments, the entry is an org.osesb.eaimessage.EAIObjectMessageWithAttachments Object. If the service response does not include attachments, the entry is an org.osesb.eaimessage.EAIObjectMessage Object.

If any invocation throws an Exception, commit() throws the Exception.

A JAXRPCDynamicClientTransactionManager is instantiated by JAXRPCDynamicClient hold service invocation parameters, security credentials, and attachments in an internal buffer until commit() or rollback() is called.

call

protected javax.xml.rpc.Call call

The jax-rpc Call Object as configured in jaxrpcClientConfiguration.

The Call object is cached, but Call property values are cleared before each invocation.

See reset() and createCall().

Constructor Detail

JAXRPCDynamicClient

public JAXRPCDynamicClient(JAXRPCClientConfiguration jaxrpcClientConfiguration)
                    throws java.lang.Exception

Creates a new instance of JAXRPCDynamicClient.

Parameters:

jaxrpcClientConfiguration - The JAXRPCClientConfiguration object for this jax-rpc client.

Throws:

java.lang.Exception - if constructed with a null JAXRPCClientConfiguration.

Method Detail

invokeService

public java.lang.Object invokeService(java.lang.Object[] serviceParameters)
                               throws java.lang.Exception

Invoke the service configured in jaxrpcClientConfiguration with the given service parameters and no security.

Parameters:

serviceParameters - The parameters of the service as an Object[].

Returns:

the result of a synchronous jax-rpc call as an Object For asynchronous services (a.k.a. notifications), the return Object is null.

Throws:

javax.xml.rpc.soap.SOAPFaultException - Indicates a SOAP fault.

javax.xml.rpc.JAXRPCException - Indicates a run-time error.

java.lang.Exception

invokeService

public java.lang.Object invokeService(java.lang.Object[] serviceParameters,
                                      java.lang.String username,
                                      java.lang.String password)
                               throws java.lang.Exception

Invoke the service configured in jaxrpcClientConfiguration with the given service parameters and optional UsernameToken security.

When the invokeService() method of JAXRPCDynamicClient (or a descendant) is passed a username, JAXRPCClientSecurityHandler (or a descendant) is used to generate a security header entry for the SOAPHeader. The format of the security header entry is determined by a descendant of WSSSecurityProfile, which can be configured for the JAXRPCClientSecurityHandler.

Parameters:

serviceParameters - The parameters of the service as an Object[].

username - The username for the SOAP security header entry.

password - The optional password for the SOAP security header entry.

Returns:

the result of a synchronous jax-rpc call as an Object For asynchronous services (a.k.a. notifications), the return Object is null.

Throws:

javax.xml.rpc.soap.SOAPFaultException - Indicates a SOAP fault.

javax.xml.rpc.JAXRPCException - Indicates a run-time error.

java.lang.Exception

invokeService

protected java.lang.Object invokeService(java.lang.Object[] serviceParameters,
                                         java.lang.String username,
                                         java.lang.String password,
                                         boolean invokedByCommit)
                                  throws java.lang.Exception

Invoke the service configured in jaxrpcClientConfiguration with the given service parameters and optional UsernameToken security.

When the invokeService() method of JAXRPCDynamicClient (or a descendant) is passed a username, JAXRPCClientSecurityHandler (or a descendant) is used to generate a security header entry for the SOAPHeader. The format of the security header entry is determined by a descendant of WSSSecurityProfile, which can be configured for the JAXRPCClientSecurityHandler.

Parameters:

serviceParameters - The parameters of the service as an Object[].

username - The username for the SOAP security header entry.

password - The optional password for the SOAP security header entry.

invokedByCommit - If true, indicates that invokeService() was called by commit() and that outstanding web service invocations are being executed.

Returns:

the result of a synchronous jax-rpc call as an Object For asynchronous services (a.k.a. notifications), the return Object is null.

Throws:

javax.xml.rpc.soap.SOAPFaultException - Indicates a SOAP fault.

javax.xml.rpc.JAXRPCException - Indicates a run-time error.

java.lang.Exception

createCall

protected javax.xml.rpc.Call createCall()
                                 throws java.lang.Exception

Create a jax-rpc Call Object based on jaxrpcClientConfiguration. createCall() is invoked before service invocation.

Throws:

java.lang.Exception - if there is a problem obtaining a Call Object.

getMessageIDForLastOutgoingMessage

public java.lang.String getMessageIDForLastOutgoingMessage()

Return the value for the ws-addressing <wsa:MessageID> from the last invocation, which may have been set by a client-side addresssing handler and will be valid if any of the JAXRPCWSAddressingConfiguration methods, generateMessageID(), hasReplyTo(), or hasFaultTo() returned true when the last message was sent.

The value for the ws-addressing <wsa:MessageID> property in the JAXRPCWSAddressingConfiguration for this client is cleared whenever invokeService() is called.

clearVolatileCallProperties

public void clearVolatileCallProperties()

Invoked immediately after a service invocation completes to reset volatile properties, which are passed to handlers using the MessageContext. These are the properties that change for each invocation.

Note that a cached Call object is tied to a particular end point operation. So, once set, properties related to ws-addressing and jms transport remain the same across invocations but attachments and security credentials are different for each invocation.

addDefaultSecurityHandler

protected void addDefaultSecurityHandler()
                                  throws java.lang.Exception

When the invokeService() method of JAXRPCDynamicClient (or a descendant) is passed a username, JAXRPCClientSecurityHandler (or a descendant) is used to generate a security header entry for the SOAPHeader.

addDefaultSecurityHandler() is invoked by invokeService() to add a default security handler Class to this.handlerList if a security handler Class is not already in the handler list.

Hanlders can be configured for the handler list as part of a <handler-chain> in the JAXRPCClientConfiguration file or are added using addHandler().

If a security handler Class is not already in the handler list, the default security handler is determined according to the following ordered lookup:

1. The JAXRPCClientSecurityHandler, or descendant thereof, that is identified by the SecurityConstants.WSSE_CLIENT_SECURITYHANDLER_SYSTEMPROPERTY System Property.
2. The JAXRPCClientSecurityHandler, or descendant thereof, that is identified by SecurityConstants.DEFAULT_WSSE_CLIENT_SECURITYHANDLER_CLASS.

Throws:

java.lang.Exception - if an error occurs while adding a default security handler to this.handlerList.

addDefaultAttachmentHandler

protected void addDefaultAttachmentHandler()
                                    throws java.lang.Exception

If the requestAttachmentList is not empty when invokeService() is called and if an attachment handler Class, like org.osesb.connectors.jaxrpc.attachments.JAXRPCClientAttachmentHandler, is not already in the handler list, then addDefaultAttachmentHandler() is invoked by invokeService() to add a default attachment handler Class to this.handlerList. That is, if an attachment handler is not configured as part of the JAXRPCClientConfiguration and an attachment handler has not been added to the handlerList using addHandler(), then a default attachment handler is determined according to the following ordered lookup:

1. The JAXRPCClientAttachmentHandler, or descendant thereof, that is identified by the AttachmentConstants.CLIENT_ATTACHMENTHANDLER_SYSTEMPROPERTY System Property.
2. The JAXRPCClientAttachmentHandler, or descendant thereof, that is identified by AttachmentConstants.DEFAULT_CLIENT_ATTACHMENTHANDLER_CLASS.

Throws:

java.lang.Exception - if an error occurs while adding a default attachment handler to this.handlerList.

addDefaultWSAddressingHandler

protected void addDefaultWSAddressingHandler()
                                      throws java.lang.Exception

If a JAXRPCDynamicClient (or descendant) is configured with a JAXRPCClientConfiguration that includes a JAXRPCWSAddressingConfiguration, a JAXRPCClientAddressingHandler (or descendent) is used to add ws-addressing entries to the SOAPHeader.

If a JAXRPCWSAddressingConfiguration is present when invokeService() is called and if a ws-addressing handler Class, like org.osesb.connectors.jaxrpc.addressing.JAXRPCClientAddressingHandler, is not already in the handler list, then addDefaultWSAddressingHandler() is invoked by invokeService() to add a default ws-addressing handler Class to this.handlerList. That is, if a ws-addressing handler is not configured as part of the JAXRPCClientConfiguration and a ws-addressing handler has not been added to the handlerList using addHandler(), then a default ws-addressing handler is determined according to the following ordered lookup:

1. The JAXRPCClientAddressingHandler, or descendant thereof, that is configured in the client handler chain of the JAXRPCClientConfiguration file.
2. The JAXRPCClientAddressingHandler, or descendant thereof, that is identified by the AddressingConstants.WSA_CLIENT_ADDRESSINGHANDLER_SYSTEMPROPERTY System Property.
3. The JAXRPCClientSecurityHandler, or descendant thereof, that is identified by AddressingConstants.DEFAULT_WSA_CLIENT_ADDRESSINGHANDLER_CLASS.

Throws:

java.lang.Exception - if an error occurs while adding a default ws-addressing handler to this.handlerList.

addDefaultJMSTransportHandler

protected void addDefaultJMSTransportHandler()
                                      throws java.lang.Exception

If a JAXRPCDynamicClient (or descendant) is configured with a JAXRPCClientConfiguration that includes a JMSClientConfiguration, a JAXRPCClientJMSTransportHandler (or descendent) is used to send the SOAP message using the JMS client configured by the JMSClientConfiguration, which can be:

• org.osesb.connectors.jms.JMSQueueSender
• org.osesb.connectors.jms.JMSTopicPublisher

If a JMSClientConfiguration is present when invokeService() is called and if a jms transport handler Class, like org.osesb.connectors.jaxrpc.jmstransport.JAXRPCClientJMSTransportHandler, is not already in the handler list, then addDefaultJMSTransportHandler() is invoked by invokeService() to add a default jms transport handler Class to this.handlerList. That is, if a jms transport handler is not configured as part of the JAXRPCClientConfiguration and a jms transport handler has not been added to the handlerList using addHandler(), then a default jms transport handler is determined according to the following ordered lookup:

1. The JAXRPCClientJMSTransportHandler, or descendant thereof, that is configured in the client handler chain of the JAXRPCClientConfiguration file.
2. The JAXRPCClientJMSTransportHandler, or descendant thereof, that is identified by the JMSConstants.SOAP_OVER_JMS_TRANSPORTHANDLER_SYSTEMPROPERTY System Property.
3. The JAXRPCClientSecurityHandler, or descendant thereof, that is identified by JMSConstants.DEFAULT_SOAP_OVER_JMS_TRANSPORTHANDLER_CLASS.

Throws:

java.lang.Exception

addHandler

public void addHandler(javax.xml.rpc.handler.HandlerInfo handlerInfo)
                throws java.lang.Exception

The jax-rpc, client-side handlers as a list of javax.xml.rpc.handler.HandlerInfo Objects.

jax-rpc, client-side handlers implement the javax.xml.rpc.handler.Handler interface. The handleRequest() and handleResponse() methods of that interface are invoked by the SOAP client engine as follows:

• handleRequest() is invoked before a RPC request is communicated to the target service endpoint.
• handleResponse() is invoked before a RPC response is returned to the client from the web service endpoint.

The javax.xml.rpc.handler.GenericHandler class is an abstract class that implements the Handler interface. Typically, handlers are sub-classed from GenericHandler, which includes an init() method that can be used to pass parameters to a handler.

Handlers can be configured as part of a org.osesb.configuration.JAXRPCClientConfiguration or can be added using this method. In either case, the createCall() method registers client-side handlers with the SOAP engine before the jax-rpc Call object is returned. Handlers that are added to the SOAP processing pipeline using the addHandler() method can include parameters that are Objects. Handler configurations within a JAXRPCClientConfiguration file can ONLY include String parameters. However, Object parameters can be added to any named handler using the addHandlerParameter() method in JAXRPCDynamicClient.

Parameters:

handlerInfo - A javax.xml.rpc.handler.HandlerInfo object, which represents information about the handler to be added to the SOAP handler-chain. Typically, HandlerInfo objects are constructed using this constructor signature: HandlerInfo(handlerClass, handlerConfig, null), where:

• handlerClass is the Java Class for the Handler.
• handlerConfig is the Handler Configuration as a java.util.Map.

Throws:

java.lang.Exception

addHandlerParameter

public void addHandlerParameter(java.lang.String handlerName,
                                java.lang.String parameterName,
                                java.lang.Object parameterValue)
                         throws java.lang.Exception

Add a parameter to a named handler.

Parameters:

handlerName - The name of the handler to add the parameter to. Handler names are specified using the 'name' parameter.

parameterName - The name of the parameter to add.

parameterValue - The value of the parameter to add.

Throws:

java.lang.Exception

clearRequestAttachmentList

public void clearRequestAttachmentList()

Clear the requestAttachmentList.

clearResponseAttachmentList

public void clearResponseAttachmentList()

Clear the responseAttachmentList.

addRequestAttachments

public void addRequestAttachments(java.io.File[] fileAttachments)
                           throws java.lang.Exception

Add File attachments to the Call object. The attachments are added to the outgoing SOAPMessage when invokeService is called.

Attachment header entries are not added to the request SOAPHeader. Use the addRequestAttachments() method that takes an AttachmentDescriptor[] to add attahment header entries to the request SOAPHeader.

Parameters:

fileAttachments - A File[] of attachments to add to the Call object. Each File represents a seperate attachment.

Throws:

java.lang.Exception - If any File in fileAttachments cannot be read into a byte[].

addRequestAttachments

public void addRequestAttachments(java.io.InputStream[] streamAttachments)
                           throws java.lang.Exception

Add InputStream attachments to the Call object. The attachments are added to the outgoing SOAPMessage when invokeService is called.

All InputStream(s) are closed after being read.

Attachment header entries are not added to the request SOAPHeader. Use the addRequestAttachments() method that takes an AttachmentDescriptor[] to add attahment header entries to the request SOAPHeader.

Parameters:

streamAttachments - A InputStream[] of attachments to add to the Call object. Each InputStream represents a seperate attachment.

Throws:

java.lang.Exception - If any InputStream in streamAttachments cannot be read into a byte[].

addRequestAttachment

public void addRequestAttachment(byte[] bytes)
                          throws java.lang.Exception

Add a byte[] as an attachment to the to the Call object. The attachments are added to the outgoing SOAPMessage when invokeService is called.

Attachment header entries are not added to the request SOAPHeader. Use the addRequestAttachments() method that takes an AttachmentDescriptor[] to add attahment header entries to the request SOAPHeader.

Parameters:

bytes - A byte[] that holds the contents of a single attachment.

Throws:

java.lang.Exception - If byte[] is null or empty.

addRequestAttachments

public void addRequestAttachments(AttachmentDescriptor[] attachmentDescriptors)
                           throws java.lang.Exception

Add attachments to the to the Call object, where attachment properties and contents are specified as org.osesb.connectors.jaxrpc.attachments.AttachmentDescriptor(s).

The attachments are added to the outgoing SOAPMessage when invokeService is called.

AttachmentDescriptor properties are added as Attachment header entries to the request SOAPHeader for each AttachmentDescriptor whose generateAttachmentDescriptor property is true.

Parameters:

attachmentDescriptors - An AttachmentDescriptor[] where each AttachmentDescriptor specifies the contents and properties of a single attachment.

Throws:

java.lang.Exception - If any AttachmentDescriptor is null.

getResponseAttachments

public java.util.List getResponseAttachments()

Retrieve the attachments extracted from the SOAP response message by the handleResponse() method of JAXRPCClientAttachmentHandler (or descdendent).

Returns:

A List of AttachmentDescriptor(s) where each AttachmentDescriptor specifies the contents and properties of a single attachment.

clearTransactionList

public void clearTransactionList()

Clear the List of TransactionBufferEntry(s) for the JAXRPCDynamicClientTransactionManager.

commit

public java.lang.Object[] commit()
                          throws java.lang.Exception

Invoke the configured service with the service invocation parameters, security credentials, and attachments held in jaxrpcDynamicClientTransactionManager.

Return an Object[] where each entry is a service response. If the service response includes attachments, the entry is an org.osesb.eaimessage.EAIObjectMessageWithAttachments Object. If the service response does not include attachments, the entry is an org.osesb.eaimessage.EAIObjectMessage Object.

If the target service returns null or Void, the corresponding entry in Object[] will be null.

Throws:

java.lang.Exception

rollback

public void rollback()

Clear the List of TransactionBufferEntry(s) for the JAXRPCDynamicClientTransactionManager.

getJAXRPCClientConfiguration

public JAXRPCClientConfiguration getJAXRPCClientConfiguration()

Return the JAXRPCClientConfiguration for this JAXRPCDynamicClient.

Returns:

the JAXRPCClientConfiguration for this JAXRPCDynamicClient.

isVoidReturnType

protected boolean isVoidReturnType(javax.xml.rpc.Call call)

Normalize the return from the getReturnType() method of a javax.xml.rpc.Call object. No standard for void void return types.

Returns:

the JAXRPCClientConfiguration for this JAXRPCDynamicClient.

reset

public void reset()

Resets this JAXRPCDynamicClient by setting the Call object to null so that it is re-created the next time invokeService() is called.

main

public static void main(java.lang.String[] args)

Main method for testing.

Parameters:

args - The test data directory.