The JMSIn component is used to send messages to a JMS destination (topic or queue). This component sends the messages received on the input port to the configured JMS destination. The destination on which the message is to be sent can be specified in the Configuration Property Sheet wizard.
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.
Points to Note
- The JMS providers supported are Fiorano MQ, BEA Weblogic and JBoss. For working with these JMS providers the jars that should be explicitly added as resources to the component are 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\ojdbc14.jar%ORACLE_HOME%\jdbc\lib\nls_charset12.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
- BEA WebLogic:
- In case of BEA Weblogic, InitialContext can be created by specifying empty values for JNDI Username and JNDI password as well.
- 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 save a specific configuration for further use, Named Configuration option is available in JMS Connection Configuration properties as well as Send Configuration properties. Please refer the Named Configurations in CPS section in Common Configurations page to understand the procedure to save a Named Configuration.
Configuration
JMS Connection Configuration
Connection configuration details can be specified in this panel.
Figure 1: Connection Configuration panel
Provider URL Settings
JMS Provider
Choose the MQ server from the drop-down list provided. The JMS provider options present in the drop-down are:
- FIORANO
- WEBLOGIC
- ORACLE_AQ
- JBOSS
Connection Configuration
To set the Connection Configuration in the dialog box, click the button on the right side of the property.
Figure 2: Connection Configuration dialog box
Password Encryption Configuration
Please refer the Custom Encryption For Passwords section in CPS in Common Configurationspage.
Server URL
The URL of the server to which the component 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 ";" in case of all servers except the openMQ where comma ( , ) has to be used.
CF lookup name
The lookup name of the Connection Factory.
JMS Username
The user name with which the client connects to the MQ server.
JMS Password
The password for the username that is provided.
SSL Configuration
Use 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.
Accept Server Certificate
When accessing https URLs, this property determines whether the server certificates should be accepted or not. If selected, the certificate will be accepted without any validation, otherwise exception is sent to ON_EXCEPTION port.
Ignore Hostname Mismatch
If this option is selected the certificate will be accepted even if hostname in the certificate does not match with the hostname in the request URL. If its not selected exception is thrown.
Protocol Handler Packages
Determines protocol handler packages property.
Security Protocol
Determines Security protocol
Security Provider Class
Determines Security provider class.
Key Store Settings
| Attribute | Description |
|---|---|
| Key Manager Factory Type | Algorithm for the Key Manager Factory. |
| Key Store Type | Type of the Key Store whose location is specified by Key Store Location should be specified in the fileld. |
| Key Store Location | Location of the key store file can be provided using the file dialog that opens up on clicking the ellipsis  .The KeyStore is used by the component for client authentication. |
| Key Store Password | Password of the specified key store can be specified in the field. |
| Key Store Client Key | Determines Key Store Client Key |
Trust Store Settings
| Attribute | Description |
|---|---|
| Trust Manager Factory Type | Algorithm for the Trust Manager Factory. |
| Trust Store Location | Location of the trust store file should be specified. TrustStore is a file where digital certificates of trusted sites are stored and retrieved for authentication during an SSL connection. TrustStore is used to authenticate a server in SSL authentication. |
| Trust Store Type | Type of Trust Store whose location is specified by property Trust Store Location. |
| Trust Store Password | Password of the specified trust store should be specified in the field. |
JNDI Settings
JNDI Configuration
To set JNDI configuration in the dialog box, click the button on the right side of the property.
Figure 3: JNDI Configuration dialog box
Initial context factory
The name of the initial context factory.
JNDI Username
The name with which the user connects to the JNDI server to perform lookup operations.
JNDI Password
The password for the JNDI username.
Initial context properties
Additional properties which can be used for creating an Initial Context can be specified here. For instance, if JMSAdapter has to connect to the FMQ server using HTTP protocol instead of the default TCP protocol, then a property 'TransportProtocol' can be specified with the value 'HTTP'.
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
Use specific client ID
Select this option to specify a user-defined Client ID. If it is not selected, client ID is generated automatically at runtime.
Client ID
The client ID that will be set on the connection with the server.
Session Properties
Is transacted
Select this option if session to be created should be transacted.
Acknowledgement mode
The type of Acknowledgement mode can be specified here. A session retains messages it consumes until they have been acknowledged.
- Dups OK Acknowledge: This acknowledgment mode instructs the session to lazily acknowledge the delivery of messages.
- 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.
Send Configuration
Send configuration details can be specified in the second panel of the CPS, that is, Send Configuration.
Figure 4: Send Configuration panel
Message Type Settings
Message Type Configuration
To configure the message type in the dialog box, click the button on the right side of the property.
Figure 5: Message Definition Confguration dialog box with Message Type - 'Test Message'
The schema of the Component Input Port will be determined based on the Message Definition Configuration.
Use XML Interface
This option has to be chosen if the component needs an XML interface. If this is not selected, schema will not be set on input port of the component and the message received on the input port will be sent to the destination as it is.
Message Type
The type of the message that needs to be sent can be chosen as one of the following:
- Text message: Use this option to send a plain text message.
- Map message: A Map Message 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.
- Stream message: A Stream Message object's message body contains a stream of uninterpreted bytes. This message type is for literally encoding a body to match an existing message format.
Include JMS Header
This option can be selected to set the JMSHeaders on the message at runtime.
When this option is selected, the fields JMSCorrelationID and JMSDestination will be generated in the input schema of the component.
Include Properties
This option can be selected to set the JMS properties on the message at runtime.
When this option is selected, the elements "ApplicationContext" and "Property" (ZeroMany) are generated in the input schema of the component.
The properties and application context can be set as shown in the figure.
Figure 6: Providing Application Context and Property
Message Content
Depending on the Message Type selected, the appropriate parsing option is shown. Message Type and the corresponding parsing option is explained below.
- Text message – XML Content
Select this option if the content of the input message conforms to a specific schema. The schema can be specified using the schema editor. - Map message – Define body fields
Select this option to define the body fields of the Map message. The message body fields (name and type of the field) can be added in the table and the input schema will be generated corresponding to the each field defined.
Figure 7: Message Definition Configuration dialog box with Message Type - 'Map Message' - Stream message – Parse body
Select this option to set the content of the stream message in input XML. The name, type and length of the field can be added in the table. An element will be added to the schema corresponding to each field with the same name.
Figure 8: Message Definition Configuration dialog box with Message Type - 'Stream Message'
Destination Settings
Destination Configuration
To set the Destination Configuration in the dialog box, click the button on the right side of the property.
Figure 9: Destination Configuration dialog box options
Destination Name
The name of the destination to which the messages have to be sent.
Destination Type
The JMS type of the destination. This can be chosen as either Topic or Queue.
Lookup Destination
This option can be chosen if the destination is already present and needs to be looked up using JNDI.
AutoCreate Destination
This option has to be chosen to create a destination with the provided name in case the provided destination does not exist.
Destination specified for the property Destination Name should already exist if BEA Weblogic/Oracle 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. Ex: weblogic.examples.jms.exampleTopic or if Destination Name is provided in the format JMS_Module_Name!Destination_Name, then Autocreate destination property is mandatory for lookup and it will not create a new destination in this case.
In case of Oracle AQ, to grant user necessary previliges 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');
Producer Configuration
Figure 10: Producer Configuration dialog box 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.
Priority
The priority of the message to be sent to the destination.
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.
Error Handling
The actions that have to be taken in case of different kinds of errors can be configured in the third panel, that is, Error Handling panel.
Figure 11: Error Handling panel
Validate Input
Select this option if the input message has to be validated against the schema that is set on the input port.
Target namespace
The target namespace of the schema can be provided here. The schema on ports will be suffixed with the component name and type of the port. For example, /JMSIn/In
Error Handling options
Functional Demonstration
Scenario 1
To send a Map message to the destination "PrimaryQueue".
The component is configured to send a Map message as described in section Message Definition and the option "include JMSHeader" is enabled to set JMS headers on the message.
Feeder and display components are connected to the component to send sample input and check the response respectively.
Figure 12: Event Process for Scenario 1
Sample Input
Figure 13: Sample Input
Sample Output
Figure 14: Sample Output
Useful Tips
- Set optimal message age (Time-to-live property) so as to reduce memory overhead and thereby improve 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.
- Enabling Validate Input option has a negative impact on the performance of the component when a complex schema is used. But when this is disabled, it may cause undesired results in case the input XML is not valid.