org.osesb.transporthandlers.soap.ejb20
Class SOAPXMLMessageTransportHandlerBean

java.lang.Object
  org.osesb.transporthandlers.TransportHandlerBase
      org.osesb.transporthandlers.soap.ejb20.SOAPXMLMessageTransportHandlerBean

All Implemented Interfaces:

java.io.Serializable, javax.ejb.EnterpriseBean, javax.ejb.SessionBean

Direct Known Subclasses:

ProcessLoanApplicationBusinessServiceBean

public class SOAPXMLMessageTransportHandlerBean
extends TransportHandlerBase
implements javax.ejb.SessionBean

Out of the box, osESB supports document style interactions where service consumers invoke services using XML messages.

Transport handlers are entry points for messages sent to osESB. SOAPXMLMessageTransportHandlerBean is a transport handler that extends TransportHandlerBase for processing messages sent over SOAP.

SOAPXMLMessageTransportHandlerBean is a SessionBean configured as a SOAP end point that exposes two methods, which both take XML text as the only parameter:

• receiveAsynchronousMessage() processes the incoming message and does not return a SOAP response to the SOAP client that invoked the service. However, replies can still be sent to SOAP end-points defined by the ws-addressing <wsa:ReplyTo> or <wsa:FaultTo> tags in the incoming SOAPHeader.
• receiveSynchronousMessage() processes the incoming message and always sends a reply to the SOAP client that invoked the service. In this case, if message processing does not produce a result, then depending on the setting for the 'echoMessageAsAcknowledgement' environment property either a BrokerAcknowledgementMessage or the original XML message is returned to the SOAP client that invoked the service.

SOAPXMLMessageTransportHandlerBean supports:

• Attachments for requests and replies. See getSOAPRequestAttachments().
• ws-addressing SOAPHeader entries for requests and replies. See getWSAddressingSOAPHeaderEntries().
• ws-security SOAPHeader entries for requests and replies. See getWSSecuritySOAPHeaderEntries().

The jax-rpc handlers that can be configured to enable these options are:

• org.osesb.connectors.jaxrpc.attachments.JAXRPCServerAttachmentHandler is a jax-rpc, server-side handler with a handleRequest() method that detaches attachments from the incoming SOAPMessage and makes the attachments available to the service end point and a handleResponse() method that puts attachments in the response SOAPMessage that were added by the service end point.
• org.osesb.connectors.jaxrpc.addressing.JAXRPCServerAddressingHandler is a jax-rpc, server-side handler with handleRequest() and handleResponse() methods for processes ws-addressing entries in the SOAPHeader.
• org.osesb.connectors.jaxrpc.security.JAXRPCServerSecurityHandler is a jax-rpc, server-side handler with a handleRequest() method that process a security header entry in the SOAPHeader.

The standard Broker transport handlers expect XML messages, possibly with attachments. The standard Broker transport handlers are:

SOAPXMLMessageTransportHandlerBean is configured to receive messages from a SOAP end point exposed via WSDL. Application clients send messages to the configured SOAP end point using any SOAP client that can consume WSDL. The osESB framework includes the following SOAP-related, client components:

• org.osesb.msgrouting.ClientGateway can be configured with a org.osesb.messagepipeline.builtinstages.SOAPClientPipelineStage that uses pooled or non-pooled jax-rpc clients to send messages to osESB. This approach has the advantage that messages can be sent to different transport handlers based on the message type sent by the application client.
• org.osesb.messagepipeline.builtinstages.SOAPClientPipelineStage can be configured as part of a MessagePipline, which is deployed in osESB.
• A SOAP client, such as JAXRPCDynamicSendMessageClient, in the org.osesb.connectors.jaxrpc package.

The standard Broker transport handlers expect XML messages, possibly with attachments. The standard Broker transport handlers are:

• org.osesb.transporthandlers.jms.mdb.JMSXMLMessageTransportHandlerMDB is a MessageDrivenBean that is configured to listen on a JMS Queue or Topic. The onMessage() method expects XML messages without attachments as JMS TextMessage(s) or JMS ObjectMessage(s) and XML messages with attachments as JMS MapMessages with the following keys: 1) 'xmlMessage' maps to a String that is the XML message, and 2) there are 'attachmentN' keys that map to byte[](s), which contain attachment data. So, if there are 5 attachments, then there are 5 'attachmentN' keys (where N is 0-4).
• org.osesb.transporthandlers.soap.ejb.SOAPXMLMessageTransportHandlerBean (this class) is a SessionBean configured as a SOAP end point that exposes two methods, which both take XML text as the only parameter. receiveAsynchronousMessage() processes the incoming message and does not return a SOAP response to the SOAP client that invoked the service. However, replies can still be sent to SOAP end-points defined by the ws-addressing <wsa:ReplyTo> or <wsa:ReplyTo> tags in the incoming SOAPHeader. receiveSynchronousMessage() processes the incoming message and always sends a reply to the SOAP client that invoked the service. In this case, if message processing does not produce a result, then depending on the setting for the 'echoMessageAsAcknowledgement' environment property either a BrokerAcknowledgementMessage or the original XML message is returned to the SOAP client that invoked the service.

  Attachments are processed by server-side attachment handlers such as org.osesb.connectors.jaxrpc.attachments.JAXRPCServerAttachmentHandler.

  SOAPXMLMessageTransportHandlerBean can be configured as a document-literal or rpc-encoded SOAP end point because document-based web services, as a paradigm, are orthogonal to the formatting and the representation of the SOAP message on the wire. This means that the choice of the formatting defined in the WSDL for the transport handler end point is transparent to SOAP clients. For example, the SOAP clients in the org.osesb.connectors.jaxrpc; behave identically for document-literal and rpc-encoded SOAP end points.

