Solace JMS Integration with Tomcat 7 · Solace JMS Integration with Tomcat 7.0 3 1 Overview This document demonstrates how to integrate Solace Java Message Service (JMS) with the

Copyright © Solace Systems, Inc.

http://www.solacesystems.com

Solace JMS Integration with Tomcat 7.0

Document Version 1.2

November 2015

This document is an integration guide for using Solace JMS as a JMS provider within Apache

Tomcat.

Tomcat is one of the first Apache projects and one of the first servlet engines, dating back to 1999

as a reference servlet engine built by Sun Microsystems engineers. These integration steps apply

to the Tomcat release version 7.0.

The Solace message router supports persistent and non-persistent JMS messaging with high

throughput and low, consistent latency. Thanks to very high capacity and built-in virtualization,

each Solace message router can replace dozens of software-based JMS brokers in multi-tenant

deployments. Since JMS is a standard API, client applications connect to Solace like any other

JMS broker so companies whose applications are struggling with performance or reliability issues

can easily overcome them by upgrading to Solace’s hardware.

http://www.solacesystems.com/


2

Table of Contents Solace JMS Integration with Tomcat 7.0..................................................................................... 1 Table of Contents ....................................................................................................................... 2 1 Overview .............................................................................................................................. 3

1.1 Related Documentation ................................................................................................................................... 3 2 Why Solace .......................................................................................................................... 4

Superior Performance ............................................................................................................................................. 4 Robustness ............................................................................................................................................................. 4 Simple Architecture ................................................................................................................................................. 4 Simple Operations .................................................................................................................................................. 4 Cost Savings .......................................................................................................................................................... 4

3 Integrating with Tomcat ........................................................................................................ 5 3.1 Description of Resources Required ................................................................................................................. 5

3.1.1 Solace Resources .................................................................................................................................................5 3.1.2 Tomcat Configuration ............................................................................................................................................5

3.2 Step 1 – Configuring the Solace message router ............................................................................................ 6 3.2.1 Creating a Message VPN ......................................................................................................................................7 3.2.2 Configuring Client Usernames & Profiles ..............................................................................................................7 3.2.3 Setting up Guaranteed Messaging Endpoints .......................................................................................................8 3.2.4 Setting up Solace JNDI References ......................................................................................................................8

3.3 Step 2 – Configuring the Tomcat JMS Resource Definitions ........................................................................... 9 3.3.1 Sample Resource Definitions .............................................................................................................................. 10 Sample ObjectFactory Implementation ......................................................................................................................... 11

3.4 Step 3 – Code – Integrating the Resources into Servlets .............................................................................. 12 3.5 Step 4 – Receiving Messages from Solace ................................................................................................... 13

3.5.1 Creating the JMS Listener ................................................................................................................................... 13 3.5.2 Sending Test Messages ...................................................................................................................................... 13

3.6 Debugging Tips for Tomcat and Solace JMS API Integration ........................................................................ 14 3.6.1 Logging via Apache Commons ........................................................................................................................... 14 3.6.2 Remote Debugging Tomcat ................................................................................................................................ 14

4 Working with Solace High Availability (HA) ......................................................................... 15 5 Appendix – Tomcat Initial Setup Primer .............................................................................. 16

5.1 Setting Up the Tomcat Server ....................................................................................................................... 16 5.1.1 Install Tomcat ..................................................................................................................................................... 16 5.1.2 Install the Solace Libraries in the Tomcat Lib ...................................................................................................... 17 5.1.3 Add the Solace Resource to the Server Context ................................................................................................. 17

5.2 Create a Servlet Project ................................................................................................................................ 17 5.2.1 Deploy the Servlet to Tomcat .............................................................................................................................. 17 5.2.2 Sample Servlet Code .......................................................................................................................................... 19


3

1 Overview This document demonstrates how to integrate Solace Java Message Service (JMS) with the Apache Tomcat

application server. The target audience of this document is developers building webapps and servlets that will

communicate via a JMS message bus.

This document is divided into the following sections:

o Introduction to the Solace Messaging Platform and the Solace setup for the samples contained within this

document

o Introduction to Tomcat Resource Definitions and customizations for Solace

o Steps to setup and run the sample

o Additional Tomcat setup primer for those who are unfamiliar with the setup process

1.1 Related Documentation These documents contain information related to the feature defined in this document

Document ID Document Title Document Source

[Solace-Portal] Solace Developer Portal http://dev.solacesystems.com

