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.
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 the Durable Subscribers section in the FioranoMQ Handbook - Connecting to Web Management Tool section.
- 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 the 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)
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
Oracle Streams AQ
- %ORACLE_HOME%\rdbms\jlib\aqapi.jar
%ORACLE_HOME%\jdbc\lib\ojdbc14.jar
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
Working with Fiorano MQ HA profiles
When Configuring JMSOut with Fiorano MQ HA profiles, you should provide Initial Context Properties in Advanced 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.
- Valid value: Qualified class name of security Manager class.
Interaction Configurations
Figure 3: Interaction Configurations
Destination Settings
Destination Configuration
Figure 4: Destination Configurations
Destination Name
Name of the topic or queue to which messages are to be transferred.
Destination Type
The JMS type of the destination; either Topic or Queue.
Select one of these destination types:
- Topic: Message can be consumed by a number of clients. Topic represents Public Subscription (Pub/Sub) domain.
- Queue: Message can be consumed by only one client. Queue represents Point to Point (PTP) domain.
Lookup Destination
This option can be chosen if the destination is already present and needs to be looked up using JNDI.
AutoCreate Destination
If destination provided is not present, then it is created dynamically.
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.
Is Durable
This property is used to create a durable subscription when the destination type is Topic.
Figure 5: Option to configure Consumer Configuration in the dialog box
Subscription Name: Provide a unique Subscription Name for durable subscriber.
Message Selector: The JmsOut 4.0 filters those Messages from the configured Destination which satisfies the given condition in the Message Selector. In the above figure,all the messages with propertyName = "property" and PropertyValue = "value" are filtered by the JmsOut.
Message Type Settings
Byte Message as Text
Use this option when the destination is "AMQP" Destination in case of RabbitMQ JMS Provider.
Figure 6: Byte Message as Text option in the Message Type configuration palette
Expert Properties
For the attributes given below (all except the last one are Expert Properties), please refer Interaction Configurations section in Common Configurations page.
- Pre Processing XSL Configuration
- Post Processing XSL Configuration
- Validate Input
- Cleanup Resources (excluding connection) after each input document
- Target Namespace
- Monitoring Configuration
Refer to the Processing Message based on a Property section for the description of the property.
The properties that are unique for JMSOut component are mentioned below.
Action when message is not available?
Figure 7: 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 the output port. - Treat as Exception
An exception message is sent to error port and no message is sent to the 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 a 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. The 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 8: 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 9: Sample JMSOut input message
Output
Figure 10: Sample JMSOut output message
Schema
Input Schema
When the Use Connection details from input property 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 11: 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 12: 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 the message to the consumer and removed after delivery of the 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 acknowledgment mode