JMSOut5.0

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)

      

      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

      

      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
      
      

  • JBOSS6.0.0
    Along with the JBoss jars mentioned above, add the below jars as well:

    • hornetq-core-2.2.13.Final.jar
    • hornetq-jms-2.2.13.Final.jar
    • hornetq-ra-2.2.13.Final.jar
    • jboss-as-build-config.jar
    • jboss-ejb-api_3.1_spec.jar
    • jboss-ejb-client.jar
    • jboss-logging.jar
    • jboss-marshalling.jar
    • jboss-marshalling-river.jar
    • jboss-remote-naming.jar
    • jboss-remoting.jar
    • jboss-sasl.jar
    • jboss-transaction-api_1.1_spec.jar
    • jgroups.jar
    • netty.jar
    • xnio-api.jar
    • xnio-nio.jar

  • OpenMQ:

    • %OpenMQ_HOME%/mq/lib/fscontext.jar

    • %OpenMQ_HOME%/mq/lib/imq.jar

  • Rabbit MQ

    • amqp-client-4.1.1.jar

    • fscontext-4.5-b25.jar

    • rabbitmq-jms-client.jar

  

  • If jars mentioned above are added to resources of the System library JMSCommon, the jars will be available for all JMS components. To perform this, refer the Adding 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.
  • Refer the Creating the .bindings file section to know how to create a .bindings file for Rabbit MQ JMS Provider.

Configuration

JMS Connection Configuration

JMS Connection configuration details can be specified in this panel.

Please refer the JMSIn5.0 section for descriptions for attributes under properties Provider URL Settings, JNDI Settings and Session Properties.

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.

If user-defined client ID is used in the component and if Durable Subscription is enabled, while reconfiguring the component if the durable subscription changes, then the previously created durable subscription will also receive the messages. To avoid this, there is an option to remove the previously created Durable Subscription. Refer "Useful tips" for more details

Client ID

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

This will be used only when the option "Use specific client ID" is selected.

Receive Configuration

The details corresponding to the retrieval of messages from the server can be configured in this panel.

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.

Byte Message as Text

Use this option when the destination is "AMQP" Destination in case of RabbitMQ JMS Provider.

This option will be displayed only when JMS Provider property value is set to 'RABBIT_MQ'.

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.
• 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:
  https://docs.oracle.com/cd/E18283_01/java.112/e10587/intro.htm#insertedID1

  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.

  CODE

  public String getData() throws SQLException {
  String data = getFirstName() + "," + getLastname();
  return data;
  }

  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.

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 retrieved from the JMS server.

Message Content

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'
  

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.

If JMS Provider is "Other" (ActiveMQ), and the AutoCreate Destination property (explained below) is disabled, the Topic name and Queue name to be specified must be in the following format:

Topic name format

dynamicTopics/<TopicName>

Queue name format

dynamicQueues/<QueueName>

Consumer Configuration

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

Message Selector

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

More information on message selectors is available at 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. 

• This option appears only when the 'Destination Type' property is selected as "TOPIC" in the Destination Configuration.
• If a durable subscriber is already created by this component and the checkbox is deselected, when the CPS is finished, you are provided with an option to remove durable subscription that is created previously. This can be done by providing the administrator credentials of the JMS Server.
• Selecting this option enables you to specify the subscription name.

Subscription Name

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

This option appears only when the Destination Type is selected as "TOPIC" in the Destination Configuration and Is Durable property is enabled.

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.

This option appears only when the Delivery Mode is chosen as "SYNCHRONOUS".

Wait time

The time in milliseconds for which the component waits for the message after sending request in synchronous mode.

This option appears only when the Delivery Mode is chosen as "SYNCHRONOUS" and Should Wait option is enabled.

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.

This option appears only when the Delivery Mode is chosen as "SYNCHRONOUS".

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.

Please refer the 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.

Sample Output

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

https://www.fiorano.com/documentation/display/MQ/Web+Management+Tool+views#WebManagementToolviews-10.DurableSubscribers