org.osesb.msgrouting
Class ClientGateway

java.lang.Object
  org.osesb.msgrouting.ClientGateway

public class ClientGateway
extends java.lang.Object

This class is used by application clients to send messages to osESB.

ClientGateway(s) facilitate communication with broker end points such as JMS Destinations and web services. ClientGateway is used to hide messaging infrastructure from client applications. Client applications are not aware of target destinations, the message transport, or how a request is fulfilled. Initiating applications merely send a message, and possibly, receive a response.

Like transport handlers, the ClientGateway is configured with a MessageRouter. In this case, the MessageRouter is used to select the MessagePipeline that sends an outgoing message to a osESB destination end point. Broker destination end-points are exposed by osESB transport handlers as JMS Destinations or web services.

ClientGateway MessageRouter(s) are configured with MessagePipeline(s) that contain any number or types of PipelineStages and one PipelineStage that handles the interaction with a broker end point. We call this osESB transport PipelineStage. For example:

• org.osesb.messagepipeline.builtinstages.JMSClientPipelineStage can be used to send outgoing messages to JMS Destination(s).
• org.osesb.messagepipeline.builtinstages.SOAPClientPipelineStage can be used to send outgoing messages to web service end points.

So, ClientGateway MessagePipeline(s) generally include one Broker transport PipelineStage, possibly with preceeding PipelineStage(s) that manipulate the outgoing message and possibly with post-transport PipelineStage(s) that manipulate osESB response message before it is returned to the application client.

ClientGateway(s) use a MessageRouter to route messages to a org.osesb.messagepipeline.MessagePipeline for processing. The MessageRouter selects the MessagePipeline based on the message's messageType. The MessageRouter uses the <messagetype-to-messagepipeline-map> configuration element of a MessageRouterConfiguration to map message types to MessagePipelines.

See the org.osesb.messagepipeline package.

There are two ways that the message type for an outgoing message is determined:

1. A ClientGateway can be configured with a static messageType. In this case all messages sent from the gateway will be assigned the same message type.
2. If a ClientGateway is not configured with a static message type, then the configured MessageRouter uses a XMLMessageTypeHelper to extract a message type from the XML message.

DefaultXMLMessageTypeHelper is the default XMLMessageTypeHelper class and is constructed with a XMLMessageTypeXPathExpressionListConfiguration. DefaultXMLMessageTypeHelper applies the configured XPath expressions to a XML message until a messageType is determined. DefaultXMLMessageTypeHelper#getMessagetype() returns the messageType as a QName, where the namespaceURI is the XML document namespace (if any) and the localPart is the value for the element or attribute that is given by a XPath expression.

To configure a MessageRouter with a different XMLMessageTypeHelper, create a class that extends AbstractXMLMessageTypeHelper and use the <xmlMessagetypeHelperConfiguration> content model element of the MessageRouterConfiguration.

The ClientGateway sendXXX methods return message IDs from the underlying transport according to the following rules:

• If the content of the resultMessage is received from a JMS provider using a org.osesb.messagepipeline.builtinstages.JMSClientPipelineStage, then JMSClientPipelineStage sets the messageID of the EAIMessage that is returned to the to the JMS Message ID for the JMS Message that was received.
• If the content of the resultMessage is received from a web service using a org.osesb.messagepipeline.builtinstages.SOAPClientPipelineStage_1, then SOAPClientPipelineStage sets the messageID of the EAIMessage that is returned to the <wsa:MessageID> entry in the SOAPHeader of the message that was received.
• If the content of the resultMessage is received from a JMS provider using a org.osesb.messagepipeline.builtinstages.JMSClientPipelineStage, then JMSClientPipelineStage sets the correlationID of the EAIMessage that is returned to the JMS Correlation ID of the received JMS Message.
• If the content of the resultMessage is received from a web service using a org.osesb.messagepipeline.builtinstages.SOAPClientPipelineStage_1, then SOAPClientPipelineStage sets correlationID of the EAIMessage that is returned to the <wsa:RelatesTo> entry in the SOAPHeader of the SOAP message that was received.

In addition, the sendEAIMessage() method sets the messageID of the input EAIMessage to the message ID of the message that was sent to osESB. For JMS transport this is the JMS MessageID of the message that was sent. For SOAP transport this is the <wsa:MessageID> entry in the SOAPHeader of the message that was sent.

For multi-threaded environments or for any situation where an application client needs to send multiple messages to osESB, use a pool of ClientGateway(s) to send messages and possibly receive replies. This approach may eliminate the need for the client to correlate multiple request/reply interactions.

ClientGateway(s)can be pooled. See org.osesb.objectpools.ClientGatewayKeyedPoolFactory.

Since:

Version .9

Field Summary

