Index Changes

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 NameDescriptionCommonProvider OnlyConsumer OnlyRequiredCan Be EnvExample
connectionURLA URL which specifies the connectivity information to connect to the JMS server, even if that JMS server normally doesn't use a URL formatX XXmq://myhost:7676
usernameSpecifies the username used for connecting to the JMS serverX Xguest
passwordSpecifies the password used for connecting to the JMS serverX Xguest
connectionFactoryNameWhen 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 XMyQueueCF
initialContextFactoryWhen 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_FACTORYX com.sun.jndi.fscontext.RefFSContextFactory
providerURLWhen 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_URLX Xfile:///C:/temp/JavaMQFactoriesObjFile
securityPrincipalWhen 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_PRINCIPALX XSomeUser
securityCredentialsWhen 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_CREDENTIALSX XSomePass
jndienvChild 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 connectionsX --

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,

   <port binding="y:binding" name="jmsOutOnlyTestEndpoint">
      <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,

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

This example shows that the connectionFactoryName 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 WithProviderExample
mq://Sun Java MQmq://localhost:7676
jndi://Generic JMS Providerjndi://

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,
   <port binding="y:binding" name="jmsOutOnlyTestEndpoint">
      <jms:address connectionURL="mq://localhost:9090,mq://localhost:9191,mq://localhost:9292" username="admin" password="admin"/>
   </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 NameDescriptionRequiredExample
nameThe name of the JNDI environment map entryXjava.naming.factory.initial
valueThe value of the JNDI environment map entryXcom.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
   <port binding="y:binding" name="jmsOutOnlyTestEndpoint">
      <jms:address connectionURL="jndi://" 
                      connectionFactoryName="SampleQCF"
                      initialContextFactory="com.sonicsw.jndi.mfcontext.MFContextFactory"
                      providerURL="tcp://localhost:2506">
          <jms:jndienv>
              <jms:jndienventry name="com.sonicsw.jndi.mfcontext.domain" value="Domain1"/>
              <jms:jndienventry name="com.sonicsw.jndi.mfcontext.idleTimeout" value="60000"/>
          <jms:jndienv>
      </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,

<binding name="bindingJMSOneWayOut"
         type="tns:portTypeOneWayOut">
    <jms:binding></jms:binding>
 ...
</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 NameDescriptionCommonProvider OnlyConsumer OnlyRequiredCan Be EnvExample
destinationDefines the destination where messages are sent or receivedX XXInvoiceQueue
destinationTypeSpecifies the destination type, either Queue or TopicX X Queue
transactionDefines the transaction type for the JMS protocol based operation; valid values: NoTransaction, XATransactionX NoTransaction
deliveryModeThe message delivery mode to use when sending a message, either NON_PERSISTENT or PERSISTENT; default is NON_PERSISTENT X NON_PERSISTENT
timeToLiveTime in milliseconds from its dispatch time that a produced message, from the message producer, should be retained by the message system X 120000
priorityThe 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
disableMessageIDSets whether message IDs are disabled for a message producer, either true or false; default is false X false
disableMessageTimeStampSets whether message timestamps are disabled for a message producer, either true or false; default is false X false
timeoutSets the timeout in milliecons on a message consumer receive for a reply message; applies only to provider request reply X 120000
clientIDA unique client ID; if using a durable subscriber and this is not set then the durableName will be used as the clientID X XClientID123
messageSelectorJMS message selector to define message filtering X XJMSCorrelationID='88888888' AND JMSType='SUN'
validateMessageSelectorIf messageSelector is used, this enables or disables the validation of the message selector syntax during deployment. Default is true if not specified. X true
subscriptionDurabilityDetermines the durability of the Topic subscriber, either NonDurable or Durable, default is NonDurable X NonDurable
subscriptionNameThe 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 XSunStockSubscriptionName
batchSizeIf 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
maxConcurrentConsumersIf 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
redeliveryHandlingIf 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 X5:1000; 10:5000; 50:move(queue:mydlq)
optionsThis a sub-element reserved for future use to define additional configuration optionsX --

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):

    ...

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

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

    </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 NameDescriptionCommonProvider OnlyConsumer OnlyRequiredExample