[Solace-JMS-REF] Solace JMS Messaging API Developer

Guide

http://dev.solacesystems.com/docs/solace-jms-

api-developer-guide

[Solace-JMS-API] Solace JMS API Online Reference

Documentation

http://dev.solacesystems.com/docs/solace-jms-

api-online-reference

[Solace-FG] Solace Messaging Platform – Feature

Guide

http://dev.solacesystems.com/docs/messaging-

platform-feature-guide

[Solace-FP] Solace Messaging Platform – Feature

Provisioning

http://dev.solacesystems.com/docs/messaging-

platform-feature-provisioning

[Solace-CLI] Solace Message Router Command Line

Interface Reference

http://dev.solacesystems.com/docs/cli-reference

[Tomcat-CFG] Apache Tomcat Configuration Reference https://tomcat.apache.org/tomcat-6.0-

doc/config/context.html

[Sakai-RDEB] Setting Up Tomcat for Remote Debugging https://confluence.sakaiproject.org/display/BOOT/

Setting+Up+Tomcat+For+Remote+Debugging

[Tomcat-DL] ApacheTomcat Download Page https://tomcat.apache.org/download-70.cgi

Table 1 - Related Documents

http://dev.solacesystems.com/

http://dev.solacesystems.com/docs/solace-jms-api-developer-guide

http://dev.solacesystems.com/docs/solace-jms-api-developer-guide

http://dev.solacesystems.com/docs/solace-jms-api-online-reference

http://dev.solacesystems.com/docs/solace-jms-api-online-reference

http://dev.solacesystems.com/docs/messaging-platform-feature-guide

http://dev.solacesystems.com/docs/messaging-platform-feature-guide

http://dev.solacesystems.com/docs/messaging-platform-feature-provisioning

http://dev.solacesystems.com/docs/messaging-platform-feature-provisioning

http://dev.solacesystems.com/docs/cli-reference

https://tomcat.apache.org/tomcat-6.0-doc/config/context.html

https://tomcat.apache.org/tomcat-6.0-doc/config/context.html

https://confluence.sakaiproject.org/display/BOOT/Setting+Up+Tomcat+For+Remote+Debugging

https://confluence.sakaiproject.org/display/BOOT/Setting+Up+Tomcat+For+Remote+Debugging

https://tomcat.apache.org/download-70.cgi


4

2 Why Solace Solace technology efficiently moves information between all kinds of applications, users and devices, anywhere in the

world, over all kinds of networks. Solace makes its state-of-the-art data movement capabilities available via hardware

and software “message routers” that can meet the needs of any application or deployment environment. Solace’s

unique solution offers unmatched capacity, performance, robustness and TCO so our customers can focus on seizing

business opportunities instead of building and maintaining complex data distribution infrastructure.

Superior Performance Solace’s hardware and software messaging middleware products can cost-effectively meet the performance needs of

any application, with feature parity and interoperability that lets companies start small and scale to support higher

volume or more demanding requirements over time, and purpose-built appliances that offer 50-100x higher

performance than any other technology for customers or applications that require extremely high capacity or low

latency.

Robustness Solace offers high availability (HA) and disaster recovery (DR) without the need for 3rd party products, and fast failover

times no other solution can match. Distributing data via dedicated TCP connections ensures an orderly, well-behaved

system under load, and patented techniques ensure that the performance of publishers and high-speed consumers is

never impacted by slow consumers.

Simple Architecture Modern enterprises run applications that demand many kinds of data movement such as persistent messaging, web

streaming, WAN distribution and cloud-based communications. By supporting all kinds of data movement with a unified

platform that can be deployed as a small-footprint software broker or high-capacity rack-mounted appliance, Solace lets

architects design an end-to-end infrastructure that’s easy to build applications for, integrate with existing technologies,

secure and scale.

Simple Operations Solace’s solution features a shared administration framework for all kinds of data movement, deployment models and

network environments so it’s easy for IT staff to deploy, monitor, manage and upgrade their Solace-based messaging

environment.

Cost Savings Solace reduces expenses with high-capacity hardware, flexible software, and the ability to deploy the right solution for

each problem. Solace’s support for many kinds of messaging lets you replace multiple messaging products with just

one, built-in HA, DR, WAN and Web functionality eliminate the need for third-party products.


5

3 Integrating with Tomcat Tomcat does not implement all JEE specifications so it cannot make use of the Solace JCA Adapter for integration; it

