JMSOut4.0

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.

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

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)

  

  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

  

  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

  

  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

Rabbit MQ

• amqp-client-4.1.1.jar

• fscontext-4.5-b25.jar

• rabbitmq-jms-client.jar

• If these jars are added to resources of the System library "JMSAdapters", the jars will be 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";} ".

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

  

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

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

Interaction Configurations

Destination Settings

Destination Configuration

Destination Name

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

• If JMS Provider is "BEA Weblogic",
  • JNDI name of the topic or queue has to be specified.

  • Destination Name should be the JNDI name of the destination.

    

    Example

    weblogic.examples.jms.exampleTopic

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

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.

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 Rabbit MQ JMS Provider, if the destination provided is not present in the ".bindings" file, then it will be created dynamically. If 'AutoCreate Destination' is disabled, then the destination must be declared in the ".bindings" file, if not, it displays an error message in the error logs that reads, 'Error getting the destination'.

Refer the Creating the .bindings file for Rabbit MQ JMS Provider section to know how to create a .bindings file.

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.

The options "Is Durable?" and "Subscription Name" are visible only when 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.

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.

Refer the respective sections in the JMSIn4.0 page for descriptions on the properties below:

• Retain Application Context
• Monitoring Configuration

Message Type Settings

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'.
• For rest of the Message Type configurations, refer the respective sections in the JMSIn4.0 page.

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?

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.

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 the Test button in the CPS panel:

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

Sample Input

Output

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.

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.

Sample Input

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

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