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.
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)
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
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
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.
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 ';'.
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
| Property | Description |
|---|---|
| Enable SSl | Select 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 Location | Location of the Java keystore file containing the collection of CA certificates trusted by this application process (trust store) |
| Trust Store Password | Password to unlock the keystore file (store password) |
| Key Store Location | Location of the Java keystore file containing an application process's own certificate and private key. |
| Key Store Password | Password to access the private key from the keystore file. |
| Key Store Type | For 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 Type | For 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 Type | Algorithm for the Trust Manager Factory. |
| Key Manager Factory Type | Algorithm for the Key Manager Factory. |
| Security Provider Class | Determines Security provider class. |
| Security Protocol | Determines Security protocol |
| Key Store Client Key | Determines 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.
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.
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.
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.
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
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.