requires different integration in the core Context JNDI store that can then be used by the rest of the Tomcat

components. Looking up resources in the Tomcat JNDI store requires a javax.naming.spi.ObjectFactory

implementation for each platform being integrated. Since there is no existing implementation for JMS, a small library

with an implementation will have to be added to your Tomcat libraries. A sample implementation is provided in this

document.

3.1 Description of Resources Required This integration guide will demonstrate creation of Solace resources and configuration of Tomcat. This section outlines

the resources that are created and used in the subsequent sections.

3.1.1 Solace Resources

The following Solace message router resources are required.

Resource Value Description

Solace message

router IP:Port

__IP:Port__ The IP address and port of the Solace message router message

backbone. This is the address clients use when connecting to the

Solace message router to send and receive message. This

document uses a value of __IP:PORT__.

Message VPN Solace_VPN A Message VPN, or virtual message broker, to scope the integration

on the Solace message router.

Client Username app_user The client username.

Client Password app_password Optional client password.

Solace Queue sample_queue Solace destination of messages produced and consumed

JNDI Connection

Factory

JNDI/CF The JNDI Connection factory for controlling Solace JMS connection

properties

JNDI Queue Name JNDI/sample_queue The JNDI name of the queue used in the samples

Table 2 – Solace Configuration Resources

3.1.2 Tomcat Configuration

Tomcat has an internal JNDI service that servlets and JSP pages can use to lookup resources. The standard way to

retrieve and instantiate JNDI resources in the local store is via an ObjectFactory. In Tomcat, this is done by adding a

Resource Definitions to the Tomcat context.xml configuration file. This resource definitely contains a set of attributes

that pertain to the Tomcat Catalina container, but any other attributes can be added for particular implementations that

will be passed through to the ObjectFactory. The standard Tomcat attributes are as follows:

Attribute Description

auth Specify whether the web Application code signs on to the corresponding resource manager

programatically, or whether the Container will sign on to the resource manager on behalf of the

application. The value of this attribute must be Application or Container. This attribute is

required if the web application will use a <resource-ref> element in the web application

deployment descriptor, but is optional if the application uses a <resource-env-

https://tomcat.apache.org/tomcat-6.0-doc/config/context.html#Resource Definitions


6

ref> instead.

description Optional, human-readable description of this resource.

name The name of the resource to be created, relative to the java:comp/env context. This is for

lookup/reference within the Tomcat container and servlets. E.g., servlet code wishing to have

the resource injected into a member variable can add a @Resource(name=<name>)

attribute to the member variable and the Tomcat container will take care of the rest.

scope Specify whether connections obtained through this resource manager can be shared. The

value of this attribute must be Shareable or Unshareable. By default, connections are

assumed to be Shareable.

type The fully qualified Java class name expected by the web application when it performs a lookup

for this resource.

In Section 3.3 we will discuss how to customize this element for Solace resources.

3.2 Step 1 – Configuring the Solace message router The Solace message router needs to be configured with the following configuration objects at a minimum to enable

sending and receiving messages via the Solace JMS API.

o A Message VPN, or virtual message broker, to scope the integration on the Solace message router.

o Client connectivity configurations like usernames and profiles

o Guaranteed messaging endpoints for receiving messages.

o Appropriate JNDI mappings enabling JMS clients to connect to the Solace message router configuration.


7

For reference, the CLI commands in the following sections are from SolOS version 7.1 but will generally be forward

compatible. For more details related to Solace message router CLI see [Solace-CLI]. Wherever possible, default values

will be used to minimize the required configuration. The CLI commands listed also assume that the CLI user has a

Global Access Level set to Admin. For details on CLI access levels please see [Solace-FG] section “CLI User

Authentication and Authorization”.

Also note that this configuration can also be easily performed using SolAdmin, Solace’s GUI management tool. This is

in fact the recommended approach for configuring a Solace message router. This document uses CLI as the reference

to remain concise.

3.2.1 Creating a Message VPN

This section outlines how to create a message-VPN called “Solace_VPN” on the Solace message router with

authentication disabled and 2GB of message spool quota for Guaranteed Messaging. This message-VPN name is

required in the Tomcat configuration when connecting to the Solace message router. In practice appropriate values for

authentication, message spool and other message-VPN properties should be chosen depending on the end

application’s use case.

(config)# create message-vpn Solace_VPN

(config-msg-vpn)# authentication