propertiesThis sub-element defines the JMS message user properties to/from WSDL Message part(s) mappings; see the table for properties below for detailsX --
mapmessageThis child element defines the JMS MapMessage to/from WSDL Message part(s) mappings; see the table for mapmessage for detailsX Required if messageType is MapMessage, no otherwise--
messageTypeThe type of JMS messages to be created and sent to the JMS destination; valid values: MapMessage, TextMessageX XTextMessage
textPartWhen messageType is TextMessage, this attribute defines the WSDL message part to/from JMS TextMessage text payload mappingX Required if messageType is TextMessage, no otherwisemsgPart1
useSpecify encoder support; valid values: literal, encodedX XTextMessage
encodingStyleSpecify the encoder used if use is set to encodedX Required if use is encodedTextMessage
correlationIdPartThis attribute is used to reference the message part where the JMSCorrelationID header value will be retrieved or storedX partCorrelationID
deliveryModePartThis attribute is used to reference the message part where the JMSDeliveryMode header value will be retrieved or storedX partDeliveryMode
priorityPartThis attribute is used to reference the message part where the JMSPriority header value will be retrieved or storedX partPriority
typePartThis attribute is used to reference the message part where the JMSType header value will be retrieved or storedX partType
messageIDPartThis attribute is used to reference the message part where the JMSMessageID header value will be stored X partMessageID
redeliveredPartThis attribute is used to reference the message part where the JMSRedelivered header value will be stored X partRedelivered
timestampPartThis 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:

   
   ...
   <jms:binding>&lt/jms:binding>
     <operation name="operationOneWayOut">
        <jms:operation destination="MyTopic" 
                       destinationType="Topic"
                       messageSelector="JMSType='FOO.Type'"/>
            <input name="input">
                <!—jms:message defines the wsdl message to/from jms message mappings -->
                <jms:message messageType="MapMessage"
                             use="literal" 
                             correlationIdPart=”msgPart1”
                             deliveryModePart=”msgPart2”
                             priorityPart=”msgPart3”
                             typePart=”msgPart4”
                             messageIDPart=”msgPart5”
                             timestampPart=”msgPart6”>
                     <jms:mapmessage>
                        <jms:mappart part="partBoolean" type="boolean" name="BooleanMapEntry"></jms:mappart>
                        <jms:mappart part="partChar" type="char" name="CharMapEntry"></jms:mappart>
                     </jms:mapmessage >
                </jms:message>
             </input>
         </jms:operation>
     </operation>
   </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 NameDescriptionRequiredExample
nameThe name of the JMS property to which the message part is mappedXJMSProp1
partThe name of the message part to which the JMS property is mappedXmsgPart1
propertyTypeThe type of the JMS property, one of boolean,short,int,long,float,double, or stringXstring

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

   
   ...
   <jms:message messageType="TextMessage" textPart="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: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 NameDescriptionRequiredExample
nameThe name of the MapMessage object to which the message part is mappedXJMSProp1
partThe name of the message part to which the MapMessage object is mappedXmsgPart1
typeThe Java type of the JMS MapMessage objectXstring

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

   
   ...
   <jms:message messageType="MapMessage">
     <jms:mapmessage>
        <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:mapmessage>
   </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 NameDescriptionRequiredExample
nameThe name of the JMSJCA optionX--
valueThe valueof the JMSJCA optionX--


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

Option NameDescriptionOption Value TypeExample
JMSJCA.poolmaxsizeFor outbound connections (JMS BC is provider), this specifies the maximum number of connections in the pool (32 is default if not specified)integer35
JMSJCA.poolminsizeFor outbound connections (JMS BC is provider), this specifies the minimum number of connections in the pool (0 is default if not specified)integer5
JMSJCA.pooltimeoutFor outbound connections (JMS BC is provider), 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)long60000

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

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

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


Access Count: 25
StatCounter Access Count :

JSPWiki v2.4.100
[RSS]
« Home Index Changes Prefs
This page (revision-16) was last changed on 01-May-07 12:16 PM, -0700 by jamestran