How to Send a JMS Message
The following describes the general steps you take to send a JMS message to a JMS provider.
1. Create an empty flow service.
2. Create the message body.
How you build the message body depends on the format that you want to use for the message. For example, if you want to use a String as the message body, create a field of type String and then add content to the String field. If you want to use a Document (IData) as the message body, create a document and then add content to the document. Note that a Document (IData) should only be used when sending a JMS message from one Integration Server to another.
If you want more control over the actual javax.jms.Message that Integration Server sends to the JMS provider, you can create a Java service that calls the com.wm.app.b2b.server.jms.producer.ProducerFacade class, and then invoke one of the following methods to create the desired javax.jms.Message:
createBytesMessage(String)
createMapMessage(String)
createObjectMessage(String)
createStreamMessage(String)
createTextMessage(String)
The Java service calling this API must return an Object of type javax.jms.Message, which can then be mapped to the JMSMessage/body/message input parameter of the pub.jms:send service.
Important:
If you want to send a StreamMessage or a MapMessage, you need to use the appropriate com.wm.app.b2b.server.jms.producer.ProducerFacade API to create the javax.jms.Message object.
When you create the javax.jms.Message with the com.wm.app.b2b.server.jms.producer.ProducerFacade, you can use the javax.jms.Message setter methods to set the values of the message headers and properties directly. You can also set the value of message headers and properties using the input parameters of the pub.jms* service that you use to send the message. If you set the message headers and properties both ways, the values provided to the pub.jms* service take precedence.
Software AG recommends that you use a pub.jms* service to create and send the JMS message. This may provide better performance on average.
3. Invoke pub.jms:send.
This service creates a JMS message (javax.jms.Message) based on input provided to the service or takes an existing JMS message and sends it to the JMS provider.
Note:
If you want to send multiple JMS messages to the same destination, use
pub.jms:sendBatch. For more information about the
pub.jms:sendBatch services, see
the webMethods Integration Server Built-In Services Reference
pub.jms:sendBatch .
4. Specify the JMS connection alias.
The JMS connection alias indicates how Integration Server connects to the JMS provider. The alias also specifies whether the alias uses a client side queue and if Integration Server will retry the pub.jms:send service automatically if the service fails because of a transient error.
Name | Description |
connectionAliasName | Name of the JMS connection alias that you want to use to send the message. |
5. Specify the destination to which you want to send the message.
If the JMS connection alias you specified in step 4 uses the native webMethods API to create the connection directly on the webMethods Broker, you need to specify the destinationName as well as the destinationType.
Name | Description |
destinationName | Name or lookup name of the Destination to which you want to send the message.  Specify the lookup name of the Destination object when the JMS connection alias uses JNDI to retrieve administered objects. Specify the provider-specific name of the Destination when the JMS connection alias uses the native webMethods API to connect directly to the webMethods Broker. |
destinationType | Specifies whether the Destination is a queue or a topic. The default is queue. |
6. Set values for the header fields in the JMS message.
All of the header fields are optional.
Name | Description |
deliveryMode | Specifies the message delivery mode for the message. Specify one of the following: PERSISTENT provides once-and-only-once delivery for the message. The message will not be lost if a JMS provider failure occurs. NON_PERSISTENT provides at-most-once delivery for the message. The message has no guarantee of being saved if a JMS provider failure occurs. The default is PERSISTENT. |
priority | Specifies the message priority. The JMS standard defines priority levels from 0 to 9, with 0 as the lowest priority and 9 as the highest. The default is 4. Message priority is not supported by Universal Messaging. Any priority assigned to a JMS message sent to Universal Messaging will be ignored. |
timeToLive | Specifies the length of time, in milliseconds, that the JMS provider retains the message. The default is 0, meaning that the message does not expire. |
JMSType | Message type identifier for the message. |
If you created a javax.jms.Message and you set the message header fields using the javax.jms.Message setter methods, you do not need to provide inputs to the fields in JMSMessage/header. If you do set message header fields using both approaches, Integration Server uses the values provided as input to the pub.jms:send service.
7. Set values for the Integration Server-specific properties.
The properties fields are optional fields added to the message header and are often used to hold message selector values. Integration Server adds the following properties to JMS messages it sends. You can set these values as follows.
Name | Description |
activation | Specifies the activation ID for the message. A JMS trigger uses the activation ID to join together messages it receives. For more information about setting the activation, see
Assigning an Activation to a JMS
Message. |
uuid | Specifies a universally unique identifier for a message. For more information about setting a UUID, see
Setting the UUID. |
If you created a javax.jms.Message and you set the message property fields using the javax.jms.Message setter methods, you do not need to provide inputs to the fields in JMSMessage/properties. If you do set message property fields using both approaches, Integration Server uses the values provided as input to the pub.jms:send service.
8. Add any custom properties to the JMS message.
To add a new property to
JMSMessage/properties, click
on the Pipeline view. Select a data type for the property and assign it a name. Make sure to place the new property in the
JMSMessage/properties field.
Assign a value to any custom properties that you add.
When publishing a message supplied as IData in the JMSMessage/body/data input parameter and Universal Messaging is the JMS provider, Integration Server provides a custom property that indicates that the message should be encoded as XML and decoded from XML instead of as a byte array. Add a String field named $coderType to the JMSMessage/properties document. Set the value of $coderType to: idata_xml_bytes
9. Map data to the body of the JMSMessage document.
Specifically, map the field that contains the data you want to included in the message body to the field in JMSMessage/body with the appropriate data type.
Map to this field... | If you... |
string | Used a field of type String for the message body content. |
bytes | Used a one-dimensional byte array for the message body content. |
object | Used a Serializable Java object for the message body content. |
data | Used a Document (IData) for the JMS message body content. Keep in mind that the IData message format can only be used when sending a JMS message from one Integration Server to another. |
message | Used a Java service to create an object of type javax.jms.Message. Note:
If you created a Java service that used one of the com.wm.app.b2b.server.jms.producer.ProducerFacade methods to create a javax.jms.Message object, map the javax.jms.Message object produced by the Java service to message. |
10. Specify whether the client side queue should be used.
When the client side queue is in use, Integration Server places messages in the client side queue if the JMS provider is not available at the time the pub.jms:send service executes. If you want to use the client side queue with this implementation of the pub.jms:send service, the JMS connection alias specified for connectionAliasName must be configured to have a client side queue. A JMS connection alias has a client side queue if the Maximum CSQ Size property for the alias is set to a value other than 0 (zero).
Name | Description |
useCSQ | Indicates whether Integration Server places the sent message in the client side queue if the JMS provider is not available at the time the message is sent. True specifies that Integration Server writes messages to the client side queue if the JMS provider is not available at the time this service executes. When the JMS provider becomes available, Integration Server sends messages from the client side queue to the JMS provider. False indicates that Integration Server throws an ISRuntimeException if the JMS provider is not available at the time this service executes. The default is False. Note:
If the specified connectionAliasName uses a cluster connection factory to which the multisend guaranteed policy is applied, set useCSQ to False. For more information about the multisend guaranteed policy, see
Working with the Multisend Guaranteed
Policy. |