JMSIn4.0

The JMSIn component is used to transfer messages to a JMS topic or queue. Using the Configuration Property Sheet wizard, you can specify the topic or queue on which the message is to be sent. This component retrieves messages from a component and sends them to a JMS topic or queue. Additionally, you can create a Publisher or a Sender on Topic or Queue respectively, and configure the component to publish or send a message on a JMS Server at runtime.

This component can be used to send Text, Bytes or Map messages. The only restriction on Map Messages is that this component does not support Objects in Map Messages.JMSIn 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.

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

Configuration and Testing

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

Managed Connection Factory

Provider 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 users 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, an exception will be thrown at runtime.

JMS Provider

The JMS providers supported are BEA Weblogic, Fiorano MQ, Oracle AQ, Oracle Streams AQ, JBoss, Open MQ, and Rabbit MQ.

For working with these JMS providers, the jars that should be explicitly added as resources to the microservice are as 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\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

Open MQ

• %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" under System Lib in the Micro Service Repository panel, the jars get available for all JMS4.0 components.

  • Refer to the Adding Resources To a Microservice section to perform this action.

• In case of BEA Weblogic, InitialContext can be created by specifying empty values for JNDI Username and JNDI password as well.

• When configuring JMSIn 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 the following security permission in java.policy file under {JRE_HOME}/lib/security.

  CODE

  grant { permission javax.management.MBeanTrustPermission "register";} 

• After adding BEA Weblogic jars as resources, if we try to configure the component for Topic destination type in Fiorano MQ provider, test in Interactions configuration page of CPS will fail with java.lang.NoSuchMethodError. Thisisduetojavax.jmspackageconflictpresentinbothweblogicjarsandjms-2.0.jar used by Fiorano. To avoid this, wljmsclient.jar and wlthint3client.jarhasto be updated with the classes in javax.jmspackageofjms-2.0 jar by following these steps:

  1. Copy jms-2.0.jar present in %FIORANO_HOME%/extlib/jms to any location and extract the contents of jar using the following command: 

     CODE

     jar xf jms-2.0.jar

  2. Updatejavax.jmspackage classes in wljmsclient.jar with the above-extracted classes using the command " jarufwljmsclient.jar -C %EXTRACTED_PATH% javax/jms/* " from command prompt where %EXTRACTED_PATH% is the location where jms-2.0.jar is extracted. Similarly, wlthint3client.jar has to be updated.

Connection Configuration

Named Configuration

Please refer Named Configurations section in Common Configurations page for documentation.

Password Encryption Configuration

Please refer Custom Encryption For Passwords section in Common Configurations page for the documentation.

Server URL

The URL of the server to which the microservice connects.

Use the port 1867 to connect to the default Peer Server

In case of Rabbit MQ JMS Client, provide the location of the JNDI ".bindings" file.

Example

Windows

CODE

file:C:/JNDI-Directory/.bindings

Unix

CODE

file:var/mqm/JNDI-Directory/.bindings 

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

Backup URLs

The backup URLs to which the component tries to connect if the server specified by the property "server URL" is down. Multiple backup URLs can be specified by separating them with a ';'.

This property appears only if Backup URLs Required option is selected.

CF lookup name

Connection Factory Lookup Name.

JMS username

Username with which the connection to the server is established.

JMS password

Password for the username mentioned.

Proxy Settings

Please refer to Proxy Settings section in Common Configurations page for the documentation.

Connection Pool Params

Please refer to Connection Pool Params section in Common Configurations page for the documentation.

SSL Security

Click the Ellipsis button to configure the SSL Settings in the dialog box.

JNDI Settings

JNDI Configuration

Click the Ellipsis button to configure the JNDI settings in the dialog box.

Initial Context Factory

The name of the initial context factory. The initial context is typically used as a starting point.

JNDI username

The name with which the user connects to the JNDI server to perform lookup operations.

CF lookup name

The lookup name of the Connection Factory

JNDI password

The password for the JNDI username.

Initial Context Properties

Initial Context Properties can be used for creating an initial context by providing specific values by clicking Add button.

An initial context must be created using the specific implementation and extra parameters required by the implementation. The initial context will be used to look up a name. It is analogous to the root or top of a directory tree for a file system.

Working with Fiorano MQ HA profiles

While configuring JMSIn with Fiorano MQ HA profiles, provide Initial Context Properties in Advanced Info in the Managed Connection Factory Panel in the CPS.
Set the properties as below:

• Server URL: java.naming.provider.url
• Backup URLs: BackupConnectURLs

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. 

  

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

Connection Properties

Client ID

Client Identifier for the connection. This value is also used while creating the subscription name for a Durable Subscriber.

In case of Oracle AQ, this value will be used only as the Subscription Name but not as a Client Identifier for the connection

<instance-based>

Event Process name or Service Instance name is will be set as Client Identifier for the connection.

<auto-generated>

Client ID is not specifically set on connection, that is, connection.setClientID() is not called.

Interaction Configurations

Destination Settings

Destination Configuration

Destination Name

