Index Changes
This is version 3. 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.


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 OnlyRequiredExample
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 Xmq://myhost:7676
usernameSpecifies the username used for connecting to the JMS serverX guest
passwordSpecifies the password used for connecting to the JMS serverX guest

The following is a sample usage of the JMS address extensiblity element defined for a service port,

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

Notes On connectionURL

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.

Supported JMS Providers (most recently tested for the JMS Binding Component):

URL Starts WithProvider
mq://, mqtcp://, mqssl://, httpjms://, httpsjms:/Sun MQ

More information about the connectionURL and JMSJCA RA related information is available at the JMSJCA Wiki page http://hermes.stc.com/runtime/Wiki.jsp?page=5.1.0JMSJCA.


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,

&ltbinding name="bindingJMSOneWayOut"
         type="tns:portTypeOneWayOut">
    &ltjms: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 NameDescriptionCommonProvider OnlyConsumer OnlyRequiredExample
destinationDefines the destination where messages are sent or receivedX XInvoiceTopic
destinationTypeSpecifies the destination type, either Queue or TopicX XTopic
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 ClientID123
messageSelectorJMS message selector to define message filtering X JMSCorrelationID='88888888' AND JMSType='SUN'
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 SunStockSubscriptionName
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 5: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:

 
    ...
    &ltoperation name="Operation1">
        &ltjms: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 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:

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

   
   ...
   &ltjms:message messageType="TextMessage" textPart="partBody">
      &ltjms:properties>
        &ltjms:property part="partPropString" propertyType="string" name="AppStringProperty">&lt/jms:property>
	&ltjms:property part="partPropBoolean" propertyType="boolean" name="AppBooleanProperty">&lt/jms:property>
	&ltjms:property part="partPropShort" propertyType="short" name="AppShortProperty">&lt/jms:property>
	&ltjms:property part="partPropInt" propertyType="int" name="AppIntProperty">&lt/jms:property>
	&ltjms:property part="partPropLong" propertyType="long" name="AppLongProperty">&lt/jms:property>
        &ltjms: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 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,

   
   ...
   &ltjms:message messageType="MapMessage">
     &ltjms:mapmessage>
        &ltjms:mappart part="partBoolean" type="boolean" name="BooleanMapEntry">&lt/jms:mappart>
        &ltjms:mappart part="partChar" type="char" name="CharMapEntry">&lt/jms:mappart>
        &ltjms:mappart part="partDouble" type="double" name="DoubleMapEntry">&lt/jms:mappart>
        &ltjms:mappart part="partFloat" type="float" name="FloatMapEntry">&lt/jms:mappart>
        &ltjms:mappart part="partInt" type="int" name="IntMapEntry">&lt/jms:mappart>
        &ltjms:mappart part="partLong" type="long" name="LongMapEntry">&lt/jms:mappart>
        &ltjms:mappart part="partShort" type="short" name="ShortMapEntry">&lt/jms:mappart>
        &ltjms: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 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 ValueExample
endpointPoolMaxSizeIn the case of concurrent processing, this value (integer) specifies the number of inbound message processors that can be used to process messages concurrentlyinteger1

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

   ...
      &ltjms:operation destination="InTestDestination2" 
                     destinationType="Queue" 
                     transaction="NoTransaction">
         &ltjms:options>
            &ltjms:option name="endpointPoolMaxSize" value="1"/>
            &lt/jms:options>
         &lt/jms:operation>
      &lt/jms:operation>
   ...


JSPWiki v2.4.100
[RSS]
« Home Index Changes Prefs
This particular version was published on 08-Jan-07 13:53 PM, -0800 by jamestran