SwiftMQ/Tomcat 5.5, 6, 7

How Tomcat declares Resources

Tomcat declares resources such as connection factories as JNDI references and stores it in its JNDI tree. The declaration takes place in a context.xml file that must be store unter META-INF/ of the war file. The resolution from a JNDI reference into an object instance takes place by a custom JNDI object factory.

Example:

      <?xml version="1.0" encoding="UTF-8"?>
      <Context path="/">
        <Resource auth="Container"
                  name="jms/cf"
                  type="com.swiftmq.jms.v750.ConnectionFactoryImpl"
                  factory="com.swiftmq.jndi.v400.SwiftMQObjectFactory"
                  listenerName="plainsocket"
                  socketFactoryClass="com.swiftmq.net.PlainSocketFactory"
                  hostname="localhost"
                  port="4001"
                  keepaliveInterval="60000"
                  smqpProducerReplyInterval="20"
                  smqpConsumerCacheSize="500"
                  smqpConsumerCacheSizeKB="2048"
                  jmsDeliveryMode="2"
                  jmsPriority="4"
                  jmsTTL="0"
                  jmsMessageIdEnabled="true"
                  jmsMessageTimestampEnabled="true"
                  useThreadContextCL="true"
                  inputBufferSize="131072"
                  inputExtendSize="65536"
                  outputBufferSize="131072"
                  outputExtendSize="65536"
                  intraVM="false"
                  reconnectEnabled="false"
                  maxRetries="50"
                  retryDelay="1000"
                  duplicateMessageDetection="false"
                  duplicateBacklogSize="30000"
        />
        <Resource auth="Container"
                  name="jms/testqueue"
                  type="com.swiftmq.jms.QueueImpl"
                  factory="com.swiftmq.jndi.v400.SwiftMQObjectFactory"
                  queueName="testqueue@router1"
         />
      </Context>

The above example declares 2 objects: a JMS connection factory and a queue. It also declares all attribute values such as hostname, port, queueName etc. On a JNDI lookup, the JNDI object factory specified under attribute "factory" is used to create the object instance with all declared attribute values.

General Resource Attributes

General resource attributes are "auth", "name", "type" and "factory":

      ...
      <Resource auth="Container"
                name="jms/cf"
                type="com.swiftmq.jms.v610.ConnectionFactoryImpl"
                factory="com.swiftmq.jndi.v400.SwiftMQObjectFactory"
      ...
      <Resource auth="Container"
                name="jms/testqueue"
                type="com.swiftmq.jms.QueueImpl"
                factory="com.swiftmq.jndi.v400.SwiftMQObjectFactory"
      ...
      <Resource auth="Container"
                name="jms/testtopic"
                type="com.swiftmq.jms.TopicImpl"
                factory="com.swiftmq.jndi.v400.SwiftMQObjectFactory"
      ...
Attribute Description
auth Must be "Container".
name The name under which the object will be bound in Tomcat's JNDI tree. "jms/cf" stores it under "java:comp/env/jms/cf".
type The fully qualified class name of the object.
factory The fully qualified class name of the JNDI object factory. For SwiftMQ this is always "com.swiftmq.jndi.v400.SwiftMQObjectFactory".

Declaring JMS Connection Factories

The "type" attribute must contain the fully qualified class name of the connection factory. SwiftMQ's connection factories are versioned. The name is "com.swiftmq.jms.VERSION.ConnectionFactoryImpl" where VERSION can be v400, v500, v510, v600, v610, v630, v750. The SwiftMQ release corresponds with the connection factory version. For example, releases greater/equal 4.0.0 and less than 5.0.0 use v400, greater/equal 5.0.0 and less than 5.1.0 use v500 and so on.

Note that a "com.swiftmq.jms.VERSION.ConnectionFactoryImpl" implements ALL JMS connection factory interfaces such as javax.jms.ConnectionFactory, javax.jms.QueueConnectionFactory etc. There is no class such as "com.swiftmq.jms.VERSION.QueueConnectionFactoryImpl"!

The following table specifies the attributes which must be declared for a connection factory.