• org.osesb.transporthandlers.soapoverjms.mdb.SOAPOverJMSXMLMessageTransportHandlerMDB is a MessageDrivenBean that is configured to listen on a JMS Queue or Topic for SOAP messages with XML payloads. The onMessage() method expects SOAP messages without attachments as JMS TextMessage(s) or JMS ObjectMessage(s) where the content of JMS Messages is the SOAP envelope. SOAP over JMS transport handlers expect XML messages with attachments as JMS MapMessages with the following keys: 1) 'requestSOAPEnvelope' maps to a String that is the SOAPEnvelope, and 2) there are 'attachmentN' keys that map to byte[](s), which contain attachment data. So, if there are 5 attachments, then there are 5 'attachmentN' keys (where N is 0-4).

SOAPXMLMessageTransportHandlerBean processes messages as follows:

1. Retrieve the message ID from the <wsa:MessageID> entry in the SOAPHeader of the incoming message, if any.
2. Retrieve attachments sent with the SOAPMessage, if any.
3. Retrieve security credentials, if any, from ws-security SOAPHeader entries as a WSSSecurityProfile instance. ws-security SOAPHeader entries are extracted by the configured JAXRPCServerSecurityHandler.
4. Construct an EAIMessage for routing to a MessagePipeline as a EAIXMLMessage or a EAIXMLMessageWithAttachments.
5. If configured with an environment property that specifies the message type for all messages arriving at this transport handler, then set the message type in the EAIMessage. Otherwise, the message type is extracted from the XML message by MessageRouter.
6. Obtain a MessageRouter from the configured router pool. The configuration file for the MessageRouter pool is specified in object-pool-configurations.properties, which is packaged in osesb-configurations.jar and deployed with the EAR for this EJB.
7. Invoke MessageRouter#routeEAIMessage(), which routes the EAIMessage to a org.osesb.messagepipeline.MessagePipeline for processing.
8. If no error occurs, send a reply to the end point specified by the ws-addressing <wsa:ReplyTo> SOAPHeader entry, if any.

How replies and faults are returned from SOAP transport handlers is determined by a combination of factors, including the receiveXXX() method that is invoked, the ws-addressing <wsa:ReplyTo> and <wsa:FaultTo> tags in the SOAPHeader of the incoming message, whether or not MessageRouter#routeEAIMessage() returns a result, and the setting of the 'onExceptionSendBrokerErrorMessage' environment property. The rules for sending replies from SOAP transport handlers are as follows:

• The return from receiveAsynchronousMessage() is void, so a reply is not sent to the SOAP client.
• If an Exception does not occur, receiveSynchronousMessage() returns XML possibly with attachments. If message processing does not produce a result, then depending on the setting for the 'echoMessageAsAcknowledgement' environment property either a BrokerAcknowledgementMessage or the original XML message is returned to the SOAP client that invoked the service.
• If the SOAPHeader of the incoming message includes a ws-addressing <wsa:ReplyTo> entry, then unless an Exception occurs, a reply is always sent to the specified end-point irrespective of the method that was invoked. So, if message processing does not produce a result, then depending on the setting for the 'echoMessageAsAcknowledgement' environment property either a BrokerAcknowledgementMessage or the original XML message is sent to the end-point specified by <wsa:ReplyTo>. If message processing produces a result, then the result is sent to the end-point specified by <wsa:ReplyTo>, even if receiveAsynchronousMessage() was invoked. Note that if processing produces a result and receiveSynchronousMessage() was invoked and if <wsa:ReplyTo> is set in the SOAPHeader then a response is returned to the SOAP client and a reply is sent to the end point specified by <wsa:ReplyTo>.

The rules for sending faults from SOAP transport handlers are as follows:

• If an error occurs during message processing, the environment property 'onExceptionSendBrokerErrorMessage' determines whether a SOAPFault or a org.osesb.msgrouting.BrokerErrorMessage is returned from receiveSynchronousMessage(). Default is false, so by default SoapFaults are returned to SOAP clients that invoke receiveSynchronousMessage().
• If an error occurs during message processing and receiveASynchronousMessage() was invoked, then a SOAPFault is returned to the client irrespective of any other settings.
• If an error occurs during message processing and the ws-addressing <wsa:FaultTo> entry in the SOAPHeader of the incoming message is set, then either a SoapFault or a BrokerErrorMessage is sent to the end point specified by <wsa:FaultTo>, depending on the setting of the 'onExceptionSendBrokerErrorMessage' environment property.

Since:

Version .9

See Also:

Serialized Form

Field Summary

