The JMSOut component may be used to retrieve messages from a JMS Topic/Queue. Using the Configuration Property Sheet, you can specify the topic or queue from which the message is to be retrieved. The JMSOut component sends the JMS message received from a Topic/Queue to another component. You can create a Subscriber or a Receiver for a Topic or a Queue respectively, and configure the component to retrieve or subscribe to messages from a JMS server at runtime.

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.

JMSOut is capable of handling following types of messages:

  • Text messages: A TextMessage object's message body contains a java.lang.String object.
  • Map messages: 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.
  • Bytes Message: A BytesMessage 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.
Icon

JMSOut uses JMS APIs to process the messages.

Points to Note

  • The only restriction on Map Messages is that this component does not support Objects in Map Messages.
  • When adding the Initial Context Factory class for non Fiorano MQ server, the jar file(s) should be added as resource(s) to the JMSAdapters system library.
  • For creating Durable Subscriber, use Topic Connection Factory in place of Unified Connection Factory.
  • If IsDurableSubscriber property is changed to No or Destination Type is changed from Topic to Queue or ClientID is changed - the durable subscriptions created earlier should be unsubscribed to avoid persisting messages for the durable subscriber in runtimedata. For more information on unsubscribing, please refer to FioranoMQ Handbook - Section 29.3: Connecting to Web Management Tool - DurableSubscribers view.
  • If a timeout is not specified (left as zero – infinite), and after starting the component, the JMS server (to which the component is connected) crashes, the receive call on the Queue or Topic waits endlessly. Therefore, it is advisable to give a definite timeout value.
  • If the component is being used in scheduling mode, the execution timeout for the component should be less than the scheduler interval if the message is being received from a Queue.
  • The property 'Cleanup resources (excluding connection) after each document' is set to 'No' by default. If this is set to 'Yes', then only one message is received by JMSOut and after that resources like message consumers are closed and the component will not receive further messages.

Configuration and Testing

The JMSOut component connection related properties can be configured in the Managed Connection Factory panel of CPS.

Managed Connection Factory


Figure 1: Sample JMSOut MCF configuration

Provide URL Settings

Use Connection Details From Input

Parameters to create the connection can be specified in the input message when this property is set to true. If this property is selected the validation errors in the managed connection factory panel of the CPS are treated as warnings. So user can bypass this step without giving valid configuration and complete the configuration of the component. If valid properties are not provided even in the input message exception will be thrown at runtime.

The JMS providers supported are Fiorano MQ, BEA Weblogic, Oracle AQ, Oracle Streams AQ and JBoss. For working with these JMS providers the jars that should be explicitly added as resources to the component are given below:

JMS Provider
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

    Note: 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\classes12.zip
  • %ORACLE_HOME%\jdbc\lib\nls_charset12.jar

    Icon

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

Oracle Streams AQ
  • %ORACLE_HOME%\rdbms\jlib\aqapi.jar
  • %ORACLE_HOME%\jdbc\lib\ojdbc14.jar

    Icon

    For Oracle Database 10.2.0.1.0, %ORACLE_HOME% refers to <Oracle Installation directory>\product\10.2.0\db_1

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
Icon
  • If these jars are added to resources of the System library JMSAdapters, the jars are available for all JMS components.
  • In case of BEA Weblogic, InitialContext can be created by specifying empty values for JNDI Username and JNDI password as well.
  • When configuring JMSOut 4.0 for BEA Weblogic in scheduling mode,the colour of the component does not change to green on startup. In order to avoid this, it is necessary to add following security permission in java.policy file under {JRE_HOME}/lib/security >.The permission to be added is "grant { permission javax.management.MBeanTrustPermission "register";} "
Icon

Descriptions for the other attributes in the properties Provider URL Settings, JNDI Settings, Connection Properties, Session Properties are the same as provided in JMSIn4.0 section.

Working with Fiorano MQ HA profiles

When Configuring JMSOut with Fiorano MQ HA profiles, you should provide Intial Context Properties in Adavnced Info in the Managed Connection Factory Panel of the CPS.

These Properties are:

  • "java.naming.provider.url" set to Server URL
  • "BackupConnectURLs" set to backupURLs

