From ControlTier

(Redirected from Tomcat Library)
Jump to: navigation, search

Requires Version: 3.4.4

Manage an Apache-Tomcat server, with multiple contexts and war deployments. Organize multiple Apache-Tomcat servers into a Site to manage as a group.

Before delving into ControlTier usage, be sure to read How to use ControlTier.

Also see the Using Libraries document for some getting-started instructions.



The Tomcat Library provides Types to help you:

These Types are designed with the following object composition model:

Tomcat Library Composition Model

A single TomcatServer object represents an instance of the running Apache-Tomcat server. A TomcatServer object depends on a TomcatZip package object to hold the Apache-Tomcat server software for automatic deployment. TomcatServer can also use a single war object to deploy a web application to the server.

Multiple web application contexts can be managed using the TomcatContext type. Each object of this type represents a single web application. It depends on a war, and all of the TomcatContext objects should be children of a TomcatSite object. The TomcatSite also has a single TomcatServer object child dependency.

TomcatSite is a Site subtype, which dispatches lifecycle commands (Start, Stop, etc.) to all of the contexts on the server.

You can use the Site type to manage a set of multiple TomcatSites, or managing a single TomcatServer on multiple Nodes.


Works with Tomcat 4.1, 5.x, and 6.x. The particular release should be specified in the TomcatZip object's "release" property.


Development Process

The following sections will guide you in developing your Tomcat management model by use of the Types defined in this library.

Use one or more project.xml files to manage the model definitions, and use a ProjectBuilder object to load and operate on the model.


The Tomcat Library provides several Types that can be used for managing a Apache-Tomcat server and its related web-applications and configurations in various ways. The parts of this section will guide you to the appropriate Types to use for each particular purpose.

These sections are ordered in a way that should let you start simply and move on to more advanced usages. If you have already created some management components you will probably skip to the section you are interested in.

Manage an Apache-Tomcat server instance

Define a TomcatServer to manage an Apache-Tomcat server. The TomcatServer type manages a single Apache-Tomcat server installation.

The Apache-Tomcat server can be managed in two modes:

  1. Single web-application mode
  2. Multiple web-application mode

Deploy WAR packages to an Apache-Tomcat server

After defining and uploading a war object (see below), add the war as a child-dependency of the TomcatServer object.

Manage multiple web application contexts

Use the TomcatContext type to define multiple web application contexts. Each TomcatContext should have the same deployment-basedir property as the TomcatServer, and should have a single war child dependency.

Use the TomcatSite Type to manage multiple contexts for a single server. The TomcatSite Type is a Site subtype, and it dispatches commands to all of the TomcatContext/TomcatServers attached to it. It serves as the control point of the TomcatServer when doing multi-application management.

Upload Packages

Upload the TomcatZip

First you should define a TomcatZip Object, and upload the package definition. The TomcatZip package object holds the Apache-Tomcat server software in a zip file, and is used by TomcatServer.

Upload a war

Next you should define a war for use by TomcatServer, or TomcatContext. The war package object can be deployed to either TomcatServer in single-application mode, or to a TomcatContext in multi-application mode.

If you want to build a war package using a Builder, continue to the next section.

Build war packages to deploy to the server

Any Builder can be used to produce a war package object. See the Use Builder Document for the generic instructions for doing software Builds using the Builder type.

Specifically if your build process produces a war file, you should configure your Builder with the following Import Attributes:

However, when using the multiple-context method of configuring your Apache-Tomcat server, you should instead use this installroot. See the TomcatContext usage for more info:

More information about Builder Settings are here: Builder Settings and Attributes.

Build software with Ant that depends on Apache-Tomcat

Use a TomcatAntBuilder to use Ant to build a war. This will allow your Ant-based build script to use the Tomcat dependency to produce a war.

Manage multiple Apache-Tomcat servers

Define a TomcatSite to manage multiple Apache-Tomcat servers as a group. This Site subtype dispatches management commands to its children. You will configure the TomcatSite to have each TomcatContext and the TomcatServer as child dependencies.

Generate Configuration

Configuration of a TomcatServer is handled by the Docs-Generate command, which uses the Setting resources attached to the TomcatServer to expand templates for the specific Apache-Tomcat software release that is being used. Refer to the Settings for specific configuration values.

Additional configuration of TomcatServer can be done in two ways:

  1. Define Document Transforms for the TomcatServer object: see Generating Configuration Files
  2. Define Settings of type TomcatProperty and TomcatPropertyFile

Each TomcatContext object also knows how to generate a "context.xml" file for itself based on the war file that is assigned to it.

Integrate Databases

Database Datasource information can be generated for the web applications, by using the GenerateDefaultTomcatContext Setting type with a value of "true", and attaching an object of type Rdb to the TomcatServer. (6.x release only).


Deployment is done by the standard Deploy command.

To deploy a TomcatServer in single-application mode:

execute the Deploy command for the TomcatServer:

ctl -p PROJECT -t TomcatServer -r myserver -c Deploy

To deploy a TomcatSite in multiple-applicatin mode:

execute the Deploy command for the TomcatSite:

ctl -p PROJECT -t TomcatSite -r myserver -c Deploy

To deploy the entire Site for multiple servers:

execute the Deploy command for the Site:

ctl -p PROJECT -t Site -r mysite -c Deploy


The Types below from the Tomcat Library (and some from the Core Library) are designed to compose in the fashion described in the Overview. When using these types, it is useful to reference the Usage section.