protected JAXRPCWSAddressingConfiguration	jaxrpcWSAddressingConfiguration Initialized and populated by receiveMessage() this is the JAXRPCWSAddressingConfiguration, which encapsulates the ws-addressing SOAPHeader entries in the incoming SOAPMessage.
protected java.lang.String	messageFactoryClassName From the environment, the name of the javax.xml.soap.MessageFactory class that is used to create SOAPMessages.
protected boolean	onExceptionSendBrokerErrorMessage From the 'onExceptionSendBrokerErrorMessage' environment property, which determines whether a SOAPFault or a org.osesb.msgrouting.BrokerErrorMessage is returned from receiveSynchronousMessage() when an error occurs.
protected boolean	propagateSecurityCredentials From the 'propagateSecurityCredentials' environment property.
protected javax.xml.namespace.QName	requestMessageType Initialized and populated by receiveMessage() this is messageType (QName) of the incoming XML message as determined by the MessageRouter when routeEAIMessage() is invoked.
protected WSSSecurityProfile	securityProfile Initialized and populated by receiveMessage() this is the WSSSecurityProfile, which encapsulates the ws-security SOAPHeader entries in the incoming SOAPMessage.
protected java.lang.String	serviceFactoryClassName From the environment, the name of the javax.xml.rpc.ServiceFactory class that is used to invoke Web Services, such as those specified by <wsa:ReplyTo> SOAPHeader entries.
protected javax.ejb.SessionContext	sessionContext Our SessionContext.
protected java.lang.String	soapConnectionFactoryClassName From the javax.xml.soap.SOAPConnectionFactory environment property, the name of the javax.xml.soap.SOAPConnectionFactory class.
protected java.lang.String	soapFactoryClassName From the environment, the name of the javax.xml.soap.SOAPFactory class that is used to create SOAPMessages.

Fields inherited from class org.osesb.transporthandlers.TransportHandlerBase

debugFlag, echoMessageAsAcknowledgement, log, messageRouterPoolInstance, transportHandlerMessageType, transportHandlerName, verbose

Constructor Summary

SOAPXMLMessageTransportHandlerBean()

Method Summary

BrokerAcknowledgementMessage	constructBrokerAcknowledgementMessage(java.lang.String message, javax.xml.namespace.QName relatesToMessageType, java.lang.String relatesToMessageID) Constructs a BrokerAcknowledgementMessage that can be returned to a SOAP client or sent to the destination specified by a ws-addressing <wsa:ReplyTo> entry in the SOAPHeader of an incoming SOAPMessage.
BrokerErrorMessage	constructBrokerErrorMessage(java.lang.String message, javax.xml.namespace.QName relatesToMessageType, java.lang.String relatesToMessageID) Constructs a BrokerErrorMessage that can be returned to a SOAP client or sent to the destination specified by a ws-addressing <wsa:FaultTo> entry in the SOAPHeader of an incoming SOAPMessage.
void	ejbActivate()
void	ejbCreate() ejbCreate().
void	ejbPassivate()
void	ejbRemove() ejbRemove()
protected EAIXMLMessageWithAttachments	getMessagePipelineResult(EAIMessage messagePipelineResult) Returns a EAIXMLMessageWithAttachments for a given MessagePipeline result.
javax.ejb.SessionContext	getSessionContext()
java.util.List	getSOAPRequestAttachments() Retrieves attachments sent with the request SOAPMessage, if any.
JAXRPCWSAddressingConfiguration	getWSAddressingSOAPHeaderEntries() Retrieves the JAXRPCWSAddressingConfiguration, which encapsulates ws-addressing SOAPHeader entries.
WSSSecurityProfile	getWSSecuritySOAPHeaderEntries() Retrieves the WSSSecurityProfile, which encapsulates ws-security SOAPHeader entries.
protected void	logMessage(java.lang.String messageID, java.lang.String xmlMessageText, int numberOfAttachments) Log a message.
void	receiveAsynchronousMessage(java.lang.String xmlMessageText) Invoke receiveMessage() to process an asynchronous XML message transported over SOAP, possibly with attachments, as follows: The return from receiveAsynchronousMessage() is void, so a reply is not sent to the SOAP client. If the SOAPHeader of the incoming message includes a ws-addressing <wsa:ReplyTo> entry, then unless an Exception occurs, the result of MessagePipeline processing is sent to the specified end-point.
protected EAIMessage	receiveMessage(java.lang.String xmlMessageText) Process a XML message transported over SOAP, possibly with attachments, as follows: Retrieve the message ID from the <wsa:MessageID> entry in the SOAPHeader of the incoming message, if any. Retrieve attachments sent with the SOAPMessage, if any. Retrieve security credentials, if any, from ws-security SOAPHeader entries as a WSSSecurityProfile instance.
java.lang.String	receiveSynchronousMessage(java.lang.String xmlMessageText) Invoke receiveMessage() to process an Synchronous XML message transported over SOAP, possibly with attachments, as follows: Unless an Exception occurs, the result of MessagePipeline processing is returned to the client.
protected java.lang.String	sendReply(java.lang.String originatingXMLMessage, EAIMessage messagePipelineResult, java.lang.Throwable receiveMessageException) Send replies, including SOAP faults, to the end points specified by the <wsa:ReplyTo> or <wsa:FaultTo> tags in the SOAPHeader of the incoming message.
protected java.lang.String	sendReplyUsingJAXRPCClient(java.lang.String originatingXMLMessage, EAIMessage messagePipelineResult, java.lang.Throwable receiveMessageException) Use a org.osesb.connectors.jaxrpc.JAXRPCDynamicSendMessageClient to send replies, including SOAP faults, to the end points specified by the <wsa:ReplyTo> or <wsa:FaultTo> tags in the SOAPHeader of the incoming message.
protected java.lang.String	sendReplyUsingSOAPConnection(java.lang.String originatingXMLMessage, EAIMessage messagePipelineResult, java.lang.Throwable receiveMessageException) Use a javax.xml.soap.SOAPConnection to send replies, including SOAP faults, to the end points specified by the <wsa:ReplyTo> or <wsa:FaultTo> tags in the SOAPHeader of the incoming message.
void	setSessionContext(javax.ejb.SessionContext sessionContext)
void	testWSAddressingReplyReceiver(java.lang.String xmlMessageText) testWSAddressingReplyReceiver() is a test method, not an operational method.

