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 applicaton 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. Activator 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.

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.

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 <install_directory>/Activator/site/jars.
2. This directory is already part of the CLASSPATH.
2. Restart Activator.

Troubleshooting

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

4. Save the file.

WebSphere MQ

For WebSphere MQ configuration details, see WebSphere MQ configuration.

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

Testing JMS

You can use the jmsTester tool to exercise the JMS client outside of Activator. 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 Activator and a partner’s JMS server. Activator server does not have to be running to use this tool. You can use it on UNIX or Windows.

jmsTester duplicates the way Activator 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 Activator 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