JMSBC_WSDL Xtensibility - OpenESB: the Open Source ESB for SOA & Integration

Index Changes

This is version 14. It is not the current version, and thus it cannot be edited.
[Back to current version] [Restore this version]

JMS Binding WSDL Extensibility Elements

The JMS WSDL extensibility elements allow the user to "define" JMS protocol based bindings in a WSDL.

This page describes the JMS extensibility elements for address, binding, operation, input, and output.

How to read the tables:

Each table describes the attribute(s) for a particular JMS extensibility element and any children elements the extensiblity element may have. For each attribute or element, its name, description, whether the attribute or element applies to both provider or consumer (Common), whether the attribute or element applies only to provider (Provider Only), whether the attribute or element applies only to consumer (Consumer Only), whether it is required, and an example of its usage are provided. Note that provider or consumer is from the perspective of the JMS Binding Component with respect to other components in the JBI environment. If other components "consume" the service(s) of the JMS Binding Component, then the JMS Binding Component is a provider. On the other hand, if the JMS Binding Component "consumes" the services of ther JBI components, then the JMS Binding Component is a consumer.
An additional column called Can Be Env specifies whether an environment variable can be used in place of a value. A token starts with ${ and ends with }. For example, for the connectionURL attribute, one can use an environment variable token such as ${tok_connectionURL}. The value of this environment variable (tok_connectionURL) can then be set using the JMS BC runtime configuration MBean (i.e., via NetBeans).

JMS `address`

The JMS address extensibily element allows the user to specify the connectivity information to the JMS server.

JMS address element attributes:

Attribute/Element Name	Description	Common	Required	Can Be Env	Example
connectionURL	A URL which specifies the connectivity information to connect to the JMS server, even if that JMS server normally doesn't use a URL format	X	X	X	mq://myhost:7676
username	Specifies the username used for connecting to the JMS server	X		X	guest
password	Specifies the password used for connecting to the JMS server	X		X	guest
connectionFactoryName	When the `connectionURL` attribute of the `address` extensibility element is specified as "`jndi://`", this attribute defines the JMS connection factory JNDI name used to lookup the JMS connection factory for creating connections. Note that the `destinationType` and `transaction` attributes determine what type of JMS connection factory is being looked up. For example, if destinationType is `Queue` and transaction is `XATransaction` then the JMS connection factory must be of type `javax.jms.XAQueueConnectionFactory.`	X		X	MyQueueCF
initialContextFactory	When the `connectionURL` attribute of the `address` extensibility element is specified as "`jndi://`", this attribute defines the initial context factory to use; see javax.naming.Context.INITIAL_CONTEXT_FACTORY	X			com.sun.jndi.fscontext.RefFSContextFactory
providerURL	When the `connectionURL` attribute of the `address` extensibility element is specified as "`jndi://`", this attribute defines the configuration information for the service provider to use; see javax.naming.Context.PROVIDER_URL	X		X	file:///C:/temp/JavaMQFactoriesObjFile
securityPrincipal	When the `connectionURL` attribute of the `address` extensibility element is specified as "`jndi://`", this attribute defines the identity of the principal for authenticating the caller to the service; see javax.naming.Context.SECURITY_PRINCIPAL	X		X	SomeUser
securityCredentials	When the `connectionURL` attribute of the `address` extensibility element is specified as "`jndi://`", this attribute defines the credentials of the principal for authenticating the caller to the service; see javax.naming.Context.SECURITY_CREDENTIALS	X		X	SomePass
jndienv	Child element of the `address` element which allows for specifying additional provider specific JNDI environment properties used to create the `javax.naming.InitialContext`. This is used only when the JMS BC is used in JNDI lookup mode where by it looks up the JMS connection factory needed to create connections	X			--

The following is a sample usage of the JMS address extensiblity element defined for a service port which contains a connectionURL that specifies an explicit JMS provider,

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