Methods inherited from class java.lang.Object

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

Field Detail

sessionContext

protected javax.ejb.SessionContext sessionContext

Our SessionContext.

jaxrpcWSAddressingConfiguration

protected JAXRPCWSAddressingConfiguration jaxrpcWSAddressingConfiguration

Initialized and populated by receiveMessage() this is the JAXRPCWSAddressingConfiguration, which encapsulates the ws-addressing SOAPHeader entries in the incoming SOAPMessage.

Saved as an instance variable because it can be retrieved only once per thread from the ThreadLocal variable in the configured JAXRPCServerAddressingHandler.

securityProfile

protected WSSSecurityProfile securityProfile

Initialized and populated by receiveMessage() this is the WSSSecurityProfile, which encapsulates the ws-security SOAPHeader entries in the incoming SOAPMessage.

Saved as an instance variable because it can be retrieved only once per thread from the ThreadLocal variable in the configured JAXRPCServerAddressingHandler.

requestMessageType

protected javax.xml.namespace.QName requestMessageType

Initialized and populated by receiveMessage() this is messageType (QName) of the incoming XML message as determined by the MessageRouter when routeEAIMessage() is invoked.

Saved as an instance variable because MessageRouter#routeEAIMessage() is invoked by receiveMessage() and the messageType assigned to the incoming message by MessageRouter can only be accessed after that call, but the messageType is needed by other methods.

serviceFactoryClassName

protected java.lang.String serviceFactoryClassName

From the environment, the name of the javax.xml.rpc.ServiceFactory class that is used to invoke Web Services, such as those specified by <wsa:ReplyTo> SOAPHeader entries. Set the ServiceFactory entry when using a SOAP engine that is not native to the container, like Axis in Weblogic.

See Also:

ejbCreate()

soapFactoryClassName

protected java.lang.String soapFactoryClassName

From the environment, the name of the javax.xml.soap.SOAPFactory class that is used to create SOAPMessages. Set the MessageFactory entry when using a SOAP engine that is not native to the container, like Axis in Weblogic.

See Also:

ejbCreate()

messageFactoryClassName

protected java.lang.String messageFactoryClassName

From the environment, the name of the javax.xml.soap.MessageFactory class that is used to create SOAPMessages. Set the MessageFactory entry when using a SOAP engine that is not native to the container, like Axis in Weblogic.

See Also:

ejbCreate()

soapConnectionFactoryClassName

protected java.lang.String soapConnectionFactoryClassName

From the javax.xml.soap.SOAPConnectionFactory environment property, the name of the javax.xml.soap.SOAPConnectionFactory class. Set the SOAPConnectionFactory entry when using a SOAP engine that is not native to the container, like Axis in Weblogic.

See Also:

ejbCreate()

onExceptionSendBrokerErrorMessage

protected boolean onExceptionSendBrokerErrorMessage

From the 'onExceptionSendBrokerErrorMessage' environment property, which determines whether a SOAPFault or a org.osesb.msgrouting.BrokerErrorMessage is returned from receiveSynchronousMessage() when an error occurs. Default is false, so by default SoapFaults are returned to SOAP clients that invoke receiveSynchronousMessage().

Default value is false.

See Also:

ejbCreate()

propagateSecurityCredentials

protected boolean propagateSecurityCredentials

From the 'propagateSecurityCredentials' environment property. If true, then:

• The ws-security entries (if any) in the SOAPHeader of the incoming message are propagated when replies are sent to the end point specified by the <wsa:ReplyTo> entry in the SOAPHeader of the incoming message.
• The ws-security entries (if any) in the SOAPHeader of the incoming message are propagated when BrokerErrorMessages are sent to the end point specified by the <wsa:FaultTo> entry in the SOAPHeader of the incoming message.

Default value is true.

See Also:

ejbCreate()

Constructor Detail

SOAPXMLMessageTransportHandlerBean

public SOAPXMLMessageTransportHandlerBean()

Method Detail

receiveAsynchronousMessage

