Integration Server 10.11 | Built-In Services Reference Guide | JMS Folder | Summary of Elements in This Folder | pub.jms:receive
 
pub.jms:receive
WmPublic. Receives a message from a queue or topic on the JMS provider.
Input Parameters
consumer
Object A message consumer object that the session uses to receive messages sent to the specified destination.
timeout
java.lang.Long Specifies the time to wait, in milliseconds, for a message to be received from the JMS provider.
If you specify 0 (zero), the service will not wait.
The default is 0 (zero).
Output Parameters
JMSMessage
Document A document (IData) containing the JMS message received by the consumer.
Key
Description
header
Document. Conditional. A Document containing the header fields for the received message.
Key
Description
JMSCorrelationID
String. Conditional. A unique identifier used to link multiple messages together. Often, a JMSCorrelationID is used to link a reply message with its requesting message.
JMSDeliveryMode
java.lang.Integer. Conditional.Delivery mode specified at the time the message was sent.
PERSISTENT indicates the JMS provider places the message in a persistent message store, allowing the message to be recovered in the event of a resource failure.
NON-PERSISTENT indicates the JMS provider does not place the message in a persistent store. The message has no guarantee of being delivered if the JMS provider fails.
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.
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.
JMSRedelivered
java.lang.Boolean. Conditional. Flag indicating the JMS provider delivered this message to the JMS client previously.
True indicates the message may have been delivered in the past.
False indicates the JMS provider has not delivered this message previously.
JMSReplyTo
Object. Conditional. Destination to which a reply to this message should be sent.
JMSTimestamp
java.lang.Long. Conditional. 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 may add the following properties to JMS messages it receives.
Key
Description
JMSXDelivery Count
java.lang.Integer. Conditional. Specifies the number of times the JMS provider delivered the message. Most JMS providers set this value.
JMS_WMCluster Nodes
String. Conditional. Name of the Broker or Brokers in the Broker cluster that received the JMS message.
The Broker Server acting as the JMS provider populates the JMS_WMClusterNodes parameter after it distributes the JMS message to the Broker or Brokers in the Broker cluster.
The JMS_WMClusterNodes value will be null when:
*The JMS provider is not the Broker Server.
*The JMS connection alias used to send the JMS message does not use a cluster connection factory to obtain the connection to the Broker Server.
*The cluster connection factory does not permit a policy to be overridden.
activation
String. Conditional. A unique identifier assigned by the sending service. A JMS trigger uses the activation value to determine if a message satisfies a join.
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 (IData) contenting 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.
Note:
When the JMS message is received using the pub.jms:receive service this field will always be populated because javax.jms.Message is required for acknowledging the message.
Note:
When receiving a javax.jms:MapMessage or javax.jms:StreamMessage this field will be populated. The data can then be processed using a Java service. A flow service cannot process the message in its current state.
Usage Notes
Use this service to receive a message from the JMS provider on demand. Receiving a message on demand provides more control over when and how Integration Server receives a message; however, it may not be as efficient or practical as using a JMS trigger to listen for and then receive the message.
To listen for messages and receive them when they are available, create a JMS trigger that listens to the destination. For more information about creating a JMS trigger, see the webMethods Service Development Help.
If the timeout period elapses before a message is received, the value of JMSMessage is null.
The message consumer that you use to receive the message determines the destination from which this services receives messages and the JMS connection alias used to receive the messages. You can create a message consumer object using the pub.jms:createConsumer service.
After you receive a message, you need to invoke a service that processes the message.
If the acknowledgment mode of the consumer is set to CLIENT_ACKNOWLEDGE, use the pub.jms:acknowledge service to acknowledge the message to the JMS provider.
See Also
pub.jms:acknowledge
pub.jms:createConsumer