Here's another sample usage of the JMS address extensiblity element defined for a service port which contains a connectionURL that specifies a JNDI URL,

   &lt;port binding="y:binding" name="jmsOutOnlyTestEndpoint">
      &lt;jms:address connectionURL="jndi://" 
                      connectionFactoryName="MyXAQueueCF" 
                      initialContextFactory="com.sun.jndi.fscontext.RefFSContextFactory"
                      providerURL="file:///C:/temp/JavaMQFactoriesObjFile">
         &lt;jms:jndienv>
            ...
         &lt;/jms:jndienv>
      &lt;/jms:address>
   &lt/port>

This example shows that the jndiConnectionFactoryName is "MyXATopicCF". Assuming that the JMS binding operation's destinationType value is "Queue" and that the Transaction value is "XATransaction", then the connection factory type being looked up is of type javax.jms.XAQueueConnectionFactory. It is the responsibility of the user to ensure that the connection factory bound to JNDI as "MyXAQueueCF" is of type javax.jms.XAQueueConnectionFactory. When JNDI is used, additional information needed to create the javax.naming.InitialContext must be specified by using the jndienv extensibility element. See additional details below on how to use the jndienv extensibility element to configure the JNDI environment information.

What information does the connectionURL provide?

The connectionURL specifies the connectivity information to connect to the JMS server, even if that JMS server normally doesn't use a URL format. The format is of the form

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

The query string is optional and is reserved for possible future use. It contains both properties for the JMS server as well as for the JMSJCA connector used by the JMS Binding Component.

