Java^TM Platform, Enterprise Edition (Java EE) 5 Technologies
Project Open ESB Starter Kit
Copyright © 2006 Sun Microsystems, Inc. All rights reserved.

JMS Binding Component Overview

The following topics describe the JMS Binding Component.

About the JMS Binding Component
JMS Binding Component Features
Installing the JMS Binding Component
Configuring the Design-Time Components

About the JMS Binding Component

The JMS Binding Component is a JSR 208-compliant JBI runtime component that implements the Java Business Integration component interfaces. It provides JMS protocol transport for inbound and outbound messages. The components "interact" with one another through the use of message exchanges that are coordinated by the Normalized Message Router (NMR).

JMS BC as a Service Provider

In the case of outbound message flow, where the JMS Binding Component is being “invoked” by other components and engines, the JMS Binding Component acts as a JMS service. In this role, the JMS Binding Component converts a normalized message, that it receives as part of the message exchange from other components, to a JMS message. After the JMS message is created as a result of the message conversion, the JMS message is sent to a JMS destination.

JMS BC as a Proxy Consumer

In the case of inbound message flow, where the JMS Binding Component consumes the services of other components and engines, the JMS Binding Component acts as an external JMS proxy consumer. In this role, the JMS Binding Component converts the JMS message that it receives from a JMS service to a normalized message. The normalized message is then sent, as part of the message exchange, to another component as a service request.

top

JMS Binding Component Features

Features of the JMS Binding Component include:

Sending inbound and outbound JMS messages
Auto acknowledgement of received inbound JMS messages
Receiving batch inbound JMS messages
Receiving inbound JMS messages through a selection filter
Mapping inbound JMS properties to NMR message parts
Mapping NMR message parts to outbound JMS properties
Normalizing and denormalizing JMS messages and WSDL message parts
Invoking request/response operations

Installing the JMS Binding Component

The JMS Binding Component is not packaged with the JBI runtime delivered with the Java EE 5 SDK or with NetBeans^TM 5.5 Enterprise Pack. You can install the JBI runtime components and NetBean Module from the following link:

http://java.sun.com/integration/openesb/download.jsp

top

Configuring the Design-Time Components

Configuring the JMS BC design-time components means configuring the JMS WSDL extensibility elements. JMS WSDL extensibility elements are used to specify JMS binding specific configurations.

Extensibility elements contain information for constructing the JMS message by specifying the message parts, message formats, properties mapping, and other message related information necessary for the JMS Binding Component to properly map message exchanges to JMS messages, and vice versa.

The JMS WSDL extensibility elements also contain information which the JMS Binding Component uses to establish connections and sessions with the JMS. Various properties affecting the delivery of JMS messages are also included in the JMS WSDL extensibility elements.

You can configure three extensibility element groups for the JMS Binding Component:

JMS Connectivity
JMS Delivery
WSDL Message Part Mapping

JMS Connectivity

The JMS address extensibility element specifies the JMS server connectivity information. The JMS address WSDL extensibility element attributes include the following:

Element Name	Description	Mandatory	Example
connectionURL	A URL which specifies the connectivity information to connect to the JMS server, even if that JMS server normally does not use a URL format For more information, refer to About the ConnectionURL Element below.	Yes	mq://myhost:7676
username	Specifies the username used for connecting to the JMS server	No	admin
password	Specifies the password used for connecting to the JMS server	No	adminadmin

The following is a sample usage of the JMS address extensibility element defined for a service port:

<port binding="y:binding" name="jmsOutOnlyTestEndpoint">
   <jms:address connectionURL="mq://localhost:7676" username="admin" password="admin"/>
</port>

About the ConnectionURL Element

connectionURL specifies the connectivity information to connect to the JMS server, even if that JMS server normally does not use a URL format. The format is of the form:

protocol://server:port?key1=value1&key2=value2

The query string is optional; it contains properties for both the JMS server and the JMSJCA connector that are used by the JMS Binding Component.

Supported JMS Providers

The following is a list of supported JMS providers:

URL Prefix	Provider
`mq:// mqtcp:// mqssl:// httpjms:// httpsjms://`	Sun MQ

JMS Delivery

