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

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

JMS Provider

The JMS providers supported are Fiorano MQ, BEA Weblogic, Oracle AQ, Oracle Streams AQ and JBoss. For working with these JMS providers, the jars that should be explicitly added as resources to the component 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)
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\classes12.zip
  • %ORACLE_HOME%\jdbc\lib\nls_charset12.jar
Icon

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
Icon

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

 

Icon
  • If these jars are added to resources of the System library JMSAdapters, the jars are available for JMSIn, JMSOut and JMSRequestor 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 following security permission in java.policy file under {JRE_HOME}/lib/security >.The permission to be added is "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. This is due to javax.jms package conflict present in both weblogic jars and jms-2.0.jar used by Fiorano. To avoid this, wljmsclient.jar and wlthint3client.jar has to be updated with the classes in javax.jms package of jms-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 command "jar xf jms-2.0.jar" from command prompt. 
    2. Update javax.jms package classes in wljmsclient.jar with the above extracted classes using the command " jar uf wljmsclient.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 2: Connection Configuration

Named Configuration

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

Password Encryption Configuration

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

Server URL

IP address of the JMS server.

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 ';'.

Icon

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 3: 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 4: 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, we should 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. 

    Icon

    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 5: Interaction Configurations panel in CPS

Icon

For the Expert Properties such as Send message on the output port, Validate Input, Cleanup resources (excluding connection) after each document, Target Namespace, Elements to Decrypt and Elements to encrypt, refer respective sections in Common Configurations page.

Destination Settings

Destination Configuration


Figure 6: Destination Configuration options

Destination Name

Name of the topic/queue to be subscribed to.

Icon

In case of BEA Weblogic,

  • JNDI name of the topic or queue has to be specified.
  • value for Destination Name should be the JNDI name of the destination.
    Example: weblogic.examples.jms.exampleTopic.
Destination Type

The JMS type of the destination; either Topic or Queue.

Select one of these destination types:

  • Topic: Message can 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 destination needs to be created, if it does not exists.

Producer Configuration


Figure 7: 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 8: 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 9: Text Message option in Message Type Configuration dialog box

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 10: 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 on 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 11: Sample JMSIn input message

Output


Figure 12: 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 13: 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 14: 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.
Icon

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

Adaptavist ThemeBuilder EngineAtlassian Confluence