The protocol portion of the connectionURL can specify either a particular JMS provider (i.e., "mq" for Sun Java System Message Queue aka Java MQ) or a generic JMS provider, via JNDI, by using "jndi" as the prefix. In the case when JNDI is used to look up a JMS connection factory, the connectionURL is simply specified as "jndi://". The jndienv extensibility element is then used to specified the JNDI environment context in order for the JMS BC to create the javax.naming.InitialContext. See the section on the jndienv extensibility element below for details. Please note that when JNDI is used, the appropriate JNDI provider jar(s) must be in the runtime classpath (e.g., for Sun Application Server (Glassfish), the JNDI provider jar(s) can be copied to the the lib directory. In addition, JMS provider client jars also need to be in the runtime classpath.

This table lists the protocol and the corresponding JMS provider

URL Starts With	Provider	Example
mq://	Sun Java MQ	mq://localhost:7676
jndi://	Generic JMS Provider	jndi://

Connecting to a cluster of Sun Java System MQ brokers

For Sun Java MQ, a list of brokers can be specified to allow the JMS BC to connect to a cluster of brokers. This is a comma separated list of URLs. For example, to connect to a cluster of brokers running on localhost with ports 9090, 9191, and 9292. The jms:address element would be configured as,

   &lt;port binding="y:binding" name="jmsOutOnlyTestEndpoint">
      &lt;jms:address connectionURL="mq://localhost:9090,mq://localhost:9191,mq://localhost:9292" username="admin" password="admin"/>
   &lt;/port>

See the Sun Java System MQ documentation on how to create a cluster of brokers.

JMS `jndienv` Extensibility Element

The JMS jndienv element is used to enumerate the JNDI environment map entries needed to create the java.naming.InitialContext. It is necessary only when the connectionURL is "jndi://". This element is a child element of the JMS address extensibility element. The jndienv element is a collection of one or more jndienventry element(s).

JMS jndienventry element attributes: The JMS jndienventry element is used to specify the name and value of a JNDI environment map entry. The name and value of each entry depends on the JNDI provider being used.

Attribute Name	Description	Required	Example
name	The name of the JNDI environment map entry	X	java.naming.factory.initial
value	The value of the JNDI environment map entry	X	com.sun.jndi.fscontext.RefFSContextFactory

The following is a sample usage of the JMS jndienv and jndienventry extensibility elements to define a *SonicMQ® based JNDI provider

   &lt;port binding="y:binding" name="jmsOutOnlyTestEndpoint">
      &lt;jms:address connectionURL="jndi://" 
                      connectionFactoryName="SampleQCF"
                      initialContextFactory="com.sonicsw.jndi.mfcontext.MFContextFactory"
                      providerURL="tcp://localhost:2506">
          &lt;jms:jndienv>
              &lt;jms:jndienventry name="com.sonicsw.jndi.mfcontext.domain" value="Domain1"/>
              &lt;jms:jndienventry name="com.sonicsw.jndi.mfcontext.idleTimeout" value="60000"/>
          &lt;jms:jndienv>
      &lt;/jms:address>
   &lt/port>

JMS `binding`

The JMS binding extensibility element indicates a binding that is of interest to the JMS Binding Component. It is essentially an empty element which serves as a marker allowing the JMS Binding component to gather JMS "binding" information described by the other JMS extensibility elements. The JMS binding extensibility element MUST BE SPECIFIED in the WSDL to define a JMS protocol based binding.

The following is a sample usage of the JMS binding extensiblity element,

&lt;binding name="bindingJMSOneWayOut"
         type="tns:portTypeOneWayOut">
    &lt;jms:binding>&lt;/jms:binding>
 ...
&lt;/binding>

JMS `operation`

The JMS operation extensibility element indicates an operation binding that is of interest to the JMS Binding Component. This element has attributes and child elements which are used to define JMS message delivery options for the JMS BC.

JMS operation element attributes and children elements:

Attribute/Element Name	Description	Common	Provider Only	Consumer Only	Required	Can Be Env	Example
destination	Defines the destination where messages are sent or received	X			X	X	InvoiceQueue
destinationType	Specifies the destination type, either `Queue` or `Topic`	X			X		Queue
transaction	Defines the transaction type for the JMS protocol based operation; valid values: `NoTransaction`, `XATransaction`	X					NoTransaction
deliveryMode	The message delivery mode to use when sending a message, either `NON_PERSISTENT` or `PERSISTENT`; default is `NON_PERSISTENT`		X				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		X				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		X				4
disableMessageID	Sets whether message IDs are disabled for a message producer, either `true` or `false`; default is `false`		X				false
disableMessageTimeStamp	Sets whether message timestamps are disabled for a message producer, either `true` or `false`; default is `false`		X				false
timeout	Sets the timeout in milliecons on a message consumer receive for a reply message; applies only to provider request reply		X				120000
clientID	A unique client ID; if using a durable subscriber and this is not set then the durableName will be used as the clientID		X			X	ClientID123
messageSelector	JMS message selector to define message filtering			X		X	JMSCorrelationID='88888888' AND JMSType='SUN'
validateMessageSelector	If messageSelector is used, this enables or disables the validation of the message selector syntax during deployment. Default is true if not specified.			X			true
subscriptionDurability	Determines the durability of the Topic subscriber, either `NonDurable` or `Durable`, default is `NonDurable`			X			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)			X		X	SunStockSubscriptionName
batchSize	If defined with a positive integer, this element specifies that the messages received will be in a batch. The number of messages in the batch could be less than or equal to the specified size			X			20
maxConcurrentConsumers	If defined with a positive integer and the destination type is Queue, this element specifies the maximum number of concurrent receivers that can process messages; default is 15 if destinationType is `Queue`			X			15
redeliveryHandling	If defined, this attribute specifies what actions to take in the event that an error occurred in processing the JMS message received from the JMS destination (for example, putting the "poisoned" message in a dead letter queue). See below for syntax of redeliveryHandling			X		X	5:1000; 10:5000; 50:move(queue:mydlq)
options	This a sub-element reserved for future use to define additional configuration options	X					--

The following shows the operation extensibility element in a JMS binding using an explicit JMS provider (i.e., connectionURL is "mq://localhost:7676" to use Java MQ):

    ...

    &lt;port binding="y:binding" name="jmsOutOnlyTestEndpoint">
    &lt;jms:address connectionURL="mq://localhost:7676"/>

    ...
    &lt;operation name="Operation1">
        &lt;jms:operation destination="MyTopic" 
                       destinationType="Topic"
                       messageSelector="JMSType='FOO.Type'"/>
        ...

    &lt;/operation>
    ...

