Integration Server 10.3 | Built-In Services Reference Guide | JMS Folder | Summary of Elements in This Folder | pub.jms:sendBatch
 
pub.jms:sendBatch
WmPublic. Sends a group of JMS messages to the same destination on the webMethods Broker.
Input Parameters
connectionAliasName
String Name of the JMS connection alias that you want to use to send the messages.
The JMS connection alias indicates how Integration Server connects to the webMethods Broker or Universal Messaging. A JMS connection alias can specify that Integration Server use a JNDI provider to look up administered objects (connection factories and destinations) and then use the connection factory to create a connection. Alternatively, a JMS connection alias can specify that Integration Server uses the native webMethods API to create the connection directly on the webMethods Broker.
Note:connectionAliasName must specify a JMS connection alias that uses the webMethods Broker or Universal Messaging as the JMS provider.
destinationName
String Name or lookup name of the Destination to which you want to send the messages. 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.
Note:
When using the pub.jms:batchSend service, Integration Server sends all messages to the same destination.
destinationType
String Optional. Type of destination to which you want to send the message. Specify one of the following:
*QUEUE to send the message to a particular queue. This is the default.
*TOPIC to send the message to a topic.
Note:
You need to specify destinationType only if you specified a connectionAliasName that uses the native webMethods API.
deliveryMode
String Optional. Specifies the message delivery mode for the messages. Specify one of the following:
*PERSISTENT Default. Provide once-and-only-once delivery for the messages. The messages will not be lost if a JMS provider failure occurs.
*NON_PERSISTENT Provide at-most-once delivery for the messages. The messages have no guarantee of being saved if a JMS provider failure occurs.
Note:
The specified delivery mode applies to all of the messages sent by the service.
priority
java.lang.Integer Optional. Specifies the message priority for all of the messages. 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.
Note:
The specified priority applies to all of the messages sent by the service.
timeToLive
java.lang.Long Optional. Length of time, in milliseconds, that the JMS provider retains each message. The default is 0, meaning that the messages do not expire.
Note:
The specified time to live applies to all of the messages sent by the service.
JMSMessages
Document List A document list representing the JMS messages to send to the destination. Specify the following for each JMS message that you want to send:
Key
Description
header
Document Optional. A document containing the header of the JMS message.
Key
Description
JMSType
String Optional. Message type identifier for the message.
properties
Document Optional. A Document containing optional fields added to the message header. Integration Server adds the following properties to JMS messages it sends.
Key
Description
activation
String Optional. A unique identifier used to group together messages that will be received by a JMS trigger with a join. A JMS trigger can join together messages with the same activation.
uuid
String Optional. A universally unique identifier for the message. Integration Server can use the uuid for exactly-once processing or for request/reply.
body
Document Optional. A Document containing the JMS message body. Integration Server supports the following formats for the JMS message body:
Key
Description
string
String Optional. Message body in the form of a String.
bytes
primitive type Optional Message body in the form of a one-dimensional byte array.
object
Object. Optional. Message body in the form of a Serializable Java object.
data
Document Optional. Message body in the form of a document (IData object).
Note:
This message format can only be used when sending a JMS message from one Integration Server to another. When the JMS message is sent, the sending Integration Server encodes the IData into a byte array. When the receiving Integration Server receives the message, it decodes the byte array into IData.
message
Object Optional. Message body in the form of an actual javax.jms.Message.
Note:
When you send a batch of messages, you can specify a different format for each JMS message body.
useCSQ
java.lang.Boolean Optional. Flag indicating whether Integration Server places sent messages in the client side queue if the JMS provider is not available at the time the messages are sent. Set to:
*True to write 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.
Note:
If you want to use the client side queue, 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).
*False to throw an ISRuntimeException if the JMS provider is not available at the time this service executes. This is the default.
Output Parameters
JMSMessages
Document List A Document list containing the messages sent to the JMS provider. Each document contains the following information:
Key
Description
header
Document Conditional. A Document containing the header fields for the sent message. The JMS provider populates these fields after it has successfully received the message from Integration Server.
Key
Description
JMSCorrelationID
String Conditional. A unique identifier used to link messages together.
JMSDeliveryMode
java.lang.Integer Delivery mode used to send the message.
PERSISTENT indicates that the JMS provider provides once-and-only-once delivery for the message. The message will not be lost if a JMS provider failure occurs.
NON_PERSISTENT indicates that the JMS provider provides at-most-once delivery for the message. The message has no guarantee of being saved if a JMS provider failure occurs.
Note:
When sending a message, this value is obtained from the JMSMessage/header/deliveryMode input parameter.
JMSDestination
Object Conditional. Destination (queue or topic) to which the message was sent.
JMSExpiration
java.lang.LongConditional. Time at which this message expires. If the message producer did not specify a time-to-live, the JMSExpiration value is zero, indicating the message does not expire.
Note:
When sending a message, this value is obtained from the JMSMessage/header/timeToLive input parameter.
JMSMessageID
String Conditional. Unique identifier assigned to this message by the JMS provider.
JMSPriority
java.lang.Integer Conditional. Defines the message priority. The JMS standard defines priority levels from 0 to 9, with 0 as the lowest priority and 9 as the highest.
Note:
When sending a message, this value is obtained from the JMSMessage/header/priority input parameter.
JMSReplyTo
Object Conditional. Specifies the destination to which a response to this message should be sent.
JMSTimestamp
java.lang.Long Time at which the message was given to the JMS provider.
JMSType
String Conditional. Message type identifier specified by the client when sending the message.
properties
Document Conditional. A Document containing optional fields added to the message header. Integration Server adds the following properties to JMS messages it sends.
Key
Description
activation
String Conditional. A unique identifier assigned by the sender. A JMS trigger can join together messages with the same activation.
uuid
String Conditional. A universally unique identifier for the message assigned by the sender. Integration Server can use the uuid for exactly-once processing or for request/reply.
body
Document Conditional. A Document containing the JMS message body. Integration Server supports the following formats for the JMS message body:
Key
Description
string
String Conditional. Message body in the form of a String.
bytes
primitive type Conditional Message body in the form of a one-dimensional byte array.
object
Object. Conditional. Message body in the form of a Serializable Java object.
data
Document Conditional. Message body in the form of a document (IData object).
Note:
This message format can only be used when sending a JMS message from one Integration Server to another. When the JMS message is sent, the sending Integration Server encodes the IData into a byte array. When the receiving Integration Server receives the message, it decodes the byte array into IData.
message
Object Conditional. Message body in the form of an actual javax.jms.Message.
Usage Notes
The pub.jms:sendBatch service can be used with webMethods Broker or Universal Messaging only. If you set the connectionAliasName parameter to a JMS connection alias that uses a different JMS provider, the pub.jms:sendBatch service ends with an exception.
The pub.jms:sendBatch service creates multiple JMS messages (javax.jms.Message) based on input provided to the service or takes existing JMS messages and sends them to the JMS provider.
Sending a batch of messages using the pub.jms:sendBatch service is an all or nothing operation. If Integration Server or the JMS provider determines that one of the messages is not valid during a pre-processing check, none of the messages will be sent. Make sure to code your service to handle this possibility.
When Integration Server executes a pub.jms:sendBatch service that uses a transacted JMS connection alias, Integration Server sends the messages as part of a transaction. If a transaction has not yet been started, the transaction manager starts a transaction context for an implicit transaction A JMS connection alias is considered to be transacted when it has a transaction type of XA TRANSACTION or LOCAL TRANSACTION.
You can add properties to a JMS message when building a flow service that invokes this service. To add a new property, use the Pipeline to add a new variable to JMSMessages/properties document.
If the JMS connection alias specified for connectionAliasName uses the native webMethods API, you need to specify destinationName and destinationType to indicate where the webMethods Broker should send the message.
If you specify a destination that does not exist in the JNDI namespace and the JMS connection alias specified for the connectionAliasName input parameter is configured to create administered objects on demand, Integration Server creates the destination when the service executes. The ability to create administered objects on demand applies only when is the JMS provider. For more information about creating administered objects on demand, see Creating Administered Objects.
Integration Server creates the output parameter JMSMessages because some of the header fields in a JMS message are populated by the JMS provider after the message is sent. For example, the header field JMSMessageID is not in the JMS message sent by Integration Server, but JMSMessageID is in the header after the JMS provider receives the message.
Each JMS connection alias can be configured to have its own 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). If you want to use the client side queue with the pub.jms:sendBatch service, the JMS connection alias specified for connectionAliasName must be configured to have a client side queue. If the JMS connection alias is configured to use a client side queue and useCSQ is set to true, Integration Server places messages in the client side queue if the JMS provider is not available at the time the pub.jms:sendBatch service executes. When the JMS provider becomes available, Integration Server sends messages from the client side queue to the JMS provider.
If the client side queue is not used (useCSQ is set to false or the JMS connection alias is not configured to have a client side queue), Integration Server throws an ISRuntimeException if the JMS provider is not available when this service executes. Make sure to code your service to handle this situation.
When sending a message as part of a transaction, the client side queue cannot be used. The useCSQ field should be set to false. If useCSQ is set to true, Integration Server throws a JMSSubsystemException when the pub.jms:send service executes. A JMS message is sent as part of a transaction if the JMS connection alias specified in connectionAliasName uses a transaction type of LOCAL_TRANSACTION or XA_TRANSACTION.
The JMS provider populates the header fields in the JMSMessages output parameter after it successfully receives the sent message from Integration Server. If the JMS provider is not available at the time pub.jms:sendBatchexecutes and useCSQ is set to true, the header fields in the output JMSMessages will not be populated. Instead these fields will be blank or be set to 0 (zero).
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, which will create a javax.jms.Message. See:
*com.wm.app.b2b.server.jms.producer.ProducerFacade.createBytesMessage(String)
*com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String)
*com.wm.app.b2b.server.jms.producer.ProducerFacade.createObjectMessage(String)
*com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String)
*com.wm.app.b2b.server.jms.producer.ProducerFacade.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.
When creating 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:sendservice that you use to send the message. If you set the message headers and properties both ways, the values provided to the pub.jms:sendservice take precedence.
Software AG recommends that you use a pub.jms:sendBatch service to create and send the JMS message. This may provide better performance on average. However, 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 send a StreamMessage, create a Java service that calls com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String).The Java service calling this API must return an Object of type javax.jms.Message. Map the javax.jms.Message object to the JMSMessage/body/message input parameter of the pub.jms:send service.
To send a MapMessage, create a Java service that calls com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String).The Java service calling this API must return an Object of type javax.jms.Message. Map the javax.jms.Message object to the JMSMessage/body/message input parameter of the pub.jms:send service.
When using Universal Messaging as the JMS provider, the JMS client can use synchronous or asynchronous publishing. To ensure delivery of a persistent JMS message (deliveryMode is set to PERSISTENT), Integration Server always uses synchronous publishing to send a persistent JMS message to Universal Messaging.