Welcome to my Tomcat tutorials website!

martedì 20 gennaio 2009

Tomcat axis tutorial

Axis is essentially a SOAP engine, that is a framework for constructing SOAP processors such as clients, servers, gateways, etc.

Installing Axis on Tomcat

At first download Axis from the Apache project:


Explode the zip folder. Now you need to deploy the Axis engine to Tomcat: Here's how to do it:

Rename the folder axis under AXIS_HOME/webapps to axis.war and copy the folder under "webapps" of your tomcat

Verify that Axis has been deployed correctly:


Publishing Web Services with Axis

Let's say we have a simple class like the following:

package test;

public class HelloWorld {

public String hello(String message) {

return "Invoked with" +message;


How do we go about making this class available via SOAP? There are a couple of answers to that
question, but we'll start with an easy solution.

At first compile the class :

javac -d . HelloWorld.java

Now copy the class under WEB-INF/classes of your axis.war

Ok, now the last step is registering your Web Service so that Axis is aware of it. A Web Service can be registered with a Deployment Descriptor (WSDD) file. A deployment descriptor contains a bunch of things you want to "deploy" into Axis - i.e. make available to the Axis engine.

Here's a simple wsdd file for our WebService:


<service name="HelloWorld" provider="java:RPC">
<parameter name="className" value="test.HelloWorld"/>
<parameter name="allowedMethods" value="*"/>

Pretty simple, really - the outermost element tells the engine that this is a WSDD deployment,and defines the "java" namespace. Then the service element actually defines the service for us. A service is a targeted chain which means it may have any of: a request flow, a provider, and a response flow.

In this case, our provider is "java:RPC", which is built into Axis, and indicates a Java RPC service. We need to tell the RPCProvider that it should instantiate and call the correct class (e.g. test.HelloWorld), and another to tell the engine that any public method on that class may be called via SOAP (that's what the "*" means)

Now save your wsdd file as deploy.wsdd and run the AdminClient which is an Utility to deploy the WebService

java -classpath %AXIS_HOME%/lib/axis.jar;%AXIS_HOME%/lib/commons-discovery-0.2.jar;%AXIS_HOME%/lib/commons-logging-1.0.4.jar;%AXIS_HOME%/lib/saaj.jar;%AXIS_HOME%/lib/jaxrpc.jar org.apache.axis.client.AdminClient deploy.wsdd

If everything was Ok now you should see the WebService deployed on Axis: check the "List" option from the URL http://localhost:8080/axis/

The client

Let's take a look at an example Web Service client that will call the hello method of the HelloWorld Web Service

package test;

import org.apache.axis.client.Call;
import org.apache.axis.client.Service;
import javax.xml.namespace.QName;
import java.net.URL;

public class Client {

public static void main (String args[]) {

try {

String url;


Service service = new Service();

Call call = (Call)service.createCall();

call.setTargetEndpointAddress(new URL(url));

call.setOperationName(new QName("HelloWorld", "hello"));

Object[] params = new Object[1];

params[0] = "Hello Message";

Object result = call.invoke(params);

System.out.println("result is " + result);


catch(Exception e) {





In order to invoke our Web Service we use the Service and Call objects. These are the
standard JAX-RPC objects that are used to store metadata about the service to invoke.

With this we set up our endpoint URL - this is the destination for our SOAP message.

call.setTargetEndpointAddress(new URL(url));

With this we define the operation (method) name of the Web Service.

call.setOperationName(new QName("HelloWorld", "hello"));

Then we actually invoke the desired service, passing in an array of parameters - in this case just one String.

Object result = call.invoke(params);
Obtaining WSDL for deployed services
When you make a service available using Axis, there is typically a unique URL associated with that service. For our service it's http://localhost:8080/axis/services/HelloWorld?wsdl
When you point your browser to that location, Axis will automatically generate a service description for the deployed service, and return it as XML in your browser :

<?xml version="1.0" encoding="UTF-8" ?>
<wsdl:message name="helloRequest">
<wsdl:part name="in0" type="xsd:string" />
<wsdl:message name="helloResponse">
<wsdl:part name="helloReturn" type="xsd:string" />
<wsdl:portType name="HelloWorld">
<wsdl:operation name="hello" parameterOrder="in0">
<wsdl:input message="impl:helloRequest" name="helloRequest" />
<wsdl:output message="impl:helloResponse"
name="helloResponse" />
<wsdl:binding name="HelloWorldSoapBinding" type="impl:HelloWorld">
<wsdlsoap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/http" />
<wsdl:operation name="hello">
<wsdlsoap:operation soapAction="" />
<wsdl:input name="helloRequest">
namespace="http://test" use="encoded" />
<wsdl:output name="helloResponse">
use="encoded" />
<wsdl:service name="HelloWorldService">
<wsdl:port binding="impl:HelloWorldSoapBinding"
location="http://localhost:8080/axis/services/HelloWorld" />

Generating Java Classes from WSDL

Another approach is to generate Java Classes starting from WSDL contract. You can use the
AdminClient to follow this approach:

java -classpath %AXIS_HOME%/lib/wsdl4j-1.5.1.jar;%AXIS_HOME%/lib/axis.jar;%AXIS_HOME%/lib/commons-discovery-0.2.jar;%AXIS_HOME%/lib/commons-logging-1.0.4.jar;%AXIS_HOME%/lib/saaj.jar;%AXIS_HOME%/lib/jaxrpc.jar org.apache.axis.wsdl.WSDL2Java http://localhost:8080/axis/services/HelloWorld?wsdl

This will generate the following classes under the service namespace which is localhost\axis\services\HelloWorld


lunedì 19 gennaio 2009

Tomcat maxThreads configuration

Tomcat maxThreads represents the maximum number of request
processing threads to be created by the HTTPConnector.

<Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol"
           maxThreads="250" SSLEnabled="true" scheme="https" secure="true"
           clientAuth="false" sslProtocol="TLS" connectiontimeout="20000"/>

This determines the maximum number of simultaneous requests that can be handled. If not specified, this attribute is set to the default value of 200.

How the process works:
  • At server startup, the HTTP Connector will create a number of processing threads based on the value configured for the minSpareThreads attribute.
  • Each incoming request requires a thread for the duration of that request.
  • If the number of simultaneous requests cannot be handled by the currently available request processing threads, additional threads will be created up to the configured maximum (the value of the maxThreads attribute).
  • If still more simultaneous requests are received, they are stacked up up to the configured maximum (the value of the acceptCount attribute).
  • Any further simultaneous requests will receive "connection refused" errors, until resources are available to process them.
Guidelines for maxThreads:
maxThreads is an important tuning parameter, however if you are reaching an error like:
org.apache.tomcat.util.threads.ThreadPool logFull SEVERE: All threads (150) are
currently busy, waiting. Increase maxThreads (150) or check the servlet status
you should at first investigate if it's rather a problem of individual requests taking too long: are your threads returning to the pool? if, for example, database connections are not released, threads pile up waiting to obtain a database connection thereby making it impossible to process additional requests. This is a problem in your webapp. Take a thread dump to find out where they're stuck.
Increasing too much maxThreads will lead to :
  • Consume a good chunk of memory.
  • Your system will spend too much time context switching
So once you have already optimized your application try raising you maxThread attribute up to 500-750. I wouldn't advice to create larger Connectors, rather if 750 Connections are not enough create a Cluster configuration with several Tomcat instances. For example 2 instances of tomcat each one with maxThreads=500 instead of a single Tomcat with maxThreads=1000

Monitoring Tomcat maxThreads

You can monitor Tomcat maxThreads by logging into the Manager Web application which is available at: http://localhost:8080/manager

Once logged into the Manager application (See this tutorial to learn how to create un user for the Manager application), click on the Server Status link. At the bottom of the Server status link you will see this information:

There you can gather important information such as:
  • The number of Max threads 
  • The current thread count 
  • The current thread busy 
  • The Max processing time 
  • The Request count 
  • The Error count   
  • The Bytes received  
  • The Bytes sent 

If you want to learn more about JDK tuning read this tutorial which contains many tips valid also for Tomcat:JBoss Performance Tuning

mercoledì 14 gennaio 2009

Tomcat context listener example

When a web application is deployed a servlet context object, ServletContext, is created and associated with the web application. There is a one-to-one relationship between a servlet context object and the web application. All resources within the web application, such as servlets and JSPs, can retrieve any information stored in the servlet context.

As a web application programmer, you may want to initialize objects and place them in the servlet context when it is created and destroy the objects when the servlet context is destroyed.

For example, you may decide to create a connection to a database when the servlet context is created and close the connection when the servlet context is destroyed.

To write an application lifecycle event listener that executes when the servlet context is created and destroyed, write a Java class that implements the javax.Servlet.ServletContextListener class.

This class has two methods with the following signatures (taken from the JavaDocs):

  • void contextDestroyed (ServletContextEvent sce) Notification that the Servlet context is about to be shut down.
  • void contextInitialized (ServletContextEvent sce) Notification that the Web Application is ready to process requests

The Servlet 2.3 specification allows for more interaction between the web application programmer and ServletContext. The programmer can now write an application lifecycle event listener that executes when the attributes of the ServletContext object have been modified.

If you want to execute some code when the attributes of the ServletContext object has been modified, write a Java class that implements the javax.Servlet.ServletContextAttributesListener interface. This interface defines three methods with the following signatures (this is taken from the JavaDocs):

  • void attributeAdded (ServletContextAttributeEvent scab) Notification that a new attribute was added to the servlet context.
  • void attributeRemoved (ServletContextAttributeEvent scab) Notification that an existing attribute has been removed from the servlet context.
  • void attributeReplaced (ServletContextAttributeEvent scab) Notification that an attribute on the servlet context has been replaced.

Here's a sample class which implements both ServletContextListener and ServletContextAttributesListener :

import javax.servlet.ServletContext;
import javax.servlet.ServletContextAttributeEvent;
import javax.servlet.ServletContextAttributeListener;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;

public class ServletContextAttribListener
implements ServletContextAttributeListener,ServletContextListener {

private ServletContext context = null;

//This method is invoked when an attribute
//is added to the ServletContext object
public void attributeAdded (ServletContextAttributeEvent scab)
System.out.println("An attribute was added to the " +
"ServletContext object");

//This method is invoked when an attribute
//is removed from the ServletContext object
public void attributeRemoved (ServletContextAttributeEvent scab)
System.out.println("An attribute was removed from " +
"the ServletContext object");

//This method is invoked when an attribute
//is replaced in the ServletContext object
public void attributeReplaced (ServletContextAttributeEvent scab)
System.out.println("An attribute was replaced in the " +
"ServletContext object");

public void contextDestroyed(ServletContextEvent event)

//Output a simple message to the server's console
System.out.println("The Simple Web App. Has Been Removed");
this.context = null;


//This method is invoked when the Web Application
//is ready to service requests

public void contextInitialized(ServletContextEvent event)
this.context = event.getServletContext();

//Output a simple message to the server's console
System.out.println("The Simple Web App. Is Ready");



martedì 13 gennaio 2009

Tomcat session listener example

As part of Servlet 2.3 specification, we can now make use of session creation and destruction events. Our listener object will be called every time a session is created or destroyed by the server.

You can use two interfaces as listener for your Session:

  • HttpSessionListener triggers the listener when a new session is created or destroyed
  • HttpSessionBindingListener triggers the listener when an Object is bound/unbound from the Session
HttpSessionListener example:

package com.sample;

import javax.servlet.http.HttpSessionListener;
import javax.servlet.http.HttpSessionEvent;

public class SessionCounter implements HttpSessionListener {

private static int activeSessions = 0;

public void sessionCreated(HttpSessionEvent se) {

public void sessionDestroyed(HttpSessionEvent se) {

if(activeSessions > 0)

public static int getActiveSessions() {
return activeSessions;


As you can see, all you have to do is implementing two methods: sessionCreated() method
will be called by the server every time a session is created and sessionDestroyed() method will be called every time a session is invalidated or destroyed.

In order to activate the listener, you have to configure it in your web.xml


HttpSessionBindingListener example :

import java.sql.*;
import javax.servlet.http.*;

public class JDBCQueryBean implements HttpSessionBindingListener
  public void JDBCQueryBean() {   }

  private Connection conn = null;

  private void runQuery() {
    StringBuffer sb = new StringBuffer();
    Statement stmt = null;
    ResultSet rset = null;
    try {
      if (conn == null) {
        DriverManager.registerDriver(new .OracleDriver());
        conn = DriverManager.getConnection("jdbc:oracle:oci8:@",
                                           "scott", "tiger");

      stmt = conn.createStatement();
      rset = stmt.executeQuery ("SELECT * from ....");
    } catch (SQLException e) {
    finally {
      try {
        if (rset != null) rset.close();
        if (stmt != null) stmt.close();
      catch (SQLException ignored) {}

  public void valueBound(HttpSessionBindingEvent event) {
    // do nothing -- the session-scoped bean is already bound

  public synchronized void valueUnbound(HttpSessionBindingEvent event) {
    try {
      if (conn != null) conn.close();
    catch (SQLException ignored) {}

This is a sample code for JDBCQueryBean, a JavaBean that implements the HttpSessionBindingListener interface. The Connection object is bound into the Session and the listener takes care to close the connection as soon as the Session expires.

giovedì 8 gennaio 2009

Tomcat web xml reference

According to the Servlet 2.4 specification, every Web application should include a deployment descriptor (web.xml file). This file must be placed in the WEB-INF/ directory of the Web application.

There is also a web.xml file under the $CATALINA_HOME/conf directory. This file is similar to a Web application’s web.xml file. However, this particular web.xml file is used to specify the default properties for all Web applications that are running within this server instance.

Be very careful when making modifications to this file (such as any additions or changes) because they will affect all Web applications running on the same server instance. Note also that other application servers may or may not support a global default web.xml, as this is not a requirement for Servlet 2.4 standard compliance.

Web.xml can be formally validated against a schema:
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee web-app_2_4.xsd"


How to add a new Servlet mapping ?


How to add a parameter to your Context ?

<description>parameter description</description>

String username = getServletContext().getInitParameter("username");
How to flag a web application as clusterable ?


How to add an EJB reference in your web.xml ?

<description>Sample EJB</description>

How to add a reference to an environment variable ?

How to direct errors to error pages ?


How to add a filter to your web.xml ?
<filter-name>Compression Filter</filter-name>

<filter-name>Compression Filter</filter-name>

How to reference a tag lib ?


How to add a Context/Session listener ?


  • Here's an example how to use SessionListeners:
  • Here's an example how to use ContextListeners:

How to secure your application with JAAS ?

<realm-name>Example Form-Based Authentication Area</realm-name>

<display-name>Example Security Constraint</display-name>
<web-resource-name>Protected Area</web-resource-name>






How to add a MIME mapping to your web.xml ?


How to add a reference to a Datasource ?

<!-- JDBC DataSources (java:comp/env/jdbc) -->
<description>The default JDBC datasource</description>

How to configure the session timeout ?


How to add a welcome file list ?