public void receiveAsynchronousMessage(java.lang.String xmlMessageText)
                                throws java.lang.Exception

Invoke receiveMessage() to process an asynchronous XML message transported over SOAP, possibly with attachments, as follows:

• The return from receiveAsynchronousMessage() is void, so a reply is not sent to the SOAP client.
• If the SOAPHeader of the incoming message includes a ws-addressing <wsa:ReplyTo> entry, then unless an Exception occurs, the result of MessagePipeline processing is sent to the specified end-point. The result of MessagePipeline processing must be XML or XML with attachments. If message processing does not produce a result, then depending on the setting for the 'echoMessageAsAcknowledgement' environment property either a BrokerAcknowledgementMessage or the original XML message is sent to the end-point specified by <wsa:ReplyTo>.
• If an error occurs during message processing a SOAPFault is returned to the client irrespective of any other settings.
• If an error occurs during message processing and the ws-addressing <wsa:FaultTo> entry in the SOAPHeader of the incoming message is set, then either a SoapFault or a BrokerErrorMessage is sent to the end point specified by <wsa:FaultTo>, depending on the setting of the 'onExceptionSendBrokerErrorMessage' environment property.

Parameters:

xmlMessageText - The received XML message.

Throws:

java.lang.Exception - if an error occurs during message processing.

receiveSynchronousMessage

public java.lang.String receiveSynchronousMessage(java.lang.String xmlMessageText)
                                           throws java.lang.Exception

Invoke receiveMessage() to process an Synchronous XML message transported over SOAP, possibly with attachments, as follows:

• Unless an Exception occurs, the result of MessagePipeline processing is returned to the client. The result of MessagePipeline processing must be XML or XML with attachments. result attachments are added to the reply SOAPMessage by the configured JAXRPCServerAttachmentHandler.
• If an Exception does not occur and if MessagePipeline processing does not produce a result, then depending on the setting for the 'echoMessageAsAcknowledgement' environment property either a BrokerAcknowledgementMessage or the original XML message is returned to the client.
• If the SOAPHeader of the incoming message includes a ws-addressing <wsa:ReplyTo> entry, then unless an Exception occurs, the result of MessagePipeline processing is sent to the specified end-point. The result of MessagePipeline processing must be XML or XML with attachments. If message processing does not produce a result, then depending on the setting for the 'echoMessageAsAcknowledgement' environment property either a BrokerAcknowledgementMessage or the original XML message is sent to the end-point specified by <wsa:ReplyTo>.
• If an error occurs during message processing, the environment property 'onExceptionSendBrokerErrorMessage' determines whether a SOAPFault or a org.osesb.msgrouting.BrokerErrorMessage is returned to the client. Default is false, so by default SoapFaults are returned to SOAP clients that invoke receiveSynchronousMessage().
• If an error occurs during message processing and the ws-addressing <wsa:FaultTo> entry in the SOAPHeader of the incoming message is set, then either a SoapFault or a BrokerErrorMessage is sent to the end point specified by <wsa:FaultTo>, depending on the setting of the 'onExceptionSendBrokerErrorMessage' environment property.

Parameters:

xmlMessageText - The received XML message.

Returns:

the XML reply

Throws:

java.lang.Exception - if an error occurs during message processing.

testWSAddressingReplyReceiver

public void testWSAddressingReplyReceiver(java.lang.String xmlMessageText)

testWSAddressingReplyReceiver() is a test method, not an operational method. It is included in SOAPXMLMessageTransportHandlerBean as a convenience for testing the sendRplyXXX methods, which send replies to EndpointReferences identified by <wsa:ReplyTo> and/or <wsa:FaultTo> entries in the SOAPHeader of the incoming message.

Parameters:

xmlMessageText - The received XML message.

receiveMessage

protected EAIMessage receiveMessage(java.lang.String xmlMessageText)
                             throws java.lang.Exception

Process a XML message transported over SOAP, possibly with attachments, as follows:

1. Retrieve the message ID from the <wsa:MessageID> entry in the SOAPHeader of the incoming message, if any.
2. Retrieve attachments sent with the SOAPMessage, if any.
3. Retrieve security credentials, if any, from ws-security SOAPHeader entries as a WSSSecurityProfile instance. ws-security SOAPHeader entries are extracted by the configured JAXRPCServerSecurityHandler.
4. Construct an EAIMessage for routing to a MessagePipeline as a EAIXMLMessage or a EAIXMLMessageWithAttachments. The XML portion of the message carried by the xmlMessageText parameter. Attachments are extracted from the incoming SOAPMessage by the configured JAXRPCServerAttachmentHandler.
5. If configured with an environment property that specifies the message type for all messages arriving at this transport handler, then set the message type in the EAIMessage. Otherwise, the message type is extracted from the XML message by MessageRouter.
6. Obtain a MessageRouter from the configured router pool. The configuration file for the MessageRouter pool is specified in object-pool-configurations.properties, which is packaged in osesb-configurations.jar and deployed with the EAR for this EJB.
7. Invoke MessageRouter#routeEAIMessage(), which routes the EAIMessage to a org.osesb.messagepipeline.MessagePipeline for processing.
8. If no error occurs, send a reply to the end point specified by the ws-addressing <wsa:ReplyTo> SOAPHeader entry, if any.
9. If an error occurs, send a reply to the end point specified by the ws-addressing <wsa:FaultTo> SOAPHeader entry, if any.
10. Return the result of MessagePipeline processing, if any.