(config-msg-vpn-auth)# user-class client

(config-msg-vpn-auth-user-class)# basic auth-type none

(config-msg-vpn-auth-user-class)# exit

(config-msg-vpn-auth)# exit

(config-msg-vpn)# no shutdown

(config-msg-vpn)# exit

(config)#

(config)# message-spool message-vpn Solace_VPN

(config-message-spool)# max-spool-usage 2000

(config-message-spool)# exit

(config)#

3.2.2 Configuring Client Usernames & Profiles

This section outlines how to update the default client-profile and how to create a client username for connecting to the

Solace message router. For the client-profile, it is important to enable guaranteed messaging for JMS messaging and

transacted sessions if using transactions.

The chosen client username of “app_user” will be required by the Mule when connecting to the Solace message router.

(config)# client-profile default message-vpn Solace_VPN

(config-client-profile)# message-spool allow-guaranteed-message-receive

(config-client-profile)# message-spool allow-guaranteed-message-send

(config-client-profile)# message-spool allow-transacted-sessions

(config-client-profile)# exit

(config)#

(config)# create client-username app_user message-vpn Solace_VPN

(config-client-username)# acl-profile default

(config-client-username)# client-profile default


8

(config-client-username)# no shutdown

(config-client-username)# exit

(config)#

3.2.3 Setting up Guaranteed Messaging Endpoints

This integration guide shows receiving messages from a single JMS Queue in a Mule Flow. For illustration purposes,

this queue is chosen to be an exclusive queue with a message spool quota of 2GB matching quota associated with the

message VPN. The queue name chosen is “sample_queue”.

(config)# message-spool message-vpn Solace_VPN

(config-message-spool)# create queue sample_queue

(config-message-spool-queue)# access-type exclusive

(config-message-spool-queue)# max-spool-usage 2000

(config-message-spool-queue)# permission all delete

(config-message-spool-queue)# no shutdown

(config-message-spool-queue)# exit

(config-message-spool)# exit

(config)#

3.2.4 Setting up Solace JNDI References

To enable the JMS clients to connect and look up the Queue destination required by Mule, there are two JNDI objects

required on the Solace message router:

o A connection factory: JNDI/CF

o A queue destination: JNDI/sample_queue


9

They are configured as follows:

(config)# jndi message-vpn Solace_VPN

(config-jndi)# create connection-factory JNDI/CF

(config-jndi-connection-factory)# property-list messaging-properties

(config-jndi-connection-factory-pl)# property default-delivery-mode persistent

(config-jndi-connection-factory-pl)# exit

(config-jndi-connection-factory)# property-list transport-properties

(config-jndi-connection-factory-pl)# property direct-transport false

(config-jndi-connection-factory-pl)# property "reconnect-retry-wait" "3000"

(config-jndi-connection-factory-pl)# property "reconnect-retries" "20"

(config-jndi-connection-factory-pl)# property "connect-retries-per-host" "5"

(config-jndi-connection-factory-pl)# property "connect-retries" "1"


(config-jndi-connection-factory)# exit

(config-jndi)#

(config-jndi)# create queue JNDI/sample_queue

(config-jndi-queue)# property physical-name sample_queue

(config-jndi-queue)# exit

(config-jndi)#

(config-jndi)# no shutdown

(config-jndi)# exit

(config)#

3.3 Step 2 – Configuring the Tomcat JMS Resource Definitions For all JMS platforms, platform JMS resources are outside the Tomcat context in a separate JNDI store. So a custom

ObjectFactory is needed that knows how to instantiate a separate InitialContext, populate it with all the

necessary properties, and lookup the resource via whatever name in that external store it is stored under. They are

looked up by adding to the Resource Definition all the standard javax.naming.* parameters typically used to

configure a JMS InitialContext. The custom ObjectFactory can interpret these values appropriate to the

implementation. ActiveMQ and JBoss provide their own customized ObjectFactory behavior; we have modelled the

Solace sample to be consistent with the patterns employed by these other JMS vendors.

The custom attributes for Solace/JNDI lookup are as follows:

Attribute Description

factory

The fully qualified Java class name for the custom ObjectFactory creating

these objects. This class should implement the

javax.naming.spi.ObjectFactory interface.

factory.name The end resource name to be found in the target JNDI context.

javax.naming.factory.initial The type to use in creating a JNDI InitialContext for looking up JMS


10

resources.

