JMS transport configuration

To use this exchange, you must have JMS experience and a working JMS system.

Your JMS system may have file size limitations. Check the documentation for your JMS system.

The JMS application transport is an input and output source for messages. This is how it works: Activator polls the JMS server for messages in the designated inbound queue. This means that any JMSMessage placed in the queue by another process is retrieved by Activator, which verifies the type of JMSMessage (BytesMessage or TextMessage). If verified, Activator packages and sends it to the partner. Likewise, every message Activator receives from a partner is unpackaged, converted to a BytesMessage or TextMessage and placed on the designated outbound queue.

For application pickup exchanges, Activator determines whether the message read from the queue is a BytesMessage or a TextMessage. For delivery application delivery exchanges, in which messages from partners are sent to back-end systems, you can select the JMS type (BytesMessage or TextMessage) on the Advanced tab of the transport’s maintenance page.

When using JMS for application exchanges, configure Activator to parse EDI and XML messages retrieved from a back-end system for sender and receiver information.

Binary documents retrieved from the back-end must have the following metadata string parameters appended to the BytesMessage or TextMessage: SenderRoutingId, ReceiverRoutingId and ContentMimeType. The trading engine performs routing decisions based on the string parameters.

When Activator sends a BytesMessage or TextMessage to the back end, it includes the string parameters SenderRoutingId, ReceiverRoutingId and ContentMimeType for all document types.

Other metadata are available for JMS messages. See Message metadata. Virtually all of this metadata are copied into the JMS message when Activator produces the message to a JMS queue. When reading from a JMS queue, all metadata from the JMS message are copied into the collaboration message, but it may not make sense to set some items in the JMS message. For example it would not make sense to set the ConsumptionURL in the JMS message. Also see XML for JMS and AQ event routers.

Note that when Activator encounters a metadata element containing characters that JMS cannot recognize, it changes the offending characters into the hex representation of the ASCII code of the characters. For example, the metadata element ediint.DocumentType becomes ediint$2eDocumentType. The $2e is the hex representation of a period. When submitting JMS messages to Activator, use the properly encoded hex names to have them turned into the proper metadata names.

In addition to using the delivery exchange wizard to configure a JMS transport, other set up is required. Depending on your provider, follow the recommendations in the JMS transport configuration or JMS transport configuration topic.