Parameters:

xmlMessageText - The received XML message.

Returns:

the result of MessagePipeline processing as an EAIMessage.

Throws:

java.lang.Exception - if an error occurs during message processing.

sendReply

protected java.lang.String sendReply(java.lang.String originatingXMLMessage,
                                     EAIMessage messagePipelineResult,
                                     java.lang.Throwable receiveMessageException)
                              throws java.lang.Exception

Send replies, including SOAP faults, to the end points specified by the <wsa:ReplyTo> or <wsa:FaultTo> tags in the SOAPHeader of the incoming message.

How replies and faults are returned from SOAP transport handlers is determined by a combination of factors, including the receiveXXX() method that is invoked, the ws-addressing <wsa:ReplyTo> and <wsa:FaultTo> tags in the SOAPHeader of the incoming message, whether or not MessageRouter#routeEAIMessage() returns a result, and the setting of the 'onExceptionSendBrokerErrorMessage' environment property. The rules for sending replies from SOAP transport handlers are as follows:

• If the <wsa:ReplyTo> SOAPHeader entry is set and if the MessagePipeline result is not null, then a reply is sent to the end point specified by <wsa:ReplyTo>. Note that the MessagePipeline result must be a EAIXMLMessage or a EAIXMLMessageWithAttachments.
• If the <wsa:ReplyTo> SOAPHeader entry is set and if the MessagePipeline result is null, then a BrokerAcknowledgement Message is sent to the end point specified by <wsa:ReplyTo>.
• If an error occured during message processing and if the <wsa:FaultTo> SOAPHeader entry of the incoming message is set, then the environment property 'onExceptionSendBrokerErrorMessage' determines whether a SOAPFault or a org.osesb.msgrouting.BrokerErrorMessage is sent to the end point specified by <wsa:FaultTo>. If an error occurred during message processing then the 'receiveMessageException' is not null.
• Note that BrokerErrorMessage and/or SOAPFaults are never returned to <wsa:ReplyTo>, they are only returned to <wsa:FaultTo>.

There are two ways to construct and send a message to a <wsa:ReplyTo> or a <wsa:FaultTo> end point, depending on the entries in the <wsa:MetaData> tag of the <wsa:ReplyTo> or <wsa:FaultTo> EndpointReferences. The approaches are implemented by seperate methods, namely sendReplyUsingJAXRPCClient() and sendReplyUsingSOAPConnection().

1. sendReplyUsingJAXRPCClient() uses the <MetaData> tag of the destination EndpointReference to carry JAXRPCConfiguration, which is used to construct a JAXRPCDynamicClient to send the reply. The problem with this approach is that JAXRPCDynamicClient sets properties on the jax-rpc Call object and some SOAP engines, like WLS 8.1.x, do not support programmer-defined Call object properties. So in order to use this approach in WLS 8.1.x, Axis has to be configured as the SOAP client and this involves the adding Axis jars to the front of the class path that WLS is loaded with. This effects all applications in that server instance and is unacceptable solution for WLS 8.1.x. The advantages to this approach are 1) the WSDL of the target end point is used to send the reply, 2) JAXRPCDynamicClient(s) can be pooled and 3) the jax-rpc client pool configurations can include jax-rpc handlers.
2. sendReplyUsingSOAPConnection() uses the <operationName> and <targetNamespace> elements in the <wsa:MetaData> tag of the destination EndpointReference to construct the reply SOAPMessage using rpc-style invocation. Then a SOAPConnectionFactory is used to create a SOAPConnection and invoke it's call() method passing the <wsa:Address> and the reply SOAPMessage. The advantage to this approach is that it does not require any special features and should be universally supported by SOAP engines.

Parameters:

originatingXMLMessage - The XML message for which a reply is being sent.

messagePipelineResult - The result, if any, from the target MessagePipeline that will be sent as the reply.

receiveMessageException - An Exception thrown by the receiveMessage method, if any.

Returns:

the Message ID of the message sent to the end points specified by <wsa:ReplyTo> or <wsa:FaultTo>.

Throws:

java.lang.Exception - if there is a problem sending the reply.

sendReplyUsingJAXRPCClient

protected java.lang.String sendReplyUsingJAXRPCClient(java.lang.String originatingXMLMessage,
                                                      EAIMessage messagePipelineResult,
                                                      java.lang.Throwable receiveMessageException)
                                               throws java.lang.Exception

Use a org.osesb.connectors.jaxrpc.JAXRPCDynamicSendMessageClient to send replies, including SOAP faults, to the end points specified by the <wsa:ReplyTo> or <wsa:FaultTo> tags in the SOAPHeader of the incoming message.

How replies and faults are returned from SOAP transport handlers is determined by a combination of factors, including the receiveXXX() method that is invoked, the ws-addressing <wsa:ReplyTo> and <wsa:FaultTo> tags in the SOAPHeader of the incoming message, whether or not MessageRouter#routeEAIMessage() returns a result, and the setting of the 'onExceptionSendBrokerErrorMessage' environment property. The rules for sending replies from SOAP transport handlers are as follows:

