Skip to main content
Skip table of contents

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


Figure 1: Sample JMSIn MCF configuration

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.


Figure 2: List of JMS Providers

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.

  • 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


Figure 3: 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.


Figure 4: SSL Security settings options in the SSL Configuration panel

PropertyDescription
Enable SSlSelect this option to enable SSL Settings. Rest of the properties in this editor are enabled and configurable only when this property is checked.
Trust Store LocationLocation of the Java keystore file containing the collection of CA certificates trusted by this application process (trust store)
Trust Store PasswordPassword to unlock the keystore file (store password)
Key Store LocationLocation of the Java keystore file containing an application process's own certificate and private key.
Key Store PasswordPassword to access the private key from the keystore file.
Key Store TypeFor Java keystore file format, this property has the value jks (or JKS). You do not normally specify this property, because its default value is already jks.
Trust Store TypeFor Java keystore file format, this property has the value jks (or JKS). You do not normally specify this property, because its default value is already jks.
Trust Manager Factory TypeAlgorithm for the Trust Manager Factory.
Key Manager Factory TypeAlgorithm for the Key Manager Factory.
Security Provider ClassDetermines Security provider class.
Security ProtocolDetermines Security protocol
Key Store Client KeyDetermines Key Store Client Key

JNDI Settings


Figure 5: 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.

Session Properties

Acknowledge Mode

The type of Acknowledgement mode can be specified here. A session retains messages it consumes until they have been acknowledged.

Auto Acknowledge

The session automatically acknowledges a client's receipt of a message either when the session has successfully returned from a call to receive or when the message listener the session has called to process the message successfully returns.

Client Acknowledge

With this acknowledgment mode, the client acknowledges a consumed message.

Dups OK Acknowledge

This acknowledgment mode instructs the session to lazily acknowledge the delivery of messages.

Interaction Configurations


Figure 6: Interaction Configurations panel in CPS

Destination Settings

Destination Configuration


Figure 7: Destination Configuration options

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


Figure 8: Producer Configuration options

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


Figure 9: Message Type Configuration options

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.


Figure 11: Interaction Configurations panel with the Expert Properties view enabled

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.


Figure 12: Sample connection test result indicating success

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


Figure 13: Sample JMSIn input message

Output


Figure 14: Sample JMSIn 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 15: Input schema with ConnectionFactorySettings

Output Schema

Schema Element

Description

<Body>

Body of the response message

<SentMessage>

Message sent to the destination

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.


Figure 16: Demonstrating Scenario 1 with sample input and output

Sample Input

Input Text

Sample Output

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


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.