Note   If BEA WebLogic is your JMS provider, there are options for ensuring proper load balancing and fail-over when delivering messages to clustered JMS servers. One option is to configure a distributed destination in WLS and reference its JNDI name on the JMS configuration page in Activator. At runtime, the JNDI lookup performed by the WebLogic JMS client resolves the distributed destination name to a physical queue. Another option is to provide a comma-separated list of host names in the JNDI URL field in Activator (for example, t3://node1:7001,node2:7002,node3:7003). At runtime, the JMS client round-robins between the specified providers. Both options ensure load balancing and support for fail-over. See the WebLogic documentation for how to configure these options.

Most providers

In addition to completing the JMS transport configuration page in the user interface, to enable Activator to use a custom JMS provider:

  1. Copy the necessary JAR files for your JMS provider to <Activator_install_directory>/Activator/site/jars.
  2. This directory is already part of the CLASSPATH.
  3. Restart Activator.

Troubleshooting

Note   You cannot have multiple versions of the provider JAR files in the <Activator_install_directory>/Activator/corelib/ directories. For example, if you already have v7.5 IBM MQ JARs and add V8.0 JARs, you must remove the older JARS to avoid conflicts.

In Windows environments, in some cases you may experience JAR conflicts when a provider JAR file is added to ...Activator/site/jars. If this the case, you can:

  1. Create a new folder to contain the specific JAR files for the JMS provider.
  2. Go to .../Activator/conf and open jvmArguements.xml in a text editor.
  3. Add the name of the directory containing the JAR or class files (or both) in the jvmArguements.xml file so the server can locate the JMS and JNDI provider. Add CLASSPATH entries under the “TE” node type, as in the following example. Entries can be either a “path” reference or a reference to a single JAR:
  4. <NodeType type="TE" class="com.axway.clusterold.startup.Boot">

    ...

    <Classpath>../jars/custom.jar</Classpath>

    <Classpath>/JMSProviderJarPath</Classpath>

  5. Save the file.

WebSphere MQ

For WebSphere MQ configuration details, see WebSphere MQ configuration.

Oracle AQ

If the provider is Oracle Advanced Queuing facility (Oracle AQ), Oracle must be the external database for Activator and Oracle AQ must be installed.

Add a message queue on Oracle AQ. The queue payload type must be one of the following:

  • SYS.AQ$_JMS_BYTES_MESSAGE
  • SYS.AQ$_JMS_TEXT_MESSAGE

On the Oracle client, copy the Oracle AQ drivers aqapi.jar and jmscommon.jar. You may find these files in the rdbms/jlib directory. Paste the files to the Activator directory <Activator_install_directory>\Activator\corelib\db\oracle and restart the server.

For any JMS transport for Oracle AQ that polls for messages, go to the Advanced tab on the transport’s maintenance page and select Use transacted queue. You need to do this if the JMS settings tab name includes the word polled. For example, JMS (polled) settings. If the settings tab is named JMS (listener) settings, the Use transacted queue control is not available on the Advanced tab.

If Oracle AQ is installed on Oracle 10g or later, JMS performance in listener mode may be poorer than in polled mode. If this is the case, consult Oracle documentation or technical support about whether to keep or change values of the following AQ parameters:

System.setProperty("oracle.jms.minSleepTime","200");

System.setProperty("oracle.jms.maxSleepTime","1000");

Once the values are determined, set identical values in Activator jvmArguements.xml file at <Activator_install_directory>\Activator\conf. The properties to add are:

The steps are:

  1. Open the jvmArguments.xml file.
  2. Scroll to the TE section (NodeType type="TE").
  3. Add the min and max sleep time properties. Values are in milliseconds.
  4. Save and close the file.

JMS fields

The following fields are used in the delivery exchange wizard for configuring this transport.

Except for the user name and password, you can obtain the information needed to complete this page from the JMS provider's documentation. The information varies depending on the provider. If you have questions, contact your JMS provider.

  • JMS type – There are two choices for acquiring messages from a JMS queue when consuming messages from back-end applications and from partners:
    • Polled. Activator polls the JMS server at intervals for messages. This is the default setting. The polling interval and the maximum number of files to retrieve per interval can be adjusted on the Advanced tab of the transport’s maintenance page. Although the rate at which messages enter the system is controlled, this selection introduces latency and overhead in checking the JMS server when the queue is empty. (If Sybase EAServer is the JMS provider, you must select Polled.)
    • Listener. The JMS server calls Activator as soon as a message is written to its queue. Messages are transferred as they arrive and do not wait for Activator to poll for them. When selected, the transport’s Advanced tab on the maintenance page has a setting for reconnecting to the JMS server if the server goes down. However, there are no controls related to polling, because polling does not apply. Although latency and polling overhead are eliminated, this selection cannot control the rate at which messages enter the system, which could overload it. (If you use WebLogic, the Allow Close In On Message check box for the queue factory must be selected in the WebLogic user interface.)
  • Once polled or listener has been selected, the JMS type cannot be changed on the transport’s maintenance page.
  • JMS queue – The name of the queue. Example: XMLQueue@router1
  • This queue requires a user name and password – Select this if the queue requires a user name and password. When selected, fields appear for entering the information.
    • User name – A user name for the JNDI provider. This value could be blank and is typically provided for in the JNDI URL. However, this depends on the JNDI provider and how it is configured.
    • Password – A password for the JNDI provider. This value could be blank and is typically provided in the JNDI URL. However, this depends on the JNDI provider and how it is configured.
    • Confirm password – Type the password again for confirmation.
  • Use JNDI – Select this if a Java Naming and Directory Interface (JNDI) provider. When selected the applicable fields display.
  • JNDI URL – The network URL used to obtain access to the JNDI service provider for your JMS service. Example: smqp://localhost:4001/timeout=10000
  • JNDI factory – The name for the JNDI service provider class. Example: com.swiftmq.jndi.InitialContextFactoryImpl
  • This provider requires a user name and password – Select this if JMS requires a user name and password. When selected, fields appear for entering the information.
    • User name – A user name for the JMS provider. This can be the same as your JNDI user name. However, this depends on your JMS provider and how it is configured.
    • Password – A password for the JMS provider. This can be the same as your JNDI password. However, this depends on your JMS provider and how it is configured.
    • Confirm password – The password again for confirmation.
  • JMS connection factory – The connection factory as defined within the JMS provider. This value can be either in the form factoryname@routername or the JNDI public symbol for the QueueConnectionFactory. Examples: plainsocket@router1 or QueueConnectionFactory22. This depends on your JMS provider and how it is configured.
  • Use a custom Java implementation – Select this for a JMS provider that does not require a JNDI implementation. For example, Oracle Advanced Queuing facility (Oracle AQ). When selected the applicable fields display.
    • Class name – The name of the Java class for implementing the connection to the message queue. A Java class for Oracle AQ is available. The class name is:

    com.cyclonecommerce.tradingengine.transport.jms.OracleAQQueueUtil

    If you want a Java class for a provider other than Oracle AQ, you need the help of a professional services consultant. Contact technical support for information.

    • Parameters – These are the parameters for implementing the Java class. There are four parameters required for the Java class for Oracle AQ. These parameters must be in the following order:
      • Host. The name of the computer running Oracle AQ.
      • Database name. The name of the database that contains the message queue.
      • Port. The port Oracle AQ uses to listen for messages. 
      • Driver type. The type of JDBC driver for connecting to the provider. For Oracle AQ, the valid values are thin and oci8
  • Send payload via file system (delivery exchange only) – Select this option to have payloads sent by a file system. You can specify the size of payloads to send and the path for payload files. The receiver uses the path to retrieve the files.

Click Next if you want to name the exchange. Otherwise, click Finish.

Related Links