javax.naming.provider.url The destination connection string to pass into the InitialContext to connect

and lookup resources.

javax.naming.security.principal The Solace client-username to authenticate as in the target JNDI context.

javax.naming.security.credentials The password for the configured javax.naming.security.principal in

authentication.

3.3.1 Sample Resource Definitions

Here are some sample Solace Resource Definitions. These examples presume the fully qualified Java type for our

custom ObjectFactory class is com.solacesystems.naming.JmsResourceFactory.

ConnectionFactory Configuration:

<Resource name="jms/ConnectionFactory"

auth="Container"

type="javax.jms.ConnectionFactory"

description="JMS Connection Factory"

factory="com.solacesystems.naming.JmsResourceFactory"

factory.name="JNDI/CF"

java.naming.factory.initial="com.solacesystems.jndi.SolJNDIInitialContextFactory"

java.naming.provider.url="smf://__IP:PORT__"

java.naming.security.principal="app_user@Solace_VPN"

java.naming.security.credentials="password" />

Queue Configuration:

<Resource name="jms/Queue"

auth="Container"

type="javax.jms.Queue"

description="Solace Queue"


factory.name="JNDI/sample_queue"






11

Topic Configuration:

<Resource name="jms/Topic"

auth="Container"

type="javax.jms.Topic"

description="JMS Topic"


factory.name="JNDI/topic"





Sample ObjectFactory Implementation

Sample custom ObjectFactory code that provides the above functionality is as follows:

package com.solacesystems.naming;

public class JmsResourceFactory implements javax.naming.spi.ObjectFactory {

public Object getObjectInstance(Object obj,

javax.naming.Name name,

javax.naming.Context nameCtx,

java.util.Hashtable<?, ?> environment) throws Exception {

javax.naming.Reference reference = (javax.naming.Reference) obj;

java.util.Properties properties = new java.util.Properties();

String factoryName = null;

java.util.Enumeration addresses = reference.getAll();

while (addresses.hasMoreElements()) {

javax.naming.RefAddr address = (javax.naming.RefAddr)

addresses.nextElement();

String type = address.getType();

String content = (String) address.getContent();

if (type != null) {

if (type.equalsIgnoreCase("factory.name")) {

factoryName = content;

} else if (type.startsWith("java.naming.")) {

properties.put(type, content);

}

}


12

}

if (properties.size() < 1)

throw new IllegalArgumentException("InitialContext properties not

specified!");

if (factoryName == null)

throw new IllegalArgumentException("JNDI resource to lookup not specified!");

javax.naming.Context context = new javax.naming.InitialContext(properties);

return context.lookup(factoryName);

}

}

Note that this sample implementation just provides generic JNDI lookups. It should work for any compliant JNDI

implementation. The implementation could also provide any desired customized behavior and take customized

parameters. For example, the ActiveMQ implementation supports a physical-name Resource Definition parameter

which forces instantiation of the resource type directly, without going through any generic JMS or JNDI intermediary.

The Solace implementation could be enhanced to do this as well.

3.4 Step 3 – Code – Integrating the Resources into Servlets Once the Resource Definitions have been defined and the custom ObjectFactory code has been deployed, servlets

can integrate those resources via a kind of dependency injection by ‘tagging’ member variables for injection with a

@Resource attribute:

public class solwebsample extends HttpServlet implements MessageListener {

private Log log = LogFactory.getLog(solwebsample.class);

@Resource(name = "jms/ConnectionFactory")

private ConnectionFactory connectionFactory;

@Resource(name = "jms/Queue")

private Queue queue;

@Resource(name = "jms/Topic")

private Topic topic;

// …

}

The types of the members must match the types of the resources returned by the ObjectFactory implementation;

otherwise the servlet will fail at initialization phase. Also note that the name of the @Resource attribute in the servlet

code must match the name of the Resource Definition in the context.xml file.


13

3.5 Step 4 – Receiving Messages from Solace

3.5.1 Creating the JMS Listener

Now that the JMS connection factory and destination are available to the servlet, the rest is just standard JMS

programming:

import javax.annotation.Resource;

import javax.jms.*;

import javax.servlet.*;

import javax.servlet.http.*;



private ConnectionFactory connectionFactory;


private Queue queue;

private MessageConsumer queueConsumer;

private Connection conn;

private Session sess;

public void onMessage(Message message) {

System.out.println("GOT MESSAGE: " + message);

}

public void init(ServletConfig conf) throws ServletException {

super.init(conf);

try {

conn = connectionFactory.createConnection();

sess = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);

queueConsumer = sess.createConsumer(queue);

queueConsumer.setMessageListener(this);

conn.start();

}

catch(Exception ne) {

ne.printStackTrace();

}

}

}

