org.osesb.msgrouting
Class MessageRouter

java.lang.Object
  org.osesb.msgrouting.MessageRouter

public class MessageRouter
extends java.lang.Object

MessageRouter(s) are configured by transport handlers to route incoming messages to org.osesb.messagepipeline.MessagePipeline(s) for processing. Transport handlers are Message Driven and Stateless Session Beans configured to receive messages over JMS and SOAP, respectively. See the 'transport-handler' module. So, transport handlers configure pools of MessageRouter(s) during ejbCreate(), where bean instances obtain a MessageRouter from the configured pool in order to route an incoming XML message. See org.osesb.objectpools.MessageRouterPoolFactory.

MessageRouter(s) are also configured by ClientGateway(s) in order to facilitate communication with broker end points such as JMS Queues and web services. Broker end-points are exposed by osESB transport handlers. Each ClientGateway instance configures a single MessageRouter. Pooling for ClientGateway resources is at the ClientGateway level, not the router level. See org.osesb.objectpools.ClientGatewayKeyedPoolFactory.

MessageRouter(s) route messages to org.osesb.messagepipeline.MessagePipeline(s) for processing.

The following discussion relates to transport handler usage. See org.osesb.msgrouting.ClientGateway for comments on how a MessageRouter is configured by a ClientGateway.

Transport handlers invoke routeEAIMessage() with a org.osesb.eaimessage.EAIMessage that encapsulates the content and meta-data for the incoming message.

XML, with or without attachments, is expected as the message content and message meta-data includes:

• Message properties as a Properties object. For example, when a JMS Message arrives at a MDB transport handler, the JMS String properties are copied to the EAIMessage properties.
• The message type as a QName. The message type is extracted from the XML message and used to route messages to org.osesb.messagepipeline.MessagePipeline(s) for processing.
• The messageID. For JMS messages, this is the JMSMessageID. For SOAP messages, this is the value of the ws-addressing MessageID SoapHeader element.
• The messageCreateDateTime, which is the date-time that the message was created as a java.util.Date.

A message entering osESB through one of the transport handlers (see the org.osesb.transporthandlers package) must have a message type. Since osESB is configured mostly to handle XML messages (possibly with attachments) the message type is typically a QName where the namespaceURI is the namespace of the XML message and the local part is determined by elements or attributes in the message.

Transport handlers 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. See the org.osesb.transporthandlers package in the transport-handlers module.

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

1. A transport handler can be configured with a static messageType. In this case all messages arriving at that transport handler will be assigned the same message type.
2. If a transport handler is not configured with a static message type, then the configured MessageRouter uses a XMLMessageTypeHelper to extract a message type from the incoming 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.

MessageRouter(s)can be pooled. See org.osesb.objectpools.MessageRouterPoolFactory.

Since:

Version .9

Field Summary

protected static org.apache.commons.logging.Log	log The logging implementation for this class.
protected MessageRouterConfiguration	messageRouterConfiguration The MessageRouterConfiguration that this MessageRouter is constructed with.
protected java.lang.String	thisClassName The full name of this class.
protected AbstractXMLMessageTypeHelper	xmlMessageTypeHelper XMLMessageTypeHelper that extracts message types from XML text.

Constructor Summary

MessageRouter(MessageRouterConfiguration messageRouterConfiguration)
Creates a new instance of a MessageRouter with a MessageRouterConfiguration that includes:

A XMLMessageTypeXPathExpressionListConfiguration, which configures XPath expressions that resolve to message types. A XMLMappedConfiguration that maps message types to the MessagePipelines that are configured to process incoming messages.

Method Summary

MessageRouterConfiguration	getMessageRouterConfiguration() Return the MessageRouterConfiguration for this MessageRouter.
javax.xml.namespace.QName	getMessageType(java.lang.String xmlMessageText) Returns the message type for the given XML message using the XMLMessageTypeHelper configured by the <xmlMessagetypeHelperConfiguration> configuration element of the MessageRouterConfiguration.
protected AbstractXMLMessageTypeHelper	loadXMLMessageTypeHelper() Loads the configured XMLMessageTypeHelper from the <xmlMessagetypeHelperConfiguration> content model element of the MessageRouterConfiguration.
static void	main(java.lang.String[] args) main() For testing and sandboxing.
EAIMessage	routeEAIMessage(EAIMessage eaiMessage) Route a EAIMessage to a MessagePipeline for processing and possibly return a result as an EAIMessage.

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.

