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.

Note   If you are using the Axway Integrator JMS transport for integrating Interchange with Axway Integrator, see Integrate with Axway Integrator.

The JMS application transport is an input and output source for messages. This is how it works: Interchange 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 Interchange, which verifies the type of JMSMessage (BytesMessage or TextMessage). If verified, Interchange packages and sends it to the partner. Likewise, every message Interchange receives from a partner is unpackaged, converted to a BytesMessage or TextMessage and placed on the designated outbound queue.

For applicaton pickup exchanges, Interchange 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 Interchange 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. Interchange performs routing decisions based on the string parameters.

When Interchange 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 Metadata definitions. Virtually all of this metadata are copied into the JMS message when Interchange 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 Interchange 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 Interchange, 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 Interchange. 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 Interchange (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 Interchange to use a custom JMS provider:

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


Note: You cannot have multiple versions of the provider JAR files in the ... Interchange /site/jars or . .. Interchange /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 ...Interchange/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 .../ Interchange /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">




  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 Interchange and Oracle AQ must be installed.

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


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 Interchange directory <install directory>\Interchange\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:



Once the values are determined, set identical values in the Interchange jvmArguements.xml file at <install directory>\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. The change should look like the following snippet. The added properties are in bold.
  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 for integration pickup and receiving messages from partners:
    • Polled. Interchange 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 Interchange as soon as a message is written to its queue. Messages are transferred as they arrive and do not wait for Interchange 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:


    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.

Testing JMS

You can use the jmsTester tool to exercise the JMS client outside of Interchange. The script to start jmsTester can be found in <install directory>\tools.

jmsTester is a console-based application that can verify the operation of the JMS client in Interchange and a partner’s JMS server. Interchange server does not have to be running to use this tool. You can use it on UNIX or Windows.

jmsTester duplicates the way Interchange accesses a JMS server. It is a test program to verify interoperability with JMS servers. If you can send, list, receive and delete files on a JMS server using jmsTester, this is a good indication Interchange can interoperate with the server.

jmsTester prompts for all the information it needs, as the following illustrates:

After prompting for the initial configuration information, you can use one of the following test commands:

  • (c)onnect
  • (d)isconnect
  • (s)end
  • (r)etrieve
  • (a)cknowledge

Related Links