How to Actively Receive a JMS Message
The following describes the general steps you take to build a service that receives a message from the JMS provider.
1. Create a new service.
2. Invoke a pub.jms:createConsumer.
This service creates a message consumer that receives messages sent to a particular destination.
Use the following steps to create the message consumer.
a. Specify the JMS connection alias.
The JMS connection alias indicates how Integration Server connects to the JMS provider.
Name | Description |
connectionAliasName | Name of the JMS connection alias that you want to use to receive the message. |
b. Specify the destination from which you want to receive the message.
Specify the messages that you want the consumer to receive by selecting a destination and by creating a message selector. A message selector is a filter that the JMS provider evaluates. If a message does not meet the criteria specified in the filter, the consumer does not receive the message. Use a message selector to receive a subset of messages from a destination.
Name | Description |
destinationName | Name or lookup name of the Destination from which you want to receive 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. If the JMS connection alias you specified in step 2a 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. |
messageSelector | Optional. Specifies a filter used to receive a subset of messages from the specified destination. The message selector must use the message selector syntax specified in the Java Message Service standard. For more information about message selectors, see webMethods Service Development Help. |
durableSubscriberName | Optional. Name of the durable subscriber that you want this service to use on the JMS provider. A durable subscriber creates a durable subscription on the JMS provider. If a durable subscriber of this name already exists on the JMS provider, this service resumes the previously established subscription. Note:
This parameter only applies when the destinationType is set to TOPIC. If you select TOPIC, but do not specify a durableSubscriberName, this service creates a nondurable subscriber. If destinationType is set to QUEUE, this parameter is ignored. |
c. Determine the acknowledgment mode.
Acknowledgment mode indicates how Integration Server acknowledges messages received by a message consumer.
Use the following parameter to specify the acknowledgment mode.
Name | Description |
acknowledgmentMode | AUTO_ACKNOWLEDGE Automatically acknowledge the message when it is received by the message consumer. The message consumer will acknowledge the message before the message processing completes. The JMS provider cannot redeliver the message if Integration Server becomes unavailable before message processing completes. CLIENT_ACKNOWLEDGE Acknowledge the receipt of a message when the JMS client explicitly acknowledges it. In this case, acknowledge the message when Integration Server invokes the pub.jms:acknowledge service. DUPS_OK_ACKNOWLEDGE Automatically, lazily acknowledge the receipt of messages, which reduces system overhead but may result in duplicate messages being sent. The default is AUTO_ACKNOWLEDGE. |
d. Indicate whether locally published messages are ignored.
If you specified TOPIC as the destinationType, you can configure a consumer to ignore messages published using the same JMS connection alias used by the consumer.
Integration Server considers a message to be local if it is:
Sent by the same
Integration Server, and
Sent using the same JMS connection alias.
Name | Description |
noLocal | Indicates whether the consumer ignores locally published messages: True indicates the consumer will not receive locally published messages. False indicates the consumer can receive locally published messages. The default is False. |
3. Invoke pub.jms:receive.
This service uses the consumer created by the pub.jms:createConsumer service to receive messages from the specified destination.
In the Pipeline view, make sure the consumer created by the pub.jms:createConsumer service is linked to the pub.jms:receive service input parameter consumer. Designer should link these automatically.
Specify how long the consumer should wait to receive a message from the JMS provider.
Name | Description |
timeout | Specifies the time to wait, in milliseconds, for a message to be received from the JMS provider. If you specify 0 (zero), the consumer will not wait. The default is 0 (zero). |
4. Process the received JMS message.
Invoke a service or a sequence of services to process the message received from the JMS provider. In the Pipeline view, link the JMSMessage returned by pub.jms:receive to the input for the service that processes the message.
If the timeout period elapses before a message is received, the value of JMSMessage is null. Make sure to code your service to handle this situation.
5. Invoke pub.jms:acknowledge.
If the acknowledgment mode of the consumer that received the message is set to CLIENT_ACKNOWLEDGE use the pub.jms:acknowledge service to acknowledge the message to the JMS provider. A message is not considered to be successfully consumed until it is acknowledged.
Provide the following input parameter.
Name | Description |
message | A javax.jms.Message object that identifies the message for which you want Integration Server to send an acknowledgement to the JMS provider. You can map the value of the JMSMessage/body/message field in the JMS message retrieved by the pub.jms:receive service to this field. |
If you use the consumer created by the pub.jms:createConsumer service to receive multiple messages, keep in mind that acknowledging a message automatically acknowledges the receipt of all messages received in the same session. That is, all messages received by the same consumer will be acknowledged when just one of the received messages is acknowledged. Therefore, if the consumer receives multiple messages, invoke the pub.jms:acknowledge service after processing all of the received messages.
Any message consumers created during the execution of a service will be closed automatically when the service completes. If the consumer closes without acknowledging messages, messages are implicitly recovered back to the JMS provider.