- Points to Note
- JMS Connection Configuration
- Receive Configuration
- Message Type Settings
- Destination Settings
- Error Handling
- Functional Demonstration
- Useful Tips
The JMSOut component is used to retrieve messages from a JMS destination (topic or queue). The JMSOut component can work either in synchronous or asynchronous mode to fetch the messages from the configured destination.
This component can be used to receive Text, Bytes or Map messages. The only restriction on Map Messages is that this component does not support Objects in Map Messages.
Points to Note
- The JMS providers supported are Fiorano MQ, BEA Weblogic and JBoss. For working with these JMS providers the jars that should be explicitly added as resources to the component are given below:
- BEA WebLogic:
- %BEA_HOME%\server\lib\wljmsclient.jar (required only when the Weblogic server is running on a remote machine)
%BEA_HOME%\server\lib\wlthint3client.jar (required only when the Weblogic server is running on a remote machine)
- Oracle AQ:
- %ORACLE_HOME%\rdbms\jlib\aqapi13.jar (If JDK1.2 / JDK1.1 is used, aqapi12.jar/aqapi11.jar has to be used respectively)
Along with the JBoss jars mentioned above, add the below jars as well:
- BEA WebLogic:
JMS Connection Configuration
JMS Connection configuration details can be specified in this panel.
Figure 1: JMS Connection Configuration in the CPS
Use specific client ID
Select this option to specify a user defined Client ID. If it is not selected, client ID is generated automatically at runtime.
The client ID that will be set on the connection with the MQ server.
The details corresponding to the retrieval of messages from the server can be configured in this panel.
Figure 2: Receive Configuration CPS
Message Type Settings
Message Type Configuration
To set Message Definition Configuration in the dialog box, click the button on the right side of the property.
Figure 3: Message Definition Configuration dialog box
Byte Message as Text
Use this option when the destination is "AMQP" Destination in case of RabbitMQ JMS Provider.
Use XML Interface
Select this option if the message that is received has to be converted to XML format before sending to the output port of the component.
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 MapMessage 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.
- Byte Message as Text - When the destination is "AMQP" Destination and if the message contains XML content, then this option should be chosen to receive the AMQP message.
Figure 4: Message Type properties
- ADT Messge: This option is available only when the JMS provider is selected as "OracleAQ". An AdtMessage object is used to send a message that contains a Java object that maps to an Oracle object type. These objects inherit from the message and add a body containing a Java object that implements the CustomDatum or ORAData interface.
To use AdtMessage objects, create the queue table with payload type as the Oracle object type. In order to access the ADT payload, wrapper classes have to be created for the Oracle object type using JPublisher utility of oracle.
JPublisher enables specifying and customizing the mapping of SQL object types, object reference types, and collection types (VARRAYs or nested tables) to Java classes in a strongly typed paradigm. JPublisher generates getXXX() and setXXX() accessor methods for each attribute of an object type.
Follow the link mentioned below to create Java wrapper classes using JPublisher:
JPublisher will create the wrapper classes named ObjectType.java and ObjectTypeRef.java. After that, add a method called getData() in ObjectType.java that returns the String content of the attributes present in ObjectType class. The getData() method is used to create the output message. Compile these java files and build the jar.
If the JMSProvider selected is OracleAQ and the message type selected is ADT_MESSAGE, then the above-built jar must be added to the resources of the system library JMSCommon.
Include JMS Headers
This option can be selected to include JMSHeader information of the 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 the figure.
Figure 5: Output Schema
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.
Remove Properties with null value
If this option is checked, header properties with null value will be excluded in the Output message retrieved from the JMS server.
Depending on the type of 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 fields
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.
Figure 6: Message Definition Configuration dialog box with Message Type - 'Map Message'
- 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.
Figure 7: Message Definition Configuration dialog box with Message Type - 'Stream Message'
- ADT Message – Classpath
This option can be used to retrieve the content of ADT Message. The classpath of the class to be used from the jar should be specified in the ClassPath textbox. ClassPath field is used to extract the getFactory() and getData() methods of the wrapper class at runtime.
Figure 8: Message Definition Configuration dialog box with Message Type - 'ADT Message'
To set the Destination Configuration in the dialog box, click the button on the right side of the property.
The name of the destination from which the messages have to be retrieved.
Please refer the descriptions for rest of the attributes in the respective sections in JMSIn5.0 page.
To set the Consumer Configuration in the dialog box, click the button on the right side of the property.
Figure 9: Consumer configuration details
The message selector for the messages to be received by the consumer.
This option has to be chosen if a durable subscriber has to be created on the destination.
Figure 10: 'Is Durable' option selected
The name of the subscription corresponding to the durable subscriber that is created by the component.
- ASYNCHRONOUS: When this option is selected, the component retrieves messages asynchronously by registering a listener to the destination.
- SYNCHRONOUS: When this option is selected, the component retrieves messages when a message is sent on to the input port. Selecting this option enables the property "Should wait"
If this option is selected, the component waits for the time specified by the property "wait time" for the retrieval of messages.
Figure 11: Should Wait option selected after selecting Synchronous option
The time in milliseconds for which the component waits for the message after sending request in synchronous mode.
Action when message is not available
The action that has to be taken if the message is not available on the destination in case of Synchronous mode.
If Should Wait is enabled in Consumer Configuration, the component waits for the specified timeout before taking the chosen action. Otherwise the action will be done immediately.
Figure 12: Options of Actions available after choosing Synchronous mode
The actions which can be chosen are:
- 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.
The actions that have to be taken in case of different kinds of errors can be configured in the third panel, that is, Error Handling panel.
Figure 13: Error Handling configuration
The component is configured to receive message from "PrimaryQueue" in Asynchronous mode. Display component is connected to the component to check the response.
Figure 14: Display component connected to JMSOut
Figure 15: Output response in Display window after running the Event Process
- 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.
- IsDurable property is disabled in Consumer Configuration
- Subscription name is changed.
- Response Destination Type is changed from Topic to Queue
- ClientID is changed
If the "use specific client ID" is selected in Connection Configuration step, a Confirmation dialog box appears prompting you whether the Durable Subscription has to be removed or not. You may select "Yes" and then give the admin credentials to remove the previous Durable Subscription.
Figure 16: Confirmation dialog box
Otherwise, the subscription has to be removed manually. For more information on unsubscribing, please refer to the Durable Subscribers section in the FioranoMQ documentation.