The JMS extensibility elements for configuring JMS delivery are divided into two subgroups: send and receive elements. These elements are the JMS bindings for the port type operation's input and/or output elements in the WSDL.

JMS Message Sending and Message Mapping Elements

As a service provider, the JMS Binding Component uses the information from these elements to create a JMS session and producer for sending JMS messages to a JMS destination. The information is located or "bound at" the operation's input or output element. This JMS extensibility element name is called send.

The send element has two sub-elements named: sendSenderDefintion and sendMessageDefinition.

The sendSenderDefintion element describes the "outgoing" JMS message delivery information for the JMS Binding Component. It includes the following element attributes and sub-elements:

Element Name	Description	Mandatory	Example
destination	Defines the destination where messages are sent	Yes	InvoiceTopic
destinationType	Specifies the destination type, either Queue or Topic	Yes	Topic
transaction	Specifies whether the send is part of a transaction, either NoTransaction or XATransaction; default is NoTransaction	Yes	NoTransaction
clientID	The client ID used when establishing a JMS session	No	ClientID123
noLocal	If true, and the destination is a Topic, inhibits the delivery of messages published by its own connection. Can be either true or false; default is false	No	true
deliveryMode	The message delivery mode to use when sending a message, either NON_PERSISTENT or PERSISTENT; default is NON_PERSISTENT	No	NON_PERSISTENT
timeToLive	Time in milliseconds from its dispatch time that a produced message, from the message producer, should be retained by the message system	No	120000
priority	The message priority for a message producer; must be a value between 0 and 9; 0 is lowest, 9 is highest; default is 4	No	4
disableMessageID	Sets whether message IDs are disabled for a message producer, either true or false; default is false	No	false
disableMessageTimeStamp	Sets whether message timestamps are disabled for a message producer, either true or false; default is false	No	false
options	This a sub-element reserved for future use to define additional options relating to sending	No	—

The sendMessageDefintion element describes the "outgoing" WSDL message to JMS message mapping for the JMS Binding Component. It includes the following element attributes and sub-elements:

Element Name	Description	Mandatory	Example
properties	This sub-element defines the WSDL Message part(s) to JMS Message user properties mappings; see the table for JMS properties below for details	No	—
mapmessageparts	This sub-element defines the WSDL Message part(s) to JMS MapMessage mappings; see the table for JMS mapmessageparts for details	Yes if messageType is MapMessage, no otherwise	—
messageType	The type of JMS messages to be created and sent to the JMS destination, either MapMessage or TextMessage	Yes	TextMessage
parts	When messageType is TextMessage, this attribute defines the parts from the WSDL message that comprise the text payload; each part in the list is delimited by a space	No	msgPart1,msgPart2
use	When messageType is TextMessage, this attribute defines the use type which affects how the message is interpreted - currently supported is literal	Yes	literal
encodingStyle	Reserved for future use; when use is defined as encoded, this attribute defines the encoding style	No	—
correlationIdPart	This attribute is used to reference the message part which contains the value for the JMSCorrelationID header	No	partCorrelationID
deliveryMode	This attribute is used to define the static value for the JMSDeliveryMode header	No	NON_PERSISTENT
deliveryModePart	This attribute is used to reference the message part which contains the value for the JMSDeliveryMode header	No	partDeliveryMode
priority	This attribute is used to define the static value for the JMSPriority header	No	5
priorityPart	This attribute is used to reference the message part which contains the value for the JMSPriority header	No	partPriority
type	This attribute is used to define the static value for the JMSType header	No	MyMessageType
typePart	This attribute is used to reference the message part which contains the value for the JMSType header	No	partType

The following is a sample usage of the JMS send extensibility element defined in the binding operation's input for a "one way" send.

<binding name="binding" type="y:portType">
<jms:binding/>
<operation name="oneway">
    <jms:operation/>
     <input>
        <jms:send>
            <jms:sendSenderDefinition destination="OutTestDestination"
                                      destinationType="Topic" 
                                      transaction="NoTransaction" 
                                      disableMessageTimeStamp="true" 
                                      noLocal="true" 
                                      deliveryMode="NON_PERSISTENT" 
                                      timeToLive="10000" priority="4" 
                                      clientID="OutTestClientID">
            </jms:sendSenderDefinition>
            <jms:sendMessageDefinition messageType="TextMessage" 
                                       use="literal" 
                                       parts="body">
            </jms:sendMessageDefinition>
        </jms:send>
    </input>
