Integration Server 10.3 | Built-In Services Reference Guide | JMS Folder | Summary of Elements in This Folder | pub.jms:createConsumer
 
pub.jms:createConsumer
WmPublic. Creates a message consumer to receive messages from destinations on the JMS provider.
Input Parameters
connectionAliasName
String Name of the JMS connection alias that you want the message consumer to receive messages.
The JMS connection alias indicates how Integration Server connects to the JMS provider. 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.
destinationName
String Name or lookup name of the Destination from which you want the message consumer to receive 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.
destinationType
String Optional. Type of destination from which the message consumer receives messages. Specify one of the following:
*QUEUE to receive messages sent to a particular queue. This is the default.
*TOPIC to receive messages sent to a particular topic.
Note:
You need to specify a destinationType only if you specified a connectionAliasName that uses the native webMethods API.
acknowledgmentMode
String Optional. Specifies the acknowledgment mode. Specify one of the following:
*AUTO_ACKNOWLEDGE to 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. This is the default.
*CLIENT_ACKNOWLEDGE to acknowledge the receipt of a message when the JMS client (Integration Server) invokes pub.jms:acknowledge service.
*DUPS_OK_ACKNOWLEDGE to automatically, lazily acknowledge the receipt of messages, which reduces system overhead but may result in duplicate messages being sent.
messageSelector
String Optional Specifies a filter used to receive a subset of messages from the specified destination. A message selector allows a client to filter the messages it wants to receive by use of a SQL92 string expression in the message header. That expression is applied to properties in the message header (not to the message body content) containing the value to be filtered.
If the SQL expression evaluates to true, the JMS provider sends the message to the message consumer; if the SQL expression evaluates to false, the JMS provider does not send the message.
durableSubscriberName
String Optional. Name of the durable subscriber that you want this service to create 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.
noLocal
java.lang.Boolean Optional. Flag indicating whether the message consumer can receive locally published messages. Integration Server considers a message to be local if the message was:
*Sent by the same Integration Server, and
*Sent using the same JMS connection alias.
Specify one of the following values:
*True to indicate that the consumer will not receive locally published messages.
*False to indicate that the consumer can receive locally published messages. This is the default.
Note:
This parameter only applies when the destinationType is set to TOPIC.
Output Parameters
consumer
Object An on demand message consumer object used to receive messages for the specified destination.
Usage Notes
A message consumer is a webMethods object that encapsulates the actual javax.jms.MessageConsumer and javax.jms.Session.
Any message consumers created during the execution of a service will be closed automatically when the top-level service completes. If the consumer closes without acknowledging messages, messages are implicitly recovered back to the JMS provider.
The use of pub.jms:createConsumer in conjunction with pub.jms:receive is an alternative to using JMS triggers. Use the pub.jms:createConsumer service to create a message consumer. Use the pub.jms:receive to actively receive messages from a destination on the JMS provider.
To create a durable subscriber, set the destinationType to TOPIC and specify a durableSubscriberName. If you select TOPIC, but do not specify a durableSubscriberName, Integration Server creates a nondurable subscriber.
A durable subscription allows subscribers to receive all the messages published on a topic, including those published while the subscriber is inactive.
If a durable subscription already exists for the specified durable subscriber on the JMS provider, this service resumes the subscription.
A non-durable subscription allows subscribers to receive messages on their chosen topic, only if the messages are published while the subscriber is active. A non-durable subscription lasts the lifetime of its message consumer.
If the acknowledgment Mode field is set to CLIENT_ACKNOWLEDGE, you must acknowledge messages received by this consumer to the JMS provider using the pub.jms:acknowledge service.
If the message consumer created by this service will be used to receive large message streams from the webMethods Broker, make sure to specify an acknowledgmentMode of AUTO_ACKNOWLEDGE or CLIENT_ACKNOWLEDGE. If the acknowledgmentMode is DUPS_OK_ACKNOWLEDGE, the message consumer cannot be used to receive large message streams.
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.
See Also
pub.jms:acknowledge
pub.jms:receive
pub.jms:reply
pub.jms:send
pub.jms:sendAndWait