There is a full sample program available in Section 5.2.2 of the Appendix.

3.5.2 Sending Test Messages


14

For receivers, the simplest way to test the application is to send messages to it via an external load-generating tool; we

recommend SDKPerf for this which is available for download in the Solace Developer Portal. There is a version for all

our APIs. Here is an example using the SDKPerf JMS testing tool to do the following:

1. Authenticate as the Solace client-username app_user 2. Lookup the following resources from the Solace JNDI store:

a. JMS Connection-Factory named JNDI/CF to use for creating the JMS connection b. JMS Queue named JNDI/sample_queue as the destination to publish messages

3. Publish 10 messages to the JMS queue at a rate of 1 message per second 4. Exit when finished publishing

sdkperf_jms.bat –cip=smf://<ip-address>:<port> -cu=app_user –jcf=JNDI/CF –

pql=JNDI/sample_queue –mn=10 –mr=1 –msa=10

You can verify that your Servlet received the messages by watching for messages written to the console by the Tomcat

process.

3.6 Debugging Tips for Tomcat and Solace JMS API Integration

3.6.1 Logging via Apache Commons

Tomcat has a builtin logging facilty but that facility has changed significantly over the lifetime of the project. As of

Tomcat 6, you can always log via commons-logging which is also the framework of choice for Solace’s Java APIs, so

that is the recommended option.

For more primitive logging, Tomcat does not swallow the standard System.out and System.err output streams, so you

can always log directly to those streams and watch the Tomcat console output for your messages.

3.6.2 Remote Debugging Tomcat

If you would like to inspect the integration or servlet code at runtime under a debugger, Tomcat can be configured for

remote debugging using JPDA.

This is not something that we have done but it has been documented at [Sakai-RDEB].

http://dev.solacesystems.com/downloads/


15

4 Working with Solace High Availability (HA) The [Solace-JMS-REF] section “Establishing Connection and Creating Sessions” provides details on how to enable the

Solace JMS connection to automatically reconnect to the standby appliance in the case of a HA failover of a Solace

message router. By default Solace JMS connections will reconnect to the standby appliance in the case of an HA

failover.

In general the Solace documentation contains the following note regarding reconnection:

Note: When using HA redundant appliances, a fail-over from one appliance to its mate will typically occur in

under 30 seconds, however, applications should attempt to reconnect for at least five minutes.

In section 3.2.4 Setting up Solace JNDI References, the Solace CLI commands correctly configured the required JNDI

properties to reasonable values. These commands are repeated here for completeness.

config)# jndi message-vpn Solace_VPN

(config-jndi)# create connection-factory JNDI/CF

(config-jndi-connection-factory)# property-list transport-properties

(config-jndi-connection-factory-pl)# property "reconnect-retry-wait" "3000"

(config-jndi-connection-factory-pl)# property "reconnect-retries" "20"

(config-jndi-connection-factory-pl)# property "connect-retries-per-host" "5"

(config-jndi-connection-factory-pl)# property "connect-retries" "1"


(config-jndi-connection-factory)# exit

(config-jndi)# exit

(config)#


16

5 Appendix – Tomcat Initial Setup Primer The following appendices are added for Tomcat novices requiring more specific setup steps. They have been verified

with Tomcat v7.0.64 only.

5.1 Setting Up the Tomcat Server It’s better to actually start with a downloaded package instead of using a Linux package-manager to install in the

system’s favorite places.

5.1.1 Install Tomcat

Download from Apache.org and unzip/untar locally [Tomcat-DL].

You will need to add a user to the conf/tomcat-users.conf manager-gui group to be able to access the manager pages:

<?xml version='1.0' encoding='utf-8'?>

<tomcat-users>

<role rolename="tomcat"/>

<user username="tomcat" password="tomcat" roles="tomcat,manager-gui"/>

</tomcat-users>

Manage the server via ./bin/startup. [sh|bat] and ./bin/shutdown.[sh|bat]. The default port is 8080.

Connecting to localhost:8080 should show a screen like the following; follow the link on the right side to “Manage” the

servlet container:

You should be prompted for a user/password, which should be the user you setup and added to the manager-ui group.