</operation>
</binding>

JMS Message Receiving and Message Mapping Elements

As a service consumer, the JMS Binding Component uses the information from this category of elements to set up endpoint delivery of messages from JMS. This information is contained at the JMS binding operation's input or output element. The extensibility element name is called receive.

This element has two sub-elements named: receiveReceiverDefintion and receiveMessageDefinition.

The receiveReceiverDefintion element describes the "incoming" JMS message delivery information for the JMS Binding Component. It includes the following element attributes and sub-elements:

Element Name	Description	Mandatory	Example
destination	Defines the destination from which messages are received	Yes	InvoiceTopic
destinationType	Specifies the destination type, either Queue or Topic	Yes	Topic
transaction	Determines whether a transaction is to be started before message delivery from JMS, either NoTransaction or XATransaction; default is NoTransaction	Yes	NoTransaction
clientID	A unique client ID if using durable subscriber and if this is not set then durableName will be used as the clientID	No	ClientID123
messageSelector	JMS message selector to define message filtering	No	JMSCorrelationID='88888888' AND JMSType='SUN'
subscriptionDurability	Determines the durability of the Topic subscriber, either NonDurable or Durable, default is NonDurable	No	NonDurable
subscriptionName	The name used to denote the durable subscription; used only if using a durable subscriber (destination is a Topic and subscriptionDurability is set to Durable)	No	SunStockSubscriptionName

The receiveMessageDefintion element describes the "incoming" JMS message to WSDL message mapping for the JMS Binding Component. It includes the following element attributes and sub-elements:

Element Name	Description	Mandatory	Example
properties	This sub-element defines JMS Message user properties to the WSDL Message part(s) mappings; see the table for JMS properties below for details	No	—
mapmessageparts	This sub-element defines the JMS MapMessage to the WSDL Message part(s) mappings; see the table for JMS mapmessageparts for details	Yes if messageType is MapMessage, no otherwise	--
messageType	The type of JMS messages expected to be received from the JMS destination, either MapMessage or TextMessage	Yes	TextMessage
part	When messageType is TextMessage, this attribute is used to reference the message part where the TextMessage text payload will be stored	No	partBody
use	When messageType is TextMessage, this attribute defines the use type which affects how the message is interpreted - currently supported is literal	Yes	literal
encodingStyle	Reserved for future use; when use is defined as encoded, this attribute defines the encoding style	No	—
correlationIdPart	This attribute is used to reference the message part where the JMSCorrelationID header value will be stored	No	partCorrelationID
deliveryModePart	This attribute is used to reference the message part where the JMSDeliveryMode header value will be stored	No	partDeliveryMode
messageIDPart	This attribute is used to reference the message part where the JMSMessageID header value will be stored	No	partMessageID
priorityPart	This attribute is used to reference the message part where the JMSPriority header value will be stored	No	partPriority
timestampPart	This attribute is used to reference the message part where the JMSTimestamp header value will be stored	No	partTimestamp
typePart	This attribute is used to reference the message part where the JMSType header value will be stored	No	partType

The following is a sample usage of the JMS receive extensiblity element defined in the binding operation's input for a "one way" receive.

<binding name="bindingJMSIn"
     type="tns:portTypeJMSIn">
<jms:binding></jms:binding>
<operation name="operationJMSIn">
    <jms:operation />                        
    <input name="input">
        <jms:receive>
            <jms:receiveReceiverDefinition destination="MsgSelectorTestDestination" 
                                 destinationType="Queue" 
                                 transaction="NoTransaction" 
                                 acknowledgementMode="AUTO_ACKNOWLEDGE" 
                                 messageSelector="JMSCorrelationID='88888888' AND JMSType='SUN'>
            </jms:receiveReceiverDefinition>
            <jms:receiveMessageDefinition messageType="TextMessage" use="literal" part="partJMS">
            </jms:receiveMessageDefinition>
        </jms:receive>
    </input>