Attribute Recommended Value Description
listenerName N/A Name of the router's JMS listener, e.g. "plainsocket".
socketFactoryClass N/A Name of the Socket Factory class. Possible values: "com.swiftmq.net.PlainSocketFactory" or "com.swiftmq.net.JSSESocketFactory".
hostname N/A Host Name of the SwiftMQ Universal Router.
port N/A Port of the JMS listener.
hostname2 N/A Host Name HA instance 2. Since 6.0.0. Optional.
port2 N/A Port HA instance 2. Since 6.0.0. Optional.
keepaliveInterval "60000" SMQP Keep Alive Interval
clientId N/A Presets the JMS client id. Optional.
smqpProducerReplyInterval "20" Contains the interval after which a message producer waits on a reply and thus can act on flow control delays. This attributes takes only effect for non-persistent messages.
smqpConsumerCacheSize "500" Contains the size of the client message cache of message consumers. The router sends up to this size without waiting for a reply.
smqpConsumerCacheSizeKB "2048" Contains the maximum size in KB of the client message cache of message consumers. The router sends up to this size without waiting for a reply. Required for connection factories of protocol version v750 and above.
jmsDeliveryMode "2" Presets the JMS default delivery mode for message producers. "1" = non-persistent, "2" = persistent.
jmsPriority "4" Presets the JMS default message priority for message producers.
jmsTTL "0" Presets the JMS default message time-to-live for message producers.
jmsMessageIdEnabled "true" Presets whether a message id should be generated for produced messages.
jmsMessageTimestampEnabled "true" Presets whether a time stamp should be generated for produced messages.
useThreadContextCL "true" Presets whether the thread contex class loader should be used during the deserialization of objects returned from an ObjectMessage' getObject() method.
inputBufferSize "131072" Specifies the initial size in bytes of the JMS client's network input buffer.
inputExtendSize "65536" Specifies the extend size in bytes to increase the JMS client's network input buffer once it is full.
outputBufferSize "131072" Specifies the initial size in bytes of the JMS client's network output buffer.
outputExtendSize "65536" Specifies the extend size in bytes to increase the JMS client's network output buffer once it is full.
intraVM "false" Only for intraVM connections. Must alway be "false" for Tomcat.
reconnectEnabled "false" Enables transparent reconnect for JMS clients. Since 6.0.0.
maxRetries 10 Specifies the max. retries for reconnect attemts. Since 6.0.0.
retryDelay 10000 Specifies the delay in ms between reconnect retries. Since 6.0.0.
duplicateMessageDetection "false" Enables/disables duplicate message detection at the client side. Must be enabled if reconnect is enabled. Since 6.0.0.
duplicateBacklogSize 30000 Specifies the max. size of the duplicate backlog per connection (JMS Message Ids) at the client side. Since 6.0.0.

Declaring Queues

The "type" attribute must contain "com.swiftmq.jms.QueueImpl". There is 1 attribute "queueName" which must contain the fully qualified queue name (queuename@routername) such as "testqueue@router1".

Declaring Topics

The "type" attribute must contain "com.swiftmq.jms.TopicImpl". There is 1 attribute "topiceName" which must contain the topic name such as "testtopic".

Tomcat's web.xml

The web.xml must contain the resp. resource-ref's of the connection factories, queues and topics.

Example:

      <resource-ref>
        <res-ref-name>jms/cf</res-ref-name>
        <res-type>javax.jms.ConnectionFactory</res-type>
        <res-auth>Container</res-auth>
      </resource-ref>
      <resource-ref>
        <res-ref-name>jms/testqueue</res-ref-name>
        <res-type>javax.jms.Queue</res-type>
        <res-auth>Container</res-auth>
      </resource-ref>
      <resource-ref>
        <res-ref-name>jms/testtopic</res-ref-name>
        <res-type>javax.jms.Topic</res-type>
        <res-auth>Container</res-auth>
      </resource-ref>

Example

This example is a simple web application with 2 servlets to send and receive messages via SwiftMQ.

Download this example (war).

How to use the example:

  • Copy all jar files from SwiftMQ's "jars" directory to Tomcat's "shared/lib" resp "lib" (Tomcat 7) directory.
  • Start the SwiftMQ Universal Router on your local host.
  • Copy the above war-file to Tomcat's "webapps" directory.
  • Start Tomcat on your local host.
  • Connect to "http://localhost:8080/tomcatjms".
  • Send a message.
  • Receive a message.