Subscribe-Queue
Registers an event handler that is called by the MOM implementation when a message arrives in the specified queue.
|
|
This webject can be used only after your environment has been set up for queuing tasks.
|
SYNTAX
<ie:webject name=Subscribe-Queue type="MSG">
<ie:param name="DBUSER" data="username"/>
<ie:param name="EXECUTE_TASK" data="task_name"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="QUEUE" data="managed_queue_name"/>
<ie:param name="WHERE" data="jms_message_selector"/>
<ie:param name="MAX_CONCURRENCY"="managed_receiver_generation"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
|
DBUSER
|
|
|
SERVICE
|
|
|
EXECUTE_TASK
|
|
|
PASSWD
|
|
|
QUEUE
|
|
|
WHERE
|
|
|
MAX_CONCURRENCY
|
DBUSER
The username to use when connecting to the MOM. If this parameter is specified, the parameter value takes precedence over any existing credentials mapping for the authenticated user, or any value specified in the .msg.username and .jms.username properties of the service that is used to connect to the MOM.
If this parameter is omitted, the mapped credentials for the Info*Engine messaging software are used. If no such mapping is found, then the mapped credentials for the Java Messaging Service (JMS) are used. If neither of these mapped credentials are found, then the value set in the .msg.username property is used. If the .msg.username property is not set, then the value set in the .jms.username property is used. If neither property is set and you do not specify a value for this DBUSER parameter, Info*Engine does not specify a username when connecting to the MOM, and an anonymous connection is attempted.
This parameter is optional.
EXECUTE_TASK
The task to be executed when a message is received in the subscribed queue. If the incoming message does not contain a task to execute, then the task specified on this parameter is run.
If EXECUTE_TASK is not specified, then the subscription can only handle Info*Engine requests on its queue. Other incoming messages are rejected. This parameter is optional.
MAX_CONCURRENCY
The number of receivers that should be generated upon queue subscription. This specifies the maximum number of messages that the Info*Engine system processes simultaneously. The default value is 1, causing messages to be processed serially.
Specifying a MAX_CONCURRENCY value greater than one means that messages that are placed in a queue are not necessarily processed in the order in which they were queued. This parameter should not be used if the order of messages is important. This parameter is optional.
|
|
Specifying this parameter does not necessarily mean that all receivers are kept busy when given a queue load. This functionality is partially dependent upon the configuration of the to which MOM you are connecting.
To illustrate this, Tibco EMS supports a queue property named “prefetch.” The default value for this property is 5, meaning that any given receiver receives five messages at a time. Based on the amount of data in a queue, this can mean that if your MAX_CONCURRENCY is too high, then certain receivers might remain idle. For example, given the default queue configuration for Tibco EMS (five messages per receiver), if there were fifteen messages in a queue and upon subscription you specified a MAX_CONCURRENCY of 4, then only three out of the four available receivers would actually be used (resulting in a real concurrency of three). Because the fifteen messages would be divided by the default prefetch value of five and distributed evenly to the first three receivers, the fourth would then be left idle. Setting a value for prefetch of 1 for the queue in question would result in all receivers staying busy, but if message sizes are typically large then this might mean that there is a lag between messages.
|
PASSWD
The password to use when connecting to the MOM. If this parameter is specified, the parameter value takes precedence over existing credentials mapping for the authenticated user, or any value specified in the
.msg.password and
.jms.password properties of the service that is used to connect to the MOM. For more information, see
Credentials Mapping for MOMs.
If this parameter is omitted, the mapped credentials for the Info*Engine messaging software are used. If no such mapping is found, then the mapped credentials for the Java Messaging Service (JMS) are used. If neither such mapped credentials are found, then the value set in the .msg.password property is used. If the .msg.password property is not set, then the value set in the .jms.password property is used. If neither property is set and you do not specify a value for this PASSWD parameter, Info*Engine does not specify a password when connecting to the MOM.
This parameter is optional.
QUEUE
The LDAP distinguished name of an administered queue. The value can be an LDAP distinguished name relative to a configured base URI or a fully qualified LDAP distinguished name. If relative, the cn= (common name attribute) is implicit if not explicitly specified. The default for this parameter is to use the value specified in the com.infoengine.msg.defaultExecutionQueue property. If there is no such value, then the QUEUE parameter must be specified. This parameter is optional.
SERVICE
The name of the Info*Engine property set that is configured for connectivity to a specific JMS service. This allows you to configure more than one JMS service per Info*Engine Virtual Machine (VM). This parameter is optional.
WHERE
A properly formatted JMS message selector, as defined in the Sun Java Message Service specification, used to select a subset of messages to execute from the specified queue. The default for this parameter is to subscribe to all messages that arrive in the queue. This parameter is optional.
EXAMPLE
The following example registers a subscription to listen to the specified queue:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Subscribe-Queue" type="MSG">
<ie:param name="QUEUE" data="$(@FORM[]queue[0])"/>
<ie:param name="WHERE" data="$(@FORM[]where[0])"/>
</ie:webject>
To actually run this example you would need to provide a form where the queue and where variables are identified.
