The JMSRequestor component is used to send messages to a JMS Topic/Queue and wait till a message reply is received from the same. After sending the message to the Destination set in the CPS, JMSRequestor waits for the response message on the Response Destination. If Response Destination is not specified in the CPS, then a temporary destination is created on which the response message is expected. User can also specify an Error Destination on which JMSRequestor receives the error message.
Points to Note
The same points as mentioned in the JMSIn5.0 section applies for JMSRequestor 5.0 too.
Configuration
JMS Connection Configuration
Connection configuration details can be specified in this panel.
Requestor Configuration
Message Type Settings
Message Type Configuration
Click the Message Type Configuration ellipsis button to provide the configuration details.
Use XML Interface
This option has to be chosen if the component needs an XML interface. If this is not selected, schema will not be set on input port of the component and the message received on the input port will be sent to the destination as it is.
Message Type
The type of the message that needs to be sent can be chosen as one of the following.
- Text message - Use this option to send a plain text message.
- Map message - A Map Message object's message body contains a set of name-value pairs, where names are String objects, and values are Java primitives. The entries can be accessed sequentially or randomly by name. The order of the entries is undefined.
- Stream message - A Stream Message object's message body contains a stream of uninterrupted bytes. This message type is for literally encoding a body to match an existing message format.
Include JMS Headers
This option can be selected to set the JMSHeaders on the message at runtime.
When this option is selected, the fields JMSCorrelationID and JMSDestination will be generated in the input schema of the component.
Include Properties
This option can be selected to set the JMS properties on the message at runtime.
When this option is selected, the elements "ApplicationContext" and "Property" (ZeroMany) are generated in the input schema of the component.
The properties and application context can be set as shown below.
Message type
Depending on the Message Type selected, the appropriate parsing option is shown. Message Type and the corresponding parsing options are explained below.
Text message – XML Content: Select this option if the content of the input message conforms to a specific schema. The schema can be specified using the schema editor.
Map message – Define Body: Select this option to define the body fields of the Map message. The message body fields (name and type of the field) can be added in the table and the input schema will be generated corresponding to the each field defined.
Stream message – Parse Body: Select this option to set the content of the stream message in input XML. The name, type and length of the field can be added in the table. An element will be added to the schema corresponding to each field with the same name.
Output Message Configuration
Use XML Interface
Select this option if the response message has to be converted to XML format before sending to the output port of the component.
Message type
The type of the message that has to be received can be chosen as one of the following.
- Text message - Use this option to receive a plain text message.
- Map message - A Map Message object's message body contains a set of name-value pairs, where names are String objects, and values are Java primitives. The entries can be accessed sequentially or randomly by name. The order of the entries is undefined.
- Stream message - A Stream Message object's message body contains a stream of uninterpreted bytes. This message type is for literally encoding a body to match an existing message format.
Include JMS Headers
This option can be selected to include JMSHeader information of message in the output XML. An element "JMSHeader" will be added to the output schema and all relevant JMS headers appear as child elements in the output schema as shown in figure.
Include Properties
This option can be selected to retrieve the JMS properties on the message.
When this option is selected, the elements "ApplicationContext" and "Property" (ZeroMany) will be generated in the schema of output port.
Depending on the type of the message, the parsing of the message content can be chosen.
- Text message – XML Content: This option can be chosen if the content of the output message conforms to a specific schema. The schema can be specified using the schema editor. This schema will be set as the schema of the body element. Setting the schema enables doing necessary transformations.
- Map message – Define Body: This option can be chosen to retrieve the body fields of the map message. The message body fields (name and type of the field) can be added in the table and the output schema will be generated corresponding to the each field defined.
- Stream message – Parse Body: This option can be chosen to retrieve the content of the stream message. The name, type and length of the field can be added in the table. An element will be added to the schema corresponding to each field with the same name.
Request Configuration
Request destination configuration
The details of the destination to which the request message from input port has to be sent can be configured using the Request configuration tab.
Destination Name
The name of the destination to which the messages have to be sent.
Destination Type
The JMS type of the destination. This can be chosen as either Topic or Queue.
Lookup Destination
This option can be chosen if the destination is already present and needs to be looked up using JNDI.
AutoCreate Destination
This option has to be chosen if the destination has to be created, if it doesn't exist.
Destination specified for the property Destination Name should already exist if BEA Weblogic/Oracle AQ is being used. Dynamic creation of destinations is not supported for these providers.
For BEA Weblogic, value for Destination Name should be the JNDI name of the destination. Example: weblogic.examples.jms.exampleTopic.
In case of Oracle AQ, to grant user necessary previliges and to create a sample Topic(MY_TOPIC1)/Queue(MY_QUEUE1), execute following queries in Oracle DB configured in CPS:
To Grant Permissions:
- CONNECT SYSTEM
- grant create session to [USER]
- grant connect, resource, aq_administrator_role to [USER] identified by [USER];
- grant execute on sys.dbms_aqadm to [USER];
- grant execute on sys.dbms_aq to [USER];
To Create Queue:
- CONNECT [USER]
- EXEC dbms_aqadm.create_queue_table (queue_table=>'MY_QUEUE1', queue_payload_type=>'sys.aq$_jms_text_message', multiple_consumers=>false );
- EXEC dbms_aqadm.create_queue(queue_name=>'MY_QUEUE1', queue_table=>'MY_QUEUE1');
- EXEC dbms_aqadm.start_queue(queue_name=>'MY_QUEUE1');
To Create Topic:
- CONNECT [USER]
- EXEC dbms_aqadm.create_queue_table(queue_table=>'MY_TOPIC1', queue_payload_type=>'sys.aq$_jms_text_message', multiple_consumers=>true);
- EXEC dbms_aqadm.create_queue(queue_name=>'MY_TOPIC1', queue_table=>'MY_TOPIC1');
- EXEC dbms_aqadm.start_queue(queue_name=>'MY_TOPIC1');
Producer Configuration
Delivery Mode
- PERSISTENT: The PERSISTENT delivery mode, instructs the JMS provider to take extra care to ensure that a message is not lost in transit in case of a JMS provider failure. A message sent with this delivery mode is logged to stable storage when it is sent.
- NON-PERSISTENT: The NON_PERSISTENT delivery mode does not require the JMS provider to store the message or otherwise guarantee that it is not lost if the provider fails.
Priority
The priority of the message to be sent to the destination.
Time to Live
The time to live (in milliseconds) of the message to be sent to the destination. After the timeout the message will be discarded.
Response Configuration
Response Destination Configuration
The details of the destination to which the response is sent can be specified here.
Destination Name
The name of the destination on which the response for the request will be received. This is optional. If the destination name is not defined, then a temporary destination will be created and will be set as the JMSReplyTo Destination on the request message. The type of the temporary destination created will be same as the type of the request destination.
Destination Type
The JMS type of the destination. This can be chosen as either Topic or Queue. This option is relevant only when the destination name is not empty.
Lookup Destination
This option can be chosen if the destination is already present and needs to be looked up using JNDI.
AutoCreate Destination
This option has to be chosen if the destination has to be created.
Error Destination Configuration
The details of the destination to which the errors are sent can be specified here.
Destination Name
The name of the destination on which the errors occurred after sending the message will be received. This is optional. If the destination name is not defined, then a temporary destination will be created whose type is same as the type of the request destination.
Destination Type
The JMS type of the destination. This can be chosen as either Topic or Queue. This option is relevant only when the destination name is not empty.
Lookup Destination
This option can be chosen if the destination is already present and needs to be looked up using JNDI.
AutoCreate Destination
This option has to be chosen if the destination has to be created.
Error Port Enabled
If this property is enabled, a new ERRORDEST_PORT will be created and all messages from Error Destination will be sent through ERRORDEST_PORT instead of OUT_PORT.
If this property is disabled, all Error messages will be sent through OUT_PORT as usual.
Consumer Configuration
The details of the consumers that has to be created for the response and error destinations can be configured here. The configuration provided is relevant only when destination name is provided either for response destination or error destination.
Message Selector
The message selector for the messages to be received by this consumer. More information on message selectors is available at
http://java.sun.com/j2ee/sdk_1.3/techdocs/api/javax/jms/Message.html]http://java.sun.com/j2ee/sdk_1.3/techdocs/api/javax/jms/Message.html
Is Durable
This option has to be chosen if a durable subscriber has to be created on the destination.
Subscription Name
The name of the subscription corresponding to the durable subscriber that is created by the component.
Additional Settings
Requestor ID
The ID specific to an instance of requestor. This is used to set the message selector on the response destination. Providing a value is optional. If no value is provided then a unique requestor ID will be automatically generated by the component.
Match Response
This option has to be chosen if the response that is received from the response destination has to be matched with the request that is sent based on the header JMSCorrelationID. Choosing this option enables the property "CorrelationID prefix".
CorrelationID prefix
The String that has to be prefixed to the correlationID that is generated. Providing value is optional. If no value is provided, a default value "Correlation_" will be generated and used by the component.
Execution Timeout
The time in milliseconds for which the component has to wait for a response from the response destination after sending a request. A value of 0 indicates infinite timeout.
Action when message is not available
The action that has to be performed when no message is received within the timeout specified by the property "Execution Timeout".
The action can be chosen as one of the following
- EMPTY_MESSAGE_ACTION: An empty message is sent onto the output port of the component.
- NO_ACTION: Nothing is done if no message is received.
- ERROR_ACTION: The situation will be treated as a request execution error and action will be taken based on the configuration of Error Actions defined in Additional Configuration page.
Error Handling
Validate Input: This option has to be chosen if the input message has to be validated against the schema that is set on the input port.
Target namespace: The target namespace of the schema can be provided here. The schema on ports will be suffixed with the component name and type of the port. Eg. /JMSIn/In
Error Handling Configuration: The actions that have to be taken in case of different kinds of errors can be chosen using this panel.
Functional Demonstration
Scenario
Sending a request from JMSRequestor to the JMSReplier. If successful, the plain text message gets processed as output from JMSReplier back to JMSRequestor.
The component is configured to send messages to "PrimaryTopic". A replier is used to resend the request that is sent to it.
Sample Input
Below is the sample generated from the Feeder.
Sample Output
After running the Event Process, output will be displayed in the Display component if the message is successfully sent.
Useful Tips
- When using the Durable Subscriber mode, each message has to be stored by the JMS server either in the database or the file system depending on the vendor before delivery of message to consumer and removed after delivery of message. This has a huge impact on the performance. So as far as possible restrict the use of durable delivery mode unless it is necessary for your application to avoid the overheads involved.
- The durable subscription created by this component earlier will become unnecessary if the following gets changed while reconfiguring the component.
- Is Durable property is deselected in Consumer configuration; Subscription name is changed.
- Response Destination Type property is changed from 'Topic' to 'Queue'; ClientID is changed.
Therefore the previous subscription has to be removed to avoid persisting messages in runtimedata.
In JMS Connection Configuration, if the Use specific client ID property is enabled under Connection Properties, a dialog Confirm will appear prompting the user if the durable subscription has to be removed. The user can select "Yes" and then give the admin credentials to remove the previous durable subscription.
Otherwise, the subscription has to be removed manually.