Secured Connections to Fiorano MQ (SSL)

If Fiorano MQ server uses SSL, then provide the following properties in Advanced Info Under Initial Context Properties.

  • java.naming.security.protocol: Name of the security protocol used to create secure connections with the MQ server.
    • Valid value: The possible values that this variable can take are PHAOS_SSL and SUN_SSL.
  • SecurityManager(optional): The Security Manager implementation used to create secure connections [HTTPS or SSL] with the MQ server. The manager class should be an implementation of the fiorano.jms.runtime.IFMQSecurityManager interface provided by FioranoMQ.

    Icon

    If this property is not provided then, default security provider will be used.

    • Valid value: Qualified class name of security Manager class.

Interaction Configurations


Figure 3: Interaction Configurations

Destination Settings

Destination Configuration
Destination Name

Name of the topic or queue to which messages are to be transferred.

Icon

For BEA Weblogic, value for Destination Name should be the JNDI name of the destination. Ex: weblogic.examples.jms.exampleTopic.

AutoCreate Destination

If destination provided is not present, then it is created dynamically.

Icon

Destination specified for the property Destination Name should already exist if BEA Weblogic/Oracle AQ/Oracle Streams AQ is being used. Dynamic creation of destinations is not supported for these providers.

Refer the section in JMSIn4.0 page for the descriptions of remaining attributes present in Destination Configuration property.

Consumer Configuration

Click the Ellipsis  button to set the Consumer Configuration.

Icon

This option is visible only if the Destination Type property in Destination Configuration is set to "Topic".

Is Durable

This property is used to create a durable subscription when the destination type is Topic.


Figure 4: Option to configure Consumer Configuration in the dialog box

Subscription Name: Provide a unique Subscription Name for durable subscriber.

Icon

Refer the respective sections in JMSIn4.0 page for descriptions on the properties Retain Application Context, Monitoring Configuration and Message Type Configuration.

Expert Properties

Most of the Expert Properties are present in Common Configurations page. The ones that are unique for JMSOut component are mentioned below.

Action when message is not available?


Figure 5: Option to configure when message is not available

This property specifies the action to be taken when there are no messages on the queue within the timeout specified.

  • Send Empty Message
    An empty message is sent to output port.
  • Treat as Exception
    An exception message is sent to error port and no message is sent to output port.
  • No Action
    No message is sent to either output port or error 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 JMS server.

Execution Timeout

Maximum time in milliseconds the component should wait for a message. Default value is 0 which specifies infinite wait time that is, waits until a message is received.

Testing the Connection

Server connection can be tested from within the CPS by clicking on test in the Managed Connection Factory panel.


Figure 2: Sample connection test result indicating success

Sample JMSOut configuration

The JMSOut component can be configured using its Custom Proper Sheet wizard.

Destination specified for the property Destination Name should already exist if BEA Weblogic/Oracle AQ/Oracle Streams 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.

Below configuration can be tested from within the CPS by clicking on test button in the CPS panel:

Destination Configuration
Destination Name - PrimaryQueue
Destination Type - Queue
AutoCreate destination - Enabled

Sample Input


Figure 6: Sample JMSOut input message

Output


Figure 7: Sample JMSOut output message

Schema

Input Schema

When the property Use Connection details from input is chosen, the following input schema with the element 'ConnectionFactorySettings', is generated. Properties that are used to create the connection are present under this element.


Figure 8: Input schema with ConnectionFactorySettings

Functional Demonstration

Scenario 1

Putting a simple Text message on a destination and displaying the response message.
Configure the JMSOut as described in Configuration and Testing section and use feeder and display component to send sample input and check the response respectively.


Figure 9: Demonstrating Scenario 1 with sample input and output

Sample Input

Input Text

Sample Output

Raw Text Message, that is, "Input Text"

Useful Tips

  • Choose non-durable messages where appropriate
  • When using the durable delivery 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 and until absolutely necessary for your application to avoid the overheads involved.
  • Choose proper acknowledgement mode
Icon

To understand the service better, refer the Web Logic Integration example which demonstrates JMSOut.4.0 service features.

Adaptavist ThemeBuilder EngineAtlassian Confluence