Name of the topic/queue to be subscribed to.

• 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

Whether a destination needs to be created, if it does not exists.

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.

Producer Configuration

Delivery Mode

• PERSISTENT
  Instructs the JMS provider to take extra care to ensure that a message is not lost in transit in case of a JMS provider failure. A message sent with this delivery mode is logged to stable storage when it is sent.
• NON-PERSISTENT
  NON_PERSISTENT delivery mode does not require the JMS provider to store the message or otherwise guarantee that it is not lost if the provider fails.

Time to Live

The time to live (in milliseconds) of the message to be sent to the destination. After the timeout the message will be discarded.

Priority

The priority of the message to be sent to the destination.

Retain Application Context

To retain Application Context.

Monitoring Configuration

Refer Monitoring Configuration section in Common Configurations page.

MessageType Settings

Message Type configuration

Message Type

• Map Message
  A MapMessage object is used to send a set of name-value pairs. The names are String objects, and the values are primitive data types in the Java programming language. The names must have a value that is not null, and not an empty string. The entries can be accessed sequentially or randomly by name. The order of the entries is undefined. MapMessage inherits from the Message interface and adds a message body that contains a Map.
• Byte Message as Base64 encoded Text
  Base64 encoding schemes are commonly used when there is a need to encode binary data that needs to be stored and transferred over media that are designed to deal with textual data. This is to ensure that the data remains intact without modification during transport. Base64 is commonly used in a number of applications including email via MIME, and storing complex data in XML.
• Text Message
  Text message in any of the following formats:
  
  • Raw Text
  • Plain Text
  • XML Text: Selecting this option gives more options to provide a specific XSD Schema.
    
    

    

    
    Figure 10: Text Message option in Message Type Configuration dialog box

Expert Properties

These attributes are meant for advanced users.

Send message on the output port

By enabling this property, the message sent to the JMS destination is also sent to the output port of the destination.

For descriptions of Expert properties given below, please refer the Interaction Configurations section in Common Configurations page:

• Pre Processing XSL Configuration
• Post Processing XSL Configuration
• Process Message Based On a Property
• Validate Input
• Cleanup Resources (excluding connection) after each input document
• TargetNamespace
• Elements to Decrypt
• Elements to encrypt

Scheduler Configurations

Please refer section in Common Configurations page.

Testing the Connection

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

Sample JMSIn configuration

The JMSIn 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.
In case of Oracle AQ, to grant user necessary privileges and to create a sample Topic(MY_TOPIC1)/Queue(MY_QUEUE1), execute following queries in Oracle DB configured in CPS:

• To Grant Permissions:
  • CONNECT SYSTEM
  • grant create session to [USER]
  • grant connect, resource, aq_administrator_role to [USER] identified by [USER];
  • grant execute on sys.dbms_aqadm to [USER];
  • grant execute on sys.dbms_aq to [USER];
• To Create Queue:
  • CONNECT [USER]
  • EXEC dbms_aqadm.create_queue_table (queue_table=>'MY_QUEUE1', queue_payload_type=>'sys.aq$_jms_text_message', multiple_consumers=>false );
  • EXEC dbms_aqadm.create_queue(queue_name=>'MY_QUEUE1', queue_table=>'MY_QUEUE1');
  • EXEC dbms_aqadm.start_queue(queue_name=>'MY_QUEUE1');
• To Create Topic:
  • CONNECT [USER]
  • EXEC dbms_aqadm.create_queue_table(queue_table=>'MY_TOPIC1', queue_payload_type=>'sys.aq$_jms_text_message', multiple_consumers=>true);
  • EXEC dbms_aqadm.create_queue(queue_name=>'MY_TOPIC1', queue_table=>'MY_TOPIC1');
  • EXEC dbms_aqadm.start_queue(queue_name=>'MY_TOPIC1');

Below configuration can be tested from within the CPS by clicking the Test button in the CPS panel.

Destination Configuration

Destination name - Primary Topic
Destination Type - Topic
Auto Create Destination - Enabled

Producer Configuration

Priority of message - 4
Time to Live - 0
Delivery Mode  - Non-persistent

Sample Input

Output

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.

Output Schema

Functional Demonstration

Scenario 1

Putting a simple Text message on a destination and displaying the response message.

Configure the JMSIn 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

<?xml version="1.0" encoding="UTF-8"?>
<ns1:Message xmlns:ns1="http://www.fiorano.com/fesb/activity/JMSIn1/jmsIn/Out">
   <ns1:Body>Message sent to Destination PrimaryTopic</ns1:Body>
   <ns1:SentMessage>Input Text</ns1:SentMessage>
</ns1:Message>

Useful Tips

• Set optimal message age (Time-to-live property) so as to reduce memory overhead, thus improving performance.
• Less message size gives better performance and vice versa. For example, ByteMessage takes less memory than TextMessage, hence choose message type carefully to avoid unnecessary memory overhead.
• Delivery mode defines whether the message can be persistent or non-persistent; this factor has an impact on the performance. Choose non-persistent messages where appropriate.

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