</operation>
</binding>

WSDL Message Part Mapping

The following sub-elements are used by both the send and receive elements.

JMS Message User Properties to WSDL Message Parts Mapping

The mapping of the JMS message user properties to the WSDL message parts and vice-versa are defined using the properties sub-element of either the sendMessageDefintion or receiveMessageDefintion elements. The following is a list of property element attributes:

Element Name	Description	Mandatory	Example
name	The name of the JMS property to which the message part is mapped	Yes	JMSProp1
part	The name of the message part to which the JMS property is mapped	Yes	msgPart1
propertyType	The type of the JMS property, one of boolean, short, int, long, float, double, or string	Yes	string

The following is a sample usage of the JMS properties and property extensiblity elements:

<jms:sendMessageDefinition messageType="TextMessage" use="literal" parts="partBody">
  <jms:properties>
    <jms:property part="partPropString" propertyType="string" name="AppStringProperty"></jms:property>
    <jms:property part="partPropBoolean" propertyType="boolean" name="AppBooleanProperty"></jms:property>
    <jms:property part="partPropShort" propertyType="short" name="AppShortProperty"></jms:property>
    <jms:property part="partPropInt" propertyType="int" name="AppIntProperty"></jms:property>
    <jms:property part="partPropLong" propertyType="long" name="AppLongProperty"></jms:property>
    <jms:property part="partPropFloat" propertyType="float" name="AppFloatProperty"></jms:property>
  </jms:properties>
</jms:sendMessageDefinition>

JMS MapMessage WSDL Message Parts Mapping

In the case where the exchange involves a JMS MapMessage type, the JMS mapmesssageparts extensibility element is used to define the mapping of the JMS MapMessage to the WSDL message parts and vice-versa. This element is a sub-element of either the sendMessageDefintion or receiveMessageDefintion elements. The following is a list of mappart element attributes:

Element Name	Description	Mandatory	Example
name	The name of the MapMessage object to which the message part is mapped	Yes	JMSProp1
part	The name of the message part to which the MapMessage object is mapped	Yes	msgPart1
type	The Java type of the JMS MapMessage object	Yes	string

The following is a sample usage of the JMS mapmessageparts and mappart extensibility elements:

<jms:receiveMessageDefinition messageType="MapMessage" use="literal">
  <jms:mapmessageparts>
    <jms:mappart part="partBoolean" type="boolean" name="BooleanMapEntry"></jms:mappart>
    <jms:mappart part="partChar" type="char" name="CharMapEntry"></jms:mappart>
    <jms:mappart part="partDouble" type="double" name="DoubleMapEntry"></jms:mappart>
    <jms:mappart part="partFloat" type="float" name="FloatMapEntry"></jms:mappart>
    <jms:mappart part="partInt" type="int" name="IntMapEntry"></jms:mappart>
    <jms:mappart part="partLong" type="long" name="LongMapEntry"></jms:mappart>
    <jms:mappart part="partShort" type="short" name="ShortMapEntry"></jms:mappart>
  <jms:mappart part="partString" type="string" name="StringMapEntry"></jms:mappart>
</jms:mapmessageparts>
</jms:receiveMessageDefinition>

JMS Binding and JMS Operation Extensibility Elements

The JMS binding and JMS operation extensibility elements are empty elements that serve as markers, allowing the JMS Binding component to gather JMS "binding" information described by the other JMS extensibility elements.

The following is a sample usage of the JMS binding extensibility element:

<binding name="bindingJMSOneWayOut"
    type="tns:portTypeOneWayOut">
  <jms:binding></jms:binding>
...
</binding>

The following is a sample usage of the JMS operation extensibility element:

<binding name="bindingJMSOneWayOut"
    type="tns:portTypeOneWayOut">
  <jms:binding></jms:binding>
  <operation name="operationOneWayOut">
    <jms:operation />
      <input name="input">
...
</binding>

JavaTM Platform, Enterprise Edition (Java EE) 5 Technologies Project Open ESB Starter Kit Copyright © 2006 Sun Microsystems, Inc. All rights reserved. JMS Binding Component Overview

Contents