Comments

Java Classpath

The tpt-jms module is built against the jms-1.1 javax.jms package library. This library will be supplied with your JMS implementation and should be added to the NetKernel classpath. You have two choices for how to do this.

1. Recommended Add your JMS implementation's JAR files to the [install]/lib/ext directory where NetKernel will dynamically add them to the global NetKernel classloader
2. Unzip the tpt-jms module located in [install]/modules/ and add your JMS implementation's JAR files to the lib/ directory of the module. Rezip the module directory with a .jar extension. This module's classloader will then dynamically discover the libraries.

Native Libraries

Some JMS implementations - such as IBM MQ - also require access from the JVM to native libraries (on *nix file extension .so). You can instruct the JVM where to find native libraries with the following java command line argument:

-Djava.library.path=/usr/lib

/usr/lib is typical for Unix platforms but you may specify a different path.

Receiving Messages

The JMS transport can be used to subscribe to JMS topics and to retrieve messages from queues. For details about configuration and use see the JMS Transport Guide.

Sending Messages

There are two methods to send a message to a queue or topic, firstly by SINKing to a queue or topic URI, or secondly, by using the active:jms-send service.

Sinking

The simplest way to send a message to a queue or topic is to sink to its uri, which is either jms-queue:[logical JNDI queue name] or jms-topic:[logical JNDI topic name]. If you send a message this way you have no control on the JMS header and property fields. The type of message sent will depend upon the configuration. If a TextMessage is specified, the supplied resource will be transrepted (if necessary) to a StringAspect. If a BytesMessage is specified, the supplied resource will be transrepted to a ReadableBinaryStreamAspect.

A SINK request can be explicitly made through the NKF context or, for example in DPML, will be issued when specified as the <target> URI of an instruction.

active:jms-send

To gain full control over the message to be sent the jms-send service can be used. For full details see the accessor reference.

Compatibility

The JMS connectivity module uses standard JMS APIs and should be compatible with all JMS implementations. It has been tested with ActiveMQ and MOM4J.

Customizing and Rebuilding

You may want to customize the JMS components for your JMS system, for example for domain specific security considerations, or rebuild the library against your JMS implementations libraries.

The source is provided in the JMS module - to build you must link against [install]/lib/1060netkernel-x.x.x.jar and the ext-xml-core-x.x.x.jar and ext-layer1-x.x.x.jar which are located in the [install]modules/ directory. You must also link against your JMS library's implementation of the javax.jms.* packages.

Troubleshooting

JMS implementations vary greatly from vendor to vendor. Here are some common issues you may encounter.

JNDI ClassCastException	on JNDI lookup of Queue/TopicConnectionFactory ensure that your vendor supplied JMS JAR libraries are located in [install]/ext/lib/
javax.jms.XXX ClassCastException	the tpt-jms library is built against the Apache Geronimo javax.jms.* packages. Rebuild the tpt-jms module against your vendor supplied javax.jms libraries.