What are the Alternatives?

Opensource and commercial here are a few to consider:

  • JBoss
  • Caucho Resin
  • Weblogic
  • Websphere
  • Sun Java System Application Server
  • JRun

Initial setup

The following applies to Tomcat 5.5.x. At the time of writing I am using 5.5.12

Pretty much Tomcat can be unpacked and run right out of the box without any troubles. Of course there are a large number of configuration and tuning options at your disposal.

The first thing I usually do is to add a couple of users so you can remotely deploy to and manage the server. Note: Opening this up does increase your exposure with a public facing server, use with caution.

Typically, at least for my local development server I add the following to my tomcat home/conf/tomcat-users.xml This will allow you to setup Maven to deploy Tomcat

  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="admin" password="admin" roles="manager,admin"/>

Configuring Cayenne and Tomcat to use JNDI Datasources

  • Copy your JDBC driver into tomcat home/common/lib. It may also need to reside under your webapp, the maven build will do this for you anyway. Tomcat will require a restart to pick this change up.
  • Change the cayenne.xml file either using the Cayenne editor or manually to set your DataNodes to use JNDIDataSourceFactory. Set the JNDI Location to be: jdbc/dataSource (or whatever it is called)
    • From here you decide if you want ot make a change pre web app or globally

Per web app

For each web app:

  • Change the web application file: \src\main\webapp\META-INF\context.xml and add a resource description such as...

    Eg for SQL Server:

        <Resource name="jdbc/dataSource" auth="Container"
            type="javax.sql.DataSource" username="web_user" password="secret"
            driverClassName="net.sourceforge.jtds.jdbc.Driver"
            url="jdbc:jtds:sqlserver://DB_SERVER;databaseName=SOME_DB"
            maxActive="8" maxIdle="4"/>
  • Change the web application file: \src\main\webapp\WEB-INF\web.xml and add a resource point such as...

    (this will have to be put in the right place in the file as per dtd, it is nearly the last element)

        <resource-ref>
        <res-ref-name>jdbc/dataSource</res-ref-name>
        <res-type>javax.sql.DataSource</res-type>
        <res-auth>Container</res-auth>
    </resource-ref>

Globally

  • Change the $tomcat.home/conf/server.xml and add a GlobalNamingResources entry e.g. for SQL Server...
         <GlobalNamingResources>
        <Resource
          name="jdbc/GlobalDataSource"
          type="javax.sql.DataSource"
          password="SECRET"
          driverClassName="net.sourceforge.jtds.jdbc.Driver"
          maxIdle="2"
          maxWait="5000"
          username="DB_USER"
          url="jdbc:jtds:sqlserver://DB_SERVER;databaseName=SOME_DB"
          maxActive="4"/>
      </GlobalNamingResources>
  • Change the web application file: \src\main\webapp\META-INF\context.xml and add a resource description such as...
        <ResourceLink name="jdbc/dataSource"
            global="jdbc/GlobalDataSource"
            type="javax.sql.DataSource"/>
  • Change the web application file: \src\main\webapp\WEB-INF\web.xml and add a resource point such as... (this will have to be put in the right place in the file as per dtd, it is nearly the last element)
        <resource-env-ref>
        <resource-env-ref-name>jdbc/dataSource</resource-env-ref-name>
        <resource-env-ref-type>javax.sql.DataSource</resource-env-ref-type>
    </resource-env-ref>

    Our DB layer - Cayenne - can now use the JNDI datasource:

       jdbc/dataSource

    See the Cayenne setup guide for more information from the Cayenne side.

    Another handy reference is http://wiki.apache.org/jakarta-commons/DBCP

Use in a shared environment

We've deployed Tomcat into an environment that uses JDK1.3. In order to reduce the risk of having a JDK5 installation affect the original JDK1.3 installation you can copy a JDK5 from from another computer into another folder, say under your Tomcat installation. Then in Tomcat tell it where it should find its JDK...a small point that is just worth mentioning.

Installing as a Windows service

This is well documented here: http://tomcat.apache.org/tomcat-5.5-doc/windows-service-howto.html

Here are a couple of extra things I've found to help out

  • Set the correct JAVA_HOME before you run the script in order for the service to run.
  • Alter any -X Java options. This will require a change to the original Tomcat scripts but can be essential for tuning the performance of your Tomcat installation. It is also quite handy to increase the MAX_PERM_SIZE

    Here is what I did:

    Edit the service.bat and add a new environment variable (%JAVA_OPTS%) to the Install servce line

      "%EXECUTABLE%" //IS//%SERVICE_NAME% --StartClass org.apache.catalina.startup.Bootstrap
     --StopClass org.apache.catalina.startup.Bootstrap --StartParams start --StopParams stop --JvmOptions %JAVA_OPTS%

Install the service with the JDK and the JAVA_OPTS variable set

    set JDK_HOME=E:\apache-tomcat-5.5.12\jdk1.5.0_05
    set JAVA_OPTS=-XX:MaxPermSize=256m;-Xms512m;-Xmx512m
    call service.bat install

Enabling Debugging

Interactive debugging with JPDA and a decent editor can really get you unstuck from a nasty situation from time to time. It is not something that you would always use , most developers still rely on logging to a file, but if you want to debug into Tomcat from your IDE here is how:

Start Tomcat up with either shared memory or socket debug mode:

Shared Memory:

    set JAVA_OPTS= -XX:MaxPermSize=128m -Xms512m -Xmx512m -Dorg.apache.tapestry.disable-caching=true
    catalina jpda start

Socket: 

    set JPDA_ADDRESS=5005
    set JPDA_TRANSPORT=dt_socket
    set JAVA_OPTS= -XX:MaxPermSize=128m -Xms512m -Xmx512m -Dorg.apache.tapestry.disable-caching=true
    catalina jpda start

Ensure that you have the latest code deployed to your Tomcat server.

Start you editors debug mode to match the above.

I am an Intellij Idea (5.x) fan so here's how you do it there for shared memory mode:

  • Run - Edit Configurations
  • Remote Tab
  • Add a new one (the '+' button)
  • Under settings:
    • Transport: Shared memory
    • Debugger mode: Attach
    • Shared memory address: jdbconn