Redelivery Handling syntax (redeliveryHandling attribute)

A JMS message is typically redelivered because of an error in the processing of the message. This error may be permanent or transient. Delaying delivery of a redelivered message is useful to save CPU cycles instead of letting the message "spin" rapidly. If the error is transient, the message will eventually "go through". If the error is permanent, moving messages to a different destination may be a better approach. If the message is not valuable, deleting the message is another option.

Specification of what actions to undertake when the message is repeatedly redelivered is done through a specially formatted string. The string has this format:

   format := entry[; entry]*
   entry := idx ":" action
   idx := number (denotes the n-th time a msg was seen)
   action := number (denotes delay in ms) | "delete" | "move"(args)
   move := "queue"|"topic" | "same" ":" destname
   destname :=  any string, may include "$" which will be replaced with the original
       destination name.

Here are some examples.

Example:

5:1000; 10:5000; 50:move(queue:mydlq)

This causes no delay up to the 5th delivery; a 1000 ms delay is invoked when the message is seen the 5th, 6th, 7th, 8th, and 9th time. A 5 second delay is invoked when the msg is invoked the 10th, 11th, ..., 49th time. When the msg is seen the 50th time the msg is moved to a queue with the name "mydlq".

If the messages were received from "Queue1" and if the string was specified as

5:1000; 10:5000; 50:move(queue:dlq$oops)

the messages would be moved to the destination "dlqQueue1oops": the special character "$" denotes the original destination name. Instead of "queue" one can also specify "topic" or "same". The latter denotes a queue if the message was received from a queue, or can denote a topic if the message was received from a topic.

Another example:

5:1000; 10:5000

This causes no delay up to the 5th delivery; a 1000 ms delay is invoked when the message is seen the 5th, 6th, 7th, 8th, and 9th time. A 5 second delay is invoked for each time the message is seen thereafter.