(The default is tomcat/tomcat.)

Make sure you are able to view the Management page before moving on.


17

5.1.2 Install the Solace Libraries in the Tomcat Lib

This is because we will add Solace resources to the server context, making them available to all services running on

that server so the libraries will need to be part of the server.

Install the library with the custom ObjectFactory as well.

5.1.3 Add the Solace Resource to the Server Context

This is the important bit. A lot of different web-pages muck around with putting things in the

‘GlobalNamingResources’ of the [TOMCAT]/conf/server.xml, then adding ‘ResourceLink’ nodes to the

[TOMCAT]/conf/context.xml, or putting them in the application’s web.xml file. Don’t bother.

Just add the resource configuration to the server’s [TOMCAT]/conf/context.xml and IT WILL BE AVAILABLE TO

ANY DEPLOYED APPLICATION. If you have problems accessing it, do not flail around putting the Resource in

different places. Concentrate on fixing your application.

5.2 Create a Servlet Project Create a webapp/servlet project with whatever your preferred toolset; HttpServlet is recommended for ease of use.

Package your build artifacts as a .WAR file, as that is the easiest way to deploy the app to Tomcat.

5.2.1 Deploy the Servlet to Tomcat

You will need to add a mapping for your servlet to the web-application web.xml file. E.g.:


18

<!DOCTYPE web-app PUBLIC

"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"

"http://java.sun.com/dtd/web-app_2_3.dtd" >

<web-app>

<display-name>Archetype Created Web Application</display-name>

<servlet>

<servlet-name>sample</servlet-name>

<servlet-class>com.solacesystems.poc.solwebsample</servlet-class>

</servlet>

<servlet-mapping>

<servlet-name>sample</servlet-name>

<url-pattern>/sample</url-pattern>

</servlet-mapping>

</web-app>

Deploy the Servlet to the Tomcat container via the Management page, using the file-upload deployment method. This

will take the uploaded WAR file, and extract it into the /webapps directory while also registering the app with the

server. If you simply copy all your content into /webapps it will not be available via the Tomcat web-server and you will

be sad.

Then navigate to it via: http://localhost:8080/<webappname>/<mapped-servletname>

Does your basic servlet work? Now start integrating JMS into it; I typically start with a listener.


19

5.2.2 Sample Servlet Code

The following sample HttpServlet code uses @Resource injection to retrieve a JMS ConnectionFactory, Queue and

Topic via the sample ObjectFactory. Then it subscribes to both destinations, and in all GET requests to the servlet,

presents the latest count of received messages on all subscriptions.

package com.solacesystems.poc;

import org.apache.commons.logging.Log;

import org.apache.commons.logging.LogFactory;

import javax.annotation.Resource;

import javax.jms.*;

import javax.servlet.*;

import javax.servlet.http.*;

import java.io.IOException;

import java.io.PrintWriter;


private Log log = LogFactory.getLog(solwebsample.class);


ConnectionFactory connectionFactory;


Queue queue;

MessageConsumer queueConsumer;

@Resource(name = "jms/Topic")

Topic topic;

MessageConsumer topicConsumer;

private Connection conn;

private Session sess;

private String status;

private int count = 0;

@Override

public void onMessage(Message message) {

++count;


20

log.info("GOT MESSAGE! " + message);

}

public void init(ServletConfig conf) throws ServletException {

log.info("Entering solwebsample.init");

super.init(conf);

try {

if (conn == null) {

log.info("Creating a connection");

conn = connectionFactory.createConnection();

}

if (sess == null) {

log.info("Creating a session");

sess = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);

}

if (topicConsumer == null) {

log.info("Creating topic consumer");

topicConsumer = sess.createConsumer(topic);

topicConsumer.setMessageListener(this);

}

if (queueConsumer == null) {

log.info("Creating queue consumer");

queueConsumer = sess.createConsumer(queue);

queueConsumer.setMessageListener(this);

}

conn.start();

status = "SUCCESS";

}

catch(Exception ne) {

log.error(ne);

status = ne.toString();

}

}

public void doGet(HttpServletRequest request, HttpServletResponse response)

throws ServletException

{

response.setContentType("text/html");

try {


21

PrintWriter out = response.getWriter();

out.println("<html><body>");

out.println("<h1>Hello World</h1>");

out.println(status);

out.println("Count: " + count);

out.println("</body></html>");

}

catch(IOException e) {

e.printStackTrace();

}

}

}