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

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

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 providers supported are:

  • Fiorano MQ
  • BEA WebLogic
  • Oracle AQ
  • JBoss
  • Open MQ
  • Rabbit MQ
Icon

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)

      Icon

      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\ojdbc14.jar%ORACLE_HOME%\jdbc\lib\nls_charset12.jar

      Icon
      • For Oracle Database 9.2.0.1.0, %ORACLE_HOME% refers to <Oracle Installation directory>\ora92.
      • If these jars are added to resources of the System library JMSCommon, the jars will be available for JMSIn 5.0, JMSOut 5.0 & JMSRequestor 5.0 components. Refer to the Adding Resources To a Microservice section to perform this action.
  • 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

Icon
  • If the above jars are added to resources of the System library JMSCommon, the jars will be available for all JMS5.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.
  • 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
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 microservice connects.

Icon

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

Example

Icon
Windows
Unix

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 ";" 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
AttributeDescription
Key Manager Factory TypeAlgorithm for the Key Manager Factory.
Key Store TypeType of the Key Store whose location is specified by Key Store Location should be specified in the fileld.
Key Store LocationLocation of the key store file can be provided using the file dialog that opens up on clicking the ellipsis  button.
The KeyStore is used by the component for client authentication.
Key Store PasswordPassword of the specified key store can be specified in the field.
Key Store Client KeyDetermines Key Store Client Key
Trust Store Settings
AttributeDescription
Trust Manager Factory TypeAlgorithm for the Trust Manager Factory.
Trust Store LocationLocation 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 TypeType of Trust Store whose location is specified by property Trust Store Location.
Trust Store PasswordPassword 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. 

    Icon

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

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.

Icon

This will be used only when the option Use specific client ID is selected. 

Session Properties

Is transacted

Select this option if session to be created should be transacted.

Icon

If this property is not selected, appropriate Acknowledge mode has to be chosen.

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

This option is relevant only when IsTransacted is not selected.

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

Icon

Byte Message as Text property is not applicable in JMSIn5.0 microservice.

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

Remove Properties with null value

If this option is checked, header properties with null value will be excluded in the Output message retrieved from the JMS server.

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.

Icon

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

Icon

dynamicTopics/<TopicName>

Queue name format

Icon

dynamicQueues/<QueueName>

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.

Icon
  • This is applicable only for Fiorano MQ. In case of Oracle AQ, create destinations in the Oracle DB manually.
  • 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'.

    Icon

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

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.
Example: 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');
Icon
  • One of "Lookup destination" or "Autocreate destination" is mandatory.
  • If both are chosen, the component first tries to lookup the destination and if it fails it will create the destination.
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.

Icon

If a complex schema is used in the component, then enabling this option has an impact on the performance. If the validate Input property is disabled , it does not validate the input and thereby increases the performance. However, it may cause undesired results if the input XML is not valid. 

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
Icon
  • To set the expected responses on the event of an error, expand the required option from the following:
    • Connection Error
    • JMS Error
    • Response Generation Error
    • Request Processing Error
    • Invalid Request Error
  • The respective attributes appear on expanding the above properties.
  • For more information about the attributes, please refer Error Handling section in Common Configurations page.

 

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.
Adaptavist ThemeBuilder EngineAtlassian Confluence