protected ClientGatewayConfiguration	clientGatewayConfiguration The configuration for this ClientGateway, which includes at least a MessageRouterConfiguration.
protected static org.apache.commons.logging.Log	log The logging implementation for this class.
protected MessageRouter	messageRouter The MessageRouter for this ClientGateway.
protected java.lang.String	thisClassName The full name of this class.

Constructor Summary

ClientGateway(ClientGatewayConfiguration clientGatewayConfiguration)
Create a new instance of ClientGateway

Method Summary

ClientGatewayConfiguration	getClientGatewayConfiguration() Return the configuration for this ClientGateway.
MessageRouter	getMessageRouter() Return the MessageRouter for this ClientGateway.
static void	main(java.lang.String[] args) main() For testing and sandboxing.
EAIMessage	sendEAIMessage(EAIMessage eaiMessage) Send an EAIMessage through a configured MessagePipeline.
EAIMessage	sendEAIMessage(EAIMessage eaiMessage, java.lang.String username, java.lang.String password) Send an EAIMessage through a configured MessagePipeline with optional UsernameToken credentials.
EAIMessage	sendXMLMessage(java.lang.String xmlMessageText) Send a XML message through a configured MessagePipeline.
EAIMessage	sendXMLMessage(java.lang.String xmlMessageText, AttachmentDescriptor[] attachmentDescriptors) Send a XML message and attachments through a configured MessagePipeline.
EAIMessage	sendXMLMessage(java.lang.String xmlMessageText, AttachmentDescriptor[] attachmentDescriptors, java.lang.String username, java.lang.String password) Send a XML message and attachments through a configured MessagePipeline with optional UsernameToken credentials.
EAIMessage	sendXMLMessage(java.lang.String xmlMessageText, java.lang.String username, java.lang.String password) Send a XML message through a configured MessagePipeline with optional UsernameToken credentials.

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.

clientGatewayConfiguration

protected ClientGatewayConfiguration clientGatewayConfiguration

The configuration for this ClientGateway, which includes at least a MessageRouterConfiguration.

messageRouter

protected MessageRouter messageRouter

The MessageRouter for this ClientGateway.

Constructor Detail

ClientGateway

public ClientGateway(ClientGatewayConfiguration clientGatewayConfiguration)
              throws java.lang.Exception

Create a new instance of ClientGateway

Parameters:

clientGatewayConfiguration - The ClientGatewayConfiguration object to use for this gateway.

Throws:

java.lang.Exception - if there are problems instantiating a ClientGateway.

Method Detail

sendXMLMessage

public EAIMessage sendXMLMessage(java.lang.String xmlMessageText)
                          throws PipelineStageException,
                                 java.lang.Exception

Send a XML message through a configured MessagePipeline.

Parameters:

xmlMessageText - The XML text of the message to send.

Returns:

the resultMessage from the MessagePipelineContext of the invoked MessagePipeline returned as a EAIMessage. The MessagePipeline result can be a XML reply, possibly with attachments, a BrokerAcknowledgementMessage XML message, or a BrokerErrorMessage XML message. For asynchronous interactions the return is null.

Throws:

PipelineStageException - A PipelineStageException thrown by a MessagePipeline configured for this gateway, which could mean the message did not reach osESB or there was a problem processing a reply from osESB.

java.lang.Exception - Most likely, this is an Exception thrown by the MessageRouter. For example a messageType could not be extracted from xmlMessageText or a MessagePipeline that is mapped to the messageType is not configured.

sendXMLMessage

public EAIMessage sendXMLMessage(java.lang.String xmlMessageText,
                                 java.lang.String username,
                                 java.lang.String password)
                          throws PipelineStageException,
                                 java.lang.Exception

Send a XML message through a configured MessagePipeline with optional UsernameToken credentials.

Parameters:

xmlMessageText - The XML text of the message to send.

username - The username for the UsernameToken credential.

password - The optional password for the UsernameToken credential.

Returns:

the resultMessage from the MessagePipelineContext of the invoked MessagePipeline returned as a EAIMessage. The MessagePipeline result can be a XML reply, possibly with attachments, a BrokerAcknowledgementMessage XML message, or a BrokerErrorMessage XML message. For asynchronous interactions the return is null.

Throws:

PipelineStageException - A PipelineStageException thrown by a MessagePipeline configured for this gateway, which could mean the message did not reach osESB or there was a problem processing a reply from osESB.

java.lang.Exception - Most likely, this is an Exception thrown by the MessageRouter. For example a messageType could not be extracted from xmlMessageText or a MessagePipeline that is mapped to the messageType is not configured.

sendXMLMessage

public EAIMessage sendXMLMessage(java.lang.String xmlMessageText,
                                 AttachmentDescriptor[] attachmentDescriptors)
                          throws PipelineStageException,
                                 java.lang.Exception

