org.osesb.transporthandlers
Class TransportHandlerBase

java.lang.Object
  org.osesb.transporthandlers.TransportHandlerBase

All Implemented Interfaces:

java.io.Serializable, javax.ejb.EnterpriseBean

Direct Known Subclasses:

JMSXMLMessageTransportHandlerMDB, SOAPXMLMessageTransportHandlerBean

public class TransportHandlerBase
extends java.lang.Object
implements javax.ejb.EnterpriseBean

Out of the box, osESB supports document style interactions where service consumers, which are broker clients, interact with, or invoke, services using XML messages.

Transport handlers are entry points for messages sent to osESB and this abstract Class is the ancestor for the standard osesb transport handlers.

The standard osESB transport handlers expect XML messages, possibly with attachments. The standard osESB 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 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, a BrokerAcknowledgementMessage 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).

Generally, transport handlers process incoming messages as follows:

1. Extract the content of the incoming JMS Message. Message content is a XML message with possible attachments.
2. Construct a EAIXMLMessage or a EAIXMLMessageWithAttachments with the message content.
3. If configured with an environment property that specifies the message type for all messages arriving at the transport handler, then set the message type in the EAIMessage. Otherwise, the message type is extracted from the XML message by MessageRouter.
4. 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 the transport handler.
5. Invoke MessageRouter#routeEAIMessage(), which routes the EAIMessage to the configured org.osesb.messagepipeline.MessagePipeline for processing and returns the results of MessagePipeline processing from the MessagePipelineContext. See the org.osesb.messagepipeline package.
6. Send a reply if transport-specific addressing information indicates that a reply is expected. See the JMS, SOAP, and SOAP over JMS transport handlers for specifics around how replies are handled for their respective transports.

Since:

Version .9

See Also:

Serialized Form

Field Summary

protected boolean	debugFlag Debug flag from the environment.
protected boolean	echoMessageAsAcknowledgement echoMessage as acknowledgement flag from the environment.
protected static org.apache.commons.logging.Log	log The logging implementation for this class.
protected ObjectPool	messageRouterPoolInstance Pool of MessageRouters.
protected javax.xml.namespace.QName	transportHandlerMessageType From the org.osesb.messagetype.transport.namespaceURI and org.osesb.messagetype.transport.localPart environment properties, the optional messageType (QName) that will be associated with all messages arriving on this transport handler.
protected static java.lang.String	transportHandlerName The name for this transportHandler, which defaults to the class name..
protected boolean	verbose verbose flag from the environment.

Constructor Summary

TransportHandlerBase()

Method Summary

void	ejbCreate() ejbCreate().
void	ejbRemove() ejbRemove()

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.

transportHandlerName

protected static java.lang.String transportHandlerName

The name for this transportHandler, which defaults to the class name..

transportHandlerMessageType

protected javax.xml.namespace.QName transportHandlerMessageType

From the org.osesb.messagetype.transport.namespaceURI and org.osesb.messagetype.transport.localPart environment properties, the optional messageType (QName) that will be associated with all messages arriving on this transport handler.

A transport handler can have a fixed messageType that will be set for all messages arriving at the transport handler.

The messageType is used by the configured MessageRouter to route a message to a MessagePipeline for processing.

If not specified, the messageType is determined by the configured org.osesb.msgrouting.MessageRouter according to the <xmlmessage-messagetype-xpathexpression-list> configuration element of the MessageRouterConfiguration.

See Also:

ejbCreate()

messageRouterPoolInstance

protected ObjectPool messageRouterPoolInstance

Pool of MessageRouters.

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.

The configuration file for the pool of MessageRouter(s) is set in the 'object-pool-configurations.properties' file, which is usually packaged in osesb-configurations.jar and placed in the classpath of the target EAR.

messageRouterPoolInstance is a singleton.

See Also:

ejbCreate()

echoMessageAsAcknowledgement

protected boolean echoMessageAsAcknowledgement

echoMessage as acknowledgement flag from the environment.

By default, if a MessagePipeline does not return a result and the service requestor expects a reply, then a org.osesb.msgrouting.BrokerAcknowledgementMessage is sent as the reply. Under some circumstances it may be convenient for the source application to receive a copy of the original message as a reply. This behavior is governed by the echoMessageAsAcknowledgement environment property, which defaults to false.

See Also:

ejbCreate()

debugFlag

protected boolean debugFlag

Debug flag from the environment.

verbose

protected boolean verbose

verbose flag from the environment.

Constructor Detail

TransportHandlerBase

public TransportHandlerBase()

Method Detail

ejbCreate

public void ejbCreate()
               throws javax.ejb.CreateException

ejbCreate().

Throws:

javax.ejb.CreateException

ejbRemove

public void ejbRemove()

ejbRemove()