JMS `message` (operation's input and output JMS binding)

This JMS extensibility element defines the mapping of JMS message to/from WSDL message. It is the JMS binding for an operation's input and output elements.

JMS message element attributes and children elements:

Attribute/Element Name	Description	Common	Consumer Only	Required	Example
properties	This sub-element defines the JMS message user properties to/from WSDL Message part(s) mappings; see the table for `properties` below for details	X			--
mapmessage	This child element defines the JMS MapMessage to/from WSDL Message part(s) mappings; see the table for `mapmessage` for details	X		Required if `messageType` is `MapMessage`, no otherwise	--
messageType	The type of JMS messages to be created and sent to the JMS destination; valid values: `MapMessage`, `TextMessage`	X		X	TextMessage
textPart	When messageType is TextMessage, this attribute defines the WSDL message part to/from JMS TextMessage text payload mapping	X		Required if `messageType` is `TextMessage`, no otherwise	msgPart1
use	Specify encoder support; valid values: `literal`, `encoded`	X		X	TextMessage
encodingStyle	Specify the encoder used if use is set to encoded	X		Required if `use` is `encoded`	TextMessage
correlationIdPart	This attribute is used to reference the message part where the JMSCorrelationID header value will be retrieved or stored	X			partCorrelationID
deliveryModePart	This attribute is used to reference the message part where the JMSDeliveryMode header value will be retrieved or stored	X			partDeliveryMode
priorityPart	This attribute is used to reference the message part where the JMSPriority header value will be retrieved or stored	X			partPriority
typePart	This attribute is used to reference the message part where the JMSType header value will be retrieved or stored	X			partType
messageIDPart	This attribute is used to reference the message part where the JMSMessageID header value will be stored		X		partMessageID
redeliveredPart	This attribute is used to reference the message part where the JMSRedelivered header value will be stored		X		partRedelivered
timestampPart	This attribute is used to reference the message part where the JMSTimestamp header value will be stored		X		partTimestamp

The following shows the message extensibility element in a JMS binding:

   
   ...
   &lt;jms:binding>&lt/jms:binding>
     &lt;operation name="operationOneWayOut">
        &lt;jms:operation destination="MyTopic" 
                       destinationType="Topic"
                       messageSelector="JMSType='FOO.Type'"/>
            &lt;input name="input">
                &lt;!—jms:message defines the wsdl message to/from jms message mappings -->
                &lt;jms:message messageType="MapMessage"
                             use="literal" 
                             correlationIdPart=”msgPart1”
                             deliveryModePart=”msgPart2”
                             priorityPart=”msgPart3”
                             typePart=”msgPart4”
                             messageIDPart=”msgPart5”
                             timestampPart=”msgPart6”>
                     &lt;jms:mapmessage>
                        &lt;jms:mappart part="partBoolean" type="boolean" name="BooleanMapEntry">&lt;/jms:mappart>
                        &lt;jms:mappart part="partChar" type="char" name="CharMapEntry">&lt;/jms:mappart>
                     &lt;/jms:mapmessage >
                &lt;/jms:message>
             &lt;/input>
         &lt;/jms:operation>
     &lt;/operation>
   &lt;/jms:binding>
   ...

JMS `properties` Extensibility Element

The JMS properties extensibility element is a collection of property elements. It is optional, child element of the message extensibility element use to define one more more JMS message user properties to/from WSDL message part mapping. Each property element defines a mapping of a JMS message user property to/from a WSDL message part.

JMS property element attributes:

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

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

   
   ...
   &lt;jms:message messageType="TextMessage" textPart="partBody">
      &lt;jms:properties>
        &lt;jms:property part="partPropString" propertyType="string" name="AppStringProperty">&lt;/jms:property>
	&lt;jms:property part="partPropBoolean" propertyType="boolean" name="AppBooleanProperty">&lt;/jms:property>
	&lt;jms:property part="partPropShort" propertyType="short" name="AppShortProperty">&lt;/jms:property>
	&lt;jms:property part="partPropInt" propertyType="int" name="AppIntProperty">&lt;/jms:property>
	&lt;jms:property part="partPropLong" propertyType="long" name="AppLongProperty">&lt;/jms:property>
        &lt;jms:property part="partPropFloat" propertyType="float" name="AppFloatProperty">&lt;/jms:property>
      &lt;/jms:properties>
   &lt;/jms:message>
   ...

JMS `mapmessage` Extensibility Element

In the case where the exchange involves a JMS MapMessage type, the JMS mapmessage extensibility element is used to define the mapping of the JMS MapMessage to the WSDL message parts and vice-versa. This element is a child element of of either the JMS message extensibility element. The mapmessage element is a collection of one or more mappart element(s).

JMS mappart element attributes:

Attribute Name	Description	Required	Example
name	The name of the MapMessage object to which the message part is mapped	X	JMSProp1
part	The name of the message part to which the MapMessage object is mapped	X	msgPart1
type	The Java type of the JMS MapMessage object	X	string

The following is a sample usage of the JMS mapmessage and mappart extensiblity elements,

   
   ...
   &lt;jms:message messageType="MapMessage">
     &lt;jms:mapmessage>
        &lt;jms:mappart part="partBoolean" type="boolean" name="BooleanMapEntry">&lt;/jms:mappart>
        &lt;jms:mappart part="partChar" type="char" name="CharMapEntry">&lt;/jms:mappart>
        &lt;jms:mappart part="partDouble" type="double" name="DoubleMapEntry">&lt;/jms:mappart>
        &lt;jms:mappart part="partFloat" type="float" name="FloatMapEntry">&lt;/jms:mappart>
        &lt;jms:mappart part="partInt" type="int" name="IntMapEntry">&lt;/jms:mappart>
        &lt;jms:mappart part="partLong" type="long" name="LongMapEntry">&lt;/jms:mappart>
        &lt;jms:mappart part="partShort" type="short" name="ShortMapEntry">&lt;/jms:mappart>
        &lt;jms:mappart part="partString" type="string" name="StringMapEntry">&lt;/jms:mappart>
     &lt;/jms:mapmessage>
   &lt;/jms:message>
   ...

JMS `options` Extensibility Element

The JMS options element is reserved for future use. It is intended to be used to define additional/optional properties supported by the JMSJCA RA as need arises. This element is a child element of the JMS configuration extensibility element. The options element is a collection of one or more option element(s).

JMS option element attributes:

Attribute Name	Description	Required	Example
name	The name of the JMSJCA option	X	--
value	The valueof the JMSJCA option	X	--

Table of JMSJCA RA options currently supported by the JMS BC:

Option Name	Description	Option Value Type	Example
JMSJCA.poolmaxsize	The maximum number of connections in the pool (32 is default if not specified)	integer	35
JMSJCA.poolminsize	The minimum number of connections in the pool (0 is default if not specified)	integer	5
JMSJCA.pooltimeout	When the application requests a connection and the number of in-use connections has reached the poolmaxsize, this is the maximum time in milliseconds the pool will block before it will throw an exception back to the application. A value of zero will wait indefinitely until a connection becomes available. A negative value will throw an exception immediately. A positive value will throw an exception after the specified value. Default is to throw an exception if a connection is not available (-1)	long	60000

The following is a sample usage of the JMS options and option extensiblity elements,

   ...
      &lt;jms:operation destination="InTestDestination2" 
                     destinationType="Queue" 
                     transaction="NoTransaction">
         &lt;jms:options>
            &lt;jms:option name="JMSJCA.poolmaxsize" value="35"/>
            &lt;jms:option name="JMSJCA.pooltimeout" value="30000"/>
            &lt;/jms:options>
         &lt;/jms:operation>
      &lt;/jms:operation>
   ...

*SonicMQ® is a product and a registered trademark of Progress Software Corporation ©, http://www.sonicsoftware.com/products/sonicmq/index.ssp

Access Count: 6
StatCounter Access Count :

Version	Date	Author	Size	Changes ...
16	01-May-07 12:16 PM, -0700	jamestran	27135	to previous
15	26-Apr-07 12:13 PM, -0700	jamestran	27139	to previous \| to last
14	18-Apr-07 15:15 PM, -0700	jamestran	26968	to previous \| to last
13	18-Apr-07 15:14 PM, -0700	jamestran	26807	to previous \| to last
12	11-Apr-07 20:46 PM, -0700	jamestran	25287	to previous \| to last
11	09-Apr-07 16:36 PM, -0700	jamestran	24678	to previous \| to last
10	09-Apr-07 16:28 PM, -0700	jamestran	24641	to previous \| to last
9	09-Apr-07 12:58 PM, -0700	jamestran	24543	to previous \| to last
8	02-Apr-07 11:33 AM, -0700	jamestran	19755	to previous \| to last
7	06-Mar-07 15:03 PM, -0800	jamestran	19562	to previous \| to last
6	26-Jan-07 14:17 PM, -0800	jamestran	19060	to previous \| to last
5	16-Jan-07 12:12 PM, -0800	jamestran	18418	to previous \| to last
4	16-Jan-07 12:08 PM, -0800	jamestran	18347	to previous \| to last
3	08-Jan-07 13:53 PM, -0800	jamestran	17936	to previous \| to last
2	09-Nov-06 11:27 AM, -0800	baracuda	15176	to previous \| to last
1	09-Nov-06 11:23 AM, -0800	baracuda	15036	to last

G'day, Anonymous Guest

JSPWiki v2.4.100

« Home Index Changes Prefs

This particular version was published on 18-Apr-07 15:15 PM, -0700 by jamestran

JMS Binding WSDL Extensibility Elements

JMS address

What information does the connectionURL provide?

Connecting to a cluster of Sun Java System MQ brokers

JMS jndienv Extensibility Element

JMS binding

JMS operation

Redelivery Handling syntax (redeliveryHandling attribute)

JMS message (operation's input and output JMS binding)

JMS properties Extensibility Element

JMS mapmessage Extensibility Element

JMS options Extensibility Element