• If the <wsa:ReplyTo> SOAPHeader entry is set and if the MessagePipeline result is not null, then a reply is sent to the end point specified by <wsa:ReplyTo>. Note that the MessagePipeline result must be a EAIXMLMessage or a EAIXMLMessageWithAttachments.
• If the <wsa:ReplyTo> SOAPHeader entry is set and if the MessagePipeline result is null, then a BrokerAcknowledgement Message is sent to the end point specified by <wsa:ReplyTo>.
• If an error occured during message processing and if the <wsa:FaultTo> SOAPHeader entry of the incoming message is set, then the environment property 'onExceptionSendBrokerErrorMessage' determines whether a SOAPFault or a org.osesb.msgrouting.BrokerErrorMessage is sent to the end point specified by <wsa:FaultTo>. If an error occurred during message processing then the 'receiveMessageException' is not null.
• Note that BrokerErrorMessage and/or SOAPFaults are never returned to <wsa:ReplyTo>, they are only returned to <wsa:FaultTo>.

Parameters:

originatingXMLMessage - The XML message for which a reply is being sent.

messagePipelineResult - The result, if any, from the target MessagePipeline that will be sent as the reply.

receiveMessageException - An Exception thrown by the receiveMessage method, if any.

Returns:

the Message ID of the message sent to the end points specified by <wsa:ReplyTo> or <wsa:FaultTo>.

Throws:

java.lang.Exception - if there is a problem sending the reply.

sendReplyUsingSOAPConnection

protected java.lang.String sendReplyUsingSOAPConnection(java.lang.String originatingXMLMessage,
                                                        EAIMessage messagePipelineResult,
                                                        java.lang.Throwable receiveMessageException)
                                                 throws java.lang.Exception

Use a javax.xml.soap.SOAPConnection to send replies, including SOAP faults, to the end points specified by the <wsa:ReplyTo> or <wsa:FaultTo> tags in the SOAPHeader of the incoming message.

How replies and faults are returned from SOAP transport handlers is determined by a combination of factors, including the receiveXXX() method that is invoked, the ws-addressing <wsa:ReplyTo> and <wsa:FaultTo> tags in the SOAPHeader of the incoming message, whether or not MessageRouter#routeEAIMessage() returns a result, and the setting of the 'onExceptionSendBrokerErrorMessage' environment property. The rules for sending replies from SOAP transport handlers are as follows:

• If the <wsa:ReplyTo> SOAPHeader entry is set and if the MessagePipeline result is not null, then a reply is sent to the end point specified by <wsa:ReplyTo>. Note that the MessagePipeline result must be a EAIXMLMessage or a EAIXMLMessageWithAttachments.
• If the <wsa:ReplyTo> SOAPHeader entry is set and if the MessagePipeline result is null, then a BrokerAcknowledgement Message is sent to the end point specified by <wsa:ReplyTo>.
• If an error occured during message processing and if the <wsa:FaultTo> SOAPHeader entry of the incoming message is set, then the environment property 'onExceptionSendBrokerErrorMessage' determines whether a SOAPFault or a org.osesb.msgrouting.BrokerErrorMessage is sent to the end point specified by <wsa:FaultTo>. If an error occurred during message processing then the 'receiveMessageException' is not null.
• Note that BrokerErrorMessage and/or SOAPFaults are never returned to <wsa:ReplyTo>, they are only returned to <wsa:FaultTo>.

Parameters:

originatingXMLMessage - The XML message for which a reply is being sent.

messagePipelineResult - The result, if any, from the target MessagePipeline that will be sent as the reply.

receiveMessageException - An Exception thrown by the receiveMessage method, if any.

Returns:

the Message ID of the message sent to the end points specified by <wsa:ReplyTo> or <wsa:FaultTo>.

Throws:

java.lang.Exception - if there is a problem sending the reply.

getMessagePipelineResult

protected EAIXMLMessageWithAttachments getMessagePipelineResult(EAIMessage messagePipelineResult)
                                                         throws java.lang.Exception

Returns a EAIXMLMessageWithAttachments for a given MessagePipeline result. A MessagePipeline result for this transport handler must be a EAIXMLMessage or a EAIXMLMessageWithAttachments. If the MessagePipeline result is a EAIXMLMessage then this method returns a EAIXMLMessageWithAttachments instance with no attachments.

Parameters:

messagePipelineResult - The result of MessagePipeline processing.

Returns:

A EAIXMLMessageWithAttachments instance, possibly with attachments.

Throws:

java.lang.Exception - If messagePipelineResult is not null and is not a EAIXMLMessage or a EAIXMLMessageWithAttachments or if the XML portion of the messagePipelineResult is empty.

constructBrokerAcknowledgementMessage

public BrokerAcknowledgementMessage constructBrokerAcknowledgementMessage(java.lang.String message,
                                                                          javax.xml.namespace.QName relatesToMessageType,
                                                                          java.lang.String relatesToMessageID)