Send a XML message and attachments through a configured MessagePipeline.

Parameters:

xmlMessageText - The XML text of the message to send.

attachmentDescriptors - An array of AttachmentDescriptor(s).

Returns:

the resultMessage from the MessagePipelineContext of the invoked MessagePipeline returned as a EAIMessage. The MessagePipeline result can be a XML reply, possibly with attachments, a BrokerAcknowledgementMessage XML message, or a BrokerErrorMessage XML message. For asynchronous interactions the return is null.

Throws:

PipelineStageException - A PipelineStageException thrown by a MessagePipeline configured for this gateway, which could mean the message did not reach osESB or there was a problem processing a reply from osESB.

java.lang.Exception - Most likely, this is an Exception thrown by the MessageRouter. For example a messageType could not be extracted from xmlMessageText or a MessagePipeline that is mapped to the messageType is not configured.

sendXMLMessage

public EAIMessage sendXMLMessage(java.lang.String xmlMessageText,
                                 AttachmentDescriptor[] attachmentDescriptors,
                                 java.lang.String username,
                                 java.lang.String password)
                          throws PipelineStageException,
                                 java.lang.Exception

Send a XML message and attachments through a configured MessagePipeline with optional UsernameToken credentials.

Parameters:

xmlMessageText - The XML text of the message to send.

attachmentDescriptors - An array of AttachmentDescriptor(s).

username - The username for the UsernameToken credential.

password - The optional password for the UsernameToken credential.

Returns:

the resultMessage from the MessagePipelineContext of the invoked MessagePipeline returned as a EAIMessage. The MessagePipeline result can be a XML reply, possibly with attachments, a BrokerAcknowledgementMessage XML message, or a BrokerErrorMessage XML message. For asynchronous interactions the return is null.

Throws:

PipelineStageException - A PipelineStageException thrown by a MessagePipeline configured for this gateway, which could mean the message did not reach osESB or there was a problem processing a reply from osESB.

java.lang.Exception - Most likely, this is an Exception thrown by the MessageRouter. For example a messageType could not be extracted from xmlMessageText or a MessagePipeline that is mapped to the messageType is not configured.

sendEAIMessage

public EAIMessage sendEAIMessage(EAIMessage eaiMessage)
                          throws PipelineStageException,
                                 java.lang.Exception

Send an EAIMessage through a configured MessagePipeline.

Parameters:

eaiMessage - The EAIMessage to send.

Returns:

the resultMessage from the MessagePipelineContext of the invoked MessagePipeline returned as a EAIMessage. The MessagePipeline result can be a XML reply, possibly with attachments, a BrokerAcknowledgementMessage XML message, or a BrokerErrorMessage XML message. For asynchronous interactions the return is null.

Throws:

PipelineStageException - A PipelineStageException thrown by a MessagePipeline configured for this gateway, which could mean the message did not reach osESB or there was a problem processing a reply from osESB.

java.lang.Exception - Most likely, this is an Exception thrown by the MessageRouter. For example a messageType could not be extracted from xmlMessageText or a MessagePipeline that is mapped to the messageType is not configured.

sendEAIMessage

public EAIMessage sendEAIMessage(EAIMessage eaiMessage,
                                 java.lang.String username,
                                 java.lang.String password)
                          throws PipelineStageException,
                                 java.lang.Exception

Send an EAIMessage through a configured MessagePipeline with optional UsernameToken credentials.

Parameters:

eaiMessage - The EAIMessage to send.

username - The username for the UsernameToken credential.

password - The optional password for the UsernameToken credential.

Returns:

the resultMessage from the MessagePipelineContext of the invoked MessagePipeline returned as a EAIMessage. The MessagePipeline result can be a XML reply, possibly with attachments, a BrokerAcknowledgementMessage XML message, or a BrokerErrorMessage XML message. For asynchronous interactions the return is null.

Throws:

PipelineStageException - A PipelineStageException thrown by a MessagePipeline configured for this gateway, which could mean the message did not reach osESB or there was a problem processing a reply from osESB.

java.lang.Exception - Most likely, this is an Exception thrown by the MessageRouter. For example a messageType could not be extracted from xmlMessageText or a MessagePipeline that is mapped to the messageType is not configured.

getClientGatewayConfiguration

public ClientGatewayConfiguration getClientGatewayConfiguration()

Return the configuration for this ClientGateway.

Returns:

the configuration for this ClientGateway.

getMessageRouter

public MessageRouter getMessageRouter()

Return the MessageRouter for this ClientGateway.

Returns:

the MessageRouter for this ClientGateway.

main

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

main() For testing and sandboxing.

Parameters:

args - commandline arguments