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\wlclient.jar 
    • %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)

      Icon

      For BEA Weblogic 10.3, %BEA_HOME% refers to <BEA WebLogic Installation directory>\wlserver_10.3.

  • Oracle AQ:
    • %ORACLE_HOME%\rdbms\jlib\aqapi13.jar (If JDK1.2 / JDK1.1 is used, aqapi12.jar/aqapi11.jar has to be used respectively)
    • %ORACLE_HOME%\jdbc\lib\ojdbc14.jar

    • %ORACLE_HOME%\jdbc\lib\nls_charset12.jar

      Icon

      For Oracle Database 9.2.0.1.0, %ORACLE_HOME% refers to <Oracle Installation directory>\ora92

  • JBoss
    • %JBOSS_HOME%\client\jnp-client.jar
    • %JBOSS_HOME%\client\jboss-common-client.jar
    • %JBOSS_HOME%\client\jbossmq-client.jar
    • %JBOSS_HOME%\client\jboss-client.jar
  Icon

  • If jars mentioned above are added to resources of the System library JMSCommon, the jars will be available for JMSIn 5.0, JMSOut 5.0 & JMSRequestor 5.0 components. To perform this, refer Add Resources to a Microservice section.
  • In case of BEA Weblogic, InitialContext can be created by specifying empty values for JNDI Username and JNDI password as well.
  • 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.
  • To save a specific configuration for further use, Named Configuration option is available in JMS Connection Configuration properties as well as Send Configuration properties. Please refer the Named Configurations in CPS section in Common Configurations page to understand the procedure to save a Named Configuration.

Configuration

JMS Connection Configuration

JMS Connection configuration details can be specified in this panel.

Figure 1: JMS Connection Configuration in the CPS

Connection Properties

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.

Client ID

The client ID that will be set on the connection with the MQ server.

Receive Configuration

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

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.

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 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.

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.

Figure 4: Output Schema

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.

Remove Properties with null value

If this option is checked, header properties with null value will be excluded in the Output message retreived from JMS server.

Message Content

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 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 5: 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 6: Message Definition Configuration dialog box with Message Type - 'Stream Message'

Destination Settings

Destination Configuration

To set the Destination Configuration in the dialog box, click the button on the right side of the property.

Destination Name

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.

Consumer Configuration

To set the Consumer Configuration in the dialog box, click the button on the right side of the property.

Figure 7: Consumer configuration details

Message Selector

The message selector for the messages to be received by the consumer.

Is Durable

This option has to be chosen if a durable subscriber has to be created on the destination. 

Figure 8: 'Is Durable' option selected

Subscription Name

The name of the subscription corresponding to the durable subscriber that is created by the component.

Delivery Mode

• 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"

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 9: Should Wait option selected after selecting Synchronous option

Wait time

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 10: 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.

Error Handling

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 11:  Error Handling configuration

Please refer JMSIn5.0 section for details.

Functional Demonstration

Scenario

The component is configured to receive message from "PrimaryQueue" in Asynchronous mode. Display component is connected to the component to check the response.

Figure 12:  Display component connected to JMSOut

Sample Output

Figure 13: Output response in Display window after running the Event Process

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.
  • IsDurable property is disabled in Consumer Configuration
  • Subscription name is changed.
  • Response Destination Type is changed from Topic to Queue
  • ClientID is changed
  Therefore the previous subscription has to be removed to avoid persisting messages in runtimedata.
  
  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 14: Confirmation dialog box
  
  Otherwise, the subscription has to be removed manually. For more information on unsubscribing, please refer to Chapter 32.3 Connecting to Web Management Tool - DurableSubscribers view) in FioranoMQ Handbook.