Constructs a BrokerAcknowledgementMessage that can be returned to a SOAP client or sent to the destination specified by a ws-addressing <wsa:ReplyTo> entry in the SOAPHeader of an incoming SOAPMessage.

If MessagePipeline processing of an incoming message does not produce a result, then:

• receiveSynchronousMessage() returns a BrokerAcknowledgementMessage to the SOAP cleint.
• If the ws-addressing <wsa:ReplyTo> entry in the SOAPHeader is set for an incoming SOAPMessage, then a BrokerAcknowledgementMessage is sent to the specified destination.

Returns:

a BrokerAcknowledgementMessage.

constructBrokerErrorMessage

public BrokerErrorMessage constructBrokerErrorMessage(java.lang.String message,
                                                      javax.xml.namespace.QName relatesToMessageType,
                                                      java.lang.String relatesToMessageID)

Constructs a BrokerErrorMessage that can be returned to a SOAP client or sent to the destination specified by a ws-addressing <wsa:FaultTo> entry in the SOAPHeader of an incoming SOAPMessage.

If an error occurs during MessagePipeline processing of an incoming message, then:

• The environment property 'onExceptionSendBrokerErrorMessage' determines whether a SOAPFault or a org.osesb.msgrouting.BrokerErrorMessage is returned to the client from receiveSynchronousMessage(). Default is false, so by default SoapFaults are returned to SOAP clients that invoke receiveSynchronousMessage().
• If the ws-addressing <wsa:FaultTo> entry in the SOAPHeader of the incoming message is set, then either a SoapFault or a BrokerErrorMessage is sent to the end point specified by <wsa:FaultTo>, depending on the setting of the 'onExceptionSendBrokerErrorMessage' environment property.

Returns:

a BrokerErrorMessage.

getSOAPRequestAttachments

public java.util.List getSOAPRequestAttachments()

Retrieves attachments sent with the request SOAPMessage, if any. Request attachments are retuned as a List of org.osesb.connectors.jaxrpc.attachments.AttachmentDescriptor(s), with one AttachmentDescriptor per attachment. AttachmentDescriptor(s) wrap attachment data and programmer-defined attachment properties. The attachment List was populated by the configured JAXRPCServerAttachmentHandler.

Note that attachments are held by JAXRPCServerAttachmentHandler in a ThreadLocal and can be retrieved from JAXRPCServerAttachmentHandler only once per message flow. Subsequent calls to this method will return null.

Returns:

a List of org.osesb.connectors.jaxrpc.attachments.AttachmentDescriptor(s) that that encapsulates attachments sent with the incoming message.

getWSAddressingSOAPHeaderEntries

public JAXRPCWSAddressingConfiguration getWSAddressingSOAPHeaderEntries()

Retrieves the JAXRPCWSAddressingConfiguration, which encapsulates ws-addressing SOAPHeader entries. JAXRPCWSAddressingConfiguration was populated by the configured JAXRPCServerAddressingHandler.

Note that ws-addressing SOAPHeader entries are held by JAXRPCServerAddressingHandler in a ThreadLocal and can be retrieved from JAXRPCServerAddressingHandler only once per message flow. Subsequent calls to this method will return null.

Returns:

A JAXRPCWSAddressingConfiguration that encapsulates ws-addressing SOAPHeader entries in the incoming message.

getWSSecuritySOAPHeaderEntries

public WSSSecurityProfile getWSSecuritySOAPHeaderEntries()

Retrieves the WSSSecurityProfile, which encapsulates ws-security SOAPHeader entries. WSSSecurityProfile was populated by the configured JAXRPCServerSecurityHandler.

Note that ws-security SOAPHeader entries are held by JAXRPCServerSecurityHandler in a ThreadLocal and can be retrieved from JAXRPCServerSecurityHandler only once per message flow. Subsequent calls to this method will return null.

Returns:

A WSSSecurityProfile that encapsulates ws-security SOAPHeader entries in the incoming message.

logMessage

protected void logMessage(java.lang.String messageID,
                          java.lang.String xmlMessageText,
                          int numberOfAttachments)

Log a message.

Parameters:

messageID - The ID of the incoming message from the <wsa:MessageID> entry in the SOAPHeader, if any.

xmlMessageText - The incoming XML message.

numberOfAttachments - The number of attachments in the incoming message.

ejbCreate

public void ejbCreate()
               throws javax.ejb.CreateException

ejbCreate().

Overrides:

ejbCreate in class TransportHandlerBase

Throws:

javax.ejb.CreateException

ejbRemove

public void ejbRemove()

Description copied from class: TransportHandlerBase

ejbRemove()

Specified by:

ejbRemove in interface javax.ejb.SessionBean

Overrides:

ejbRemove in class TransportHandlerBase

ejbActivate

public void ejbActivate()

Specified by:

ejbActivate in interface javax.ejb.SessionBean

ejbPassivate

public void ejbPassivate()

Specified by:

ejbPassivate in interface javax.ejb.SessionBean

getSessionContext

public javax.ejb.SessionContext getSessionContext()

setSessionContext

public void setSessionContext(javax.ejb.SessionContext sessionContext)

Specified by:

setSessionContext in interface javax.ejb.SessionBean