messageRouterConfiguration

protected MessageRouterConfiguration messageRouterConfiguration

The MessageRouterConfiguration that this MessageRouter is constructed with.

xmlMessageTypeHelper

protected AbstractXMLMessageTypeHelper xmlMessageTypeHelper

XMLMessageTypeHelper that extracts message types from XML text. Lazily initialized by getMessageType().

See Also:

loadXMLMessageTypeHelper(), getMessageType(String xmlMessageText)

Constructor Detail

MessageRouter

public MessageRouter(MessageRouterConfiguration messageRouterConfiguration)
              throws java.lang.Exception

Creates a new instance of a MessageRouter with a MessageRouterConfiguration that includes:

• A XMLMessageTypeXPathExpressionListConfiguration, which configures XPath expressions that resolve to message types.
• A XMLMappedConfiguration that maps message types to the MessagePipelines that are configured to process incoming messages.

Parameters:

messageRouterConfiguration - A MessageRouterConfiguration

Throws:

java.lang.Exception - if construction fails.

Method Detail

routeEAIMessage

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

Route a EAIMessage to a MessagePipeline for processing and possibly return a result as an EAIMessage.

Parameters:

eaiMessage - The EAIMessage to route.

Returns:

the EAIMessage that is the result of pipeline processing.

Throws:

PipelineStageException - if an error occurs while running the destination MessagePipeline.

java.lang.Exception - if any error other than a PipelineStageException occurs.

getMessageType

public javax.xml.namespace.QName getMessageType(java.lang.String xmlMessageText)
                                         throws java.lang.Exception,
                                                MessageTypeNotFoundException

Returns the message type for the given XML message using the XMLMessageTypeHelper configured by the <xmlMessagetypeHelperConfiguration> configuration element of the MessageRouterConfiguration.

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.

Parameters:

xmlMessageText - The XML to extract the message type from.

Returns:

the EAIMessage that is the result of pipeline processing.

Throws:

java.lang.Exception - if a general error occurs.

MessageTypeNotFoundException - if the message type cannot be determined.

loadXMLMessageTypeHelper

protected AbstractXMLMessageTypeHelper loadXMLMessageTypeHelper()
                                                         throws java.lang.Exception

Loads the configured XMLMessageTypeHelper from the <xmlMessagetypeHelperConfiguration> content model element of the MessageRouterConfiguration.

Example <xmlMessagetypeHelperConfiguration> content model:

<xmlMessagetypeHelperConfiguration>
              <!-- The MessagetypeHelper class. -->
              <helper-class>org.osesb.msgrouting.test.CustomTestXMLMessageTypeHelper_Test2</helper-class>
              <!--
                  A fully qualified helper configuration class name is optional.

                  If <helper-config> is empty, then this element is not used.
                  If <helper-config> is not empty, then the specified class is
                  constructed from the <helper-config> element. If <helper-config>
                  is not empty and this element is not specified, then a XMLConfiguration
                  is constructed from the <helper-config> element.

                  If a helper configuration is constructed, then it is passed
                  to the constructor of the <helper-class> when the helper class
                  is constructed by MessageRouter.
              -->
              <helper-config-class>org.osesb.msgrouting.configuration.XMLMessageTypeXPathExpressionListConfiguratio</helper-config-class>
              <helper-config>...</helper-config>
      </xmlMessagetypeHelperConfiguration>
 

Returns:

The configured instance of AbstractXMLMessageTypeHelper.

Throws:

java.lang.Exception - if there is an error constructing a XMLMessageTypeHelper.

See Also:

getMessageType(String xmlMessageText)

getMessageRouterConfiguration

public MessageRouterConfiguration getMessageRouterConfiguration()

Return the MessageRouterConfiguration for this MessageRouter.

Returns:

the MessageRouterConfiguration for this MessageRouter.

main

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

main() For testing and sandboxing.

Parameters:

args - commandline arguments