Description: Apache Tomcat server deployment.

Sample Definition

This sample file shows a single-application mode definition.


basedir: This is the path that will be where the Apache Tomcat zip will be installed, and must correspond to the TomcatZip "package-base" property. This is the "CATALINA_BASE" path.


installroot: This is the "CATALINA_HOME" path. It is often set to the same value as the basedir, but may be different.


See the TomcatServer Reference for the complete list of Settings available for TomcatServer.



Description: Zip archive of Apache Tomcat

Since the TomcatServer implementation supports multiple releases, it is important to be precise about which Tomcat release version is in use. The TomcatZip package type represents the zip package containing the Apache Tomcat software, and we must define a package for the appropriate Apache Tomcat release that we want to use.

Supported Releases: 4.1, 5.x, 6.x. The "release" property must be one of these values, and must correspond to the actual version number, e.g. version "4.1.39" is release "4.1", and version "5.5.26" is release "5.x", etc.

When creating your definition, make note of the specific version (e.g. "4.1.39"), and the corresponding release (e.g. "4.1").

Define the project.xml for the TomcatZip package. It is the convention to name the project file exactly as the package file, with an added ".xml" extension. For the "" file, this project file would be named "".

Sample Definition

Sample definitions of the three major release packages are available in this file:

Note: The "base" property must match the base name of the "installroot" property. I.e. if the package base is "apache-tomcat-4.1", then the installroot should be something like: "/path/to/apache-tomcat-4.1". By convention, the installroot is set to the catalinaHome attribute, which is the basedir property of a TomcatServer object. Just note that this basedir must be named according to the base property of the TomcatZip.


Description: Tomcat web application service (extended to support a custom context and an "external" property file).

A TomcatContext object describes an Apache Tomcat "Context Container", that is, a web application (deployed as a war archive) and its associated "context.xml" file.

Support for deploying multiple web applications to a single TomcatServer is implemented by the TomcatContext and TomcatSite modules.

Each TomcatContext object supports deployment of a single web application, but sets of them can be combined and associated with a single TomcatServer instance via a TomcatSite object; thus a set of one TomcatSite, a TomcatServer and one or more TomcatContext objects (all deployed to the same Node(s)) models multi-application deployment.

Here's how to configure and deploy an application to a single context in this manner:

  1. Define a TomcatServer object (shown above), or choose an existing one to work with.
  2. Define a TomcatContext object and a TomcatContextFile setting.
  3. Define a war deployment to the TomcatContext.

Sample Definition

This sample file shows how to use TomcatContext in a multiple-application mode scenario:

The application level objects (TomcatServer, TomcatContext, TomcatSite) are deployed on one node named "". The management level objects (Site, Updater) are deployed on a central ControlTier management node "".


basedir: Set the "Basedir" of the TomcatContext to be the same as that of the TomcatServer, i.e. the CATALINA_HOME path ending with a directory with the same name as the TomcatZip's package-base. (See the TomcatServer - Properties section above.)

Since the TomcatServer exports its deployment-basedir property as the catalinaHome attribute, you can set the basedir for the TomcatContext to "${resource.attribute.catalinaHome}" to correspond exactly to the value set for the TomcatServer.

startup-rank: The "startup rank" Property of the TomcatContext must be greater than that of its associated TomcatServer to ensure deployment proceeds in the correct order.


See the TomcatContext Reference for the list of all Setting types available.

Notes about Settings:


   <Host name="localhost"  appBase="webapps"
            unpackWARs="true" autoDeploy="true"
            xmlValidation="false" xmlNamespaceAware="false">
WARNING: A docBase /home/anthony/ctier/demo/elements/helloworld/apache-tomcat-6.0.14/webapps/myapp inside the host appBase has been specified, and will be ignored


Description: Centralized management for a set of Tomcat based application server instances and contexts.

Define a TomcatSite object that ties the TomcatServer and TomcatContext objects into a single manageable component, ensuring all objects are deployed to the same node (or set of nodes). Note that TomcatSite has a dispatchExecutionStrategy strategy of "localdispatch" limiting it to operating on co-deployed resources. If you want to manage Apache-Tomcat software deployed on multiple Nodes as a single unit, use the Site type.

Sample Definition

This sample shows a simple TomcatSite child dependencies of a single TomcatServer and a TomcatContext.


The TomcatSite, TomcatServer and TomcatContexts should all be assigned to the specific Node(s) that they will be running on.

To manage more than one TomcatServer on different Nodes, use the Site base type, which may be deployed on a central management server.


Description: Ant builder with specialized defaults for Tomcat applications

This AntBuilder subtype provides some customization to facilitate building "war" packages using Ant that depend on the Apache-Tomcat software.

Sample Definition

This sample TomcatAntBuilder definition shows a basic Builder definition, using a TomcatZip and AntZip dependencies to provide the Ant building ability and Apache-Tomcat dependency to the build.


Description: An interface to a set of related application services.

You can define a Site object, and add the TomcatSite objects as child dependencies. You can then use management commands on the Site to control them all.

Sample Definition

This is a simple Site sample definition, aggregating two Service resources for management.


Description: A war package

If your war deployment is not produced by the Builder, you should define it via another project.xml file.

Sample Definition

This is a basic war package object definition, for a war named "myapp-1.0.war".

Related Libraries

Personal tools