Preface

This document describes the functionality provided by the Tomcat plugin.

See the Deployit Reference Manual for background information on Deployit and deployment concepts.

Overview

The Tomcat plugin is a Deployit plugin that adds capability for managing deployments and resources to a Tomcat Server. Standard support includes deploying/undeploying web applications, datasources, mail sessions, resource links, ActiveMQ and WebsphereMQFeatures resources. The plugin can easily be extended to support more deployment options or management of new artifacts/resources on Tomcat.

Features

• Deployment of web applications (WAR) to a Tomcat virtual host.
• Deployment of resources to an application context on a Tomcat virtual host.
• Deployment of resources to the common Tomcat context ie. $TOMCAT_HOME/conf/context.xml.
• Deployement of resource links.
• Supported JEE Resources
  • Datasource
  • JMS Queue
  • JMS Queue Connection Factory
  • JMS Topic
  • JMS Topic Connection Factory
  • Mail Session
• Supported Messaging Middleware
  • Active MQ
  • Websphere MQ
• Support for Tomcat Database Connection Pool (DBCP) Configurations
• Stopping and starting a Tomcat Server via control tasks.

Requirements

• Deployit requirements

  • Deployit: version 3.6+
  • Tomcat versions: 5.5.x, 6.x, 7.x (Unix and Windows)

• Infrastructural requirements

  • User credentials for accessing the Host running the Tomcat Server.

Usage in Deployment Packages

The plugin works with the standard deployment package of DAR format. Please see the Packaging Manual for more details about the DAR format and the ways to compose one.

The following is a sample MANIFEST.MF file that can be used to create a Tomcat specific deployment package. It contain declarations for a war, a datasource and a couple of JMS resources.

Manifest-Version: 1.0
Deployit-Package-Format-Version: 1.3
CI-Application: SampleApp
CI-Version: 1.0

Name: SampleApp-1.0.war
CI-Name: SampleApp
CI-Type: jee.War

Name: testDatasource
CI-Type: tomcat.DataSourceSpec
CI-jndiName: jdbc/sampleDatasource
CI-url: jdbc:mysql://localhost/test
CI-driverClassName: com.mysql.jdbc.Driver
CI-username: {{DATABASE_USERNAME}}
CI-password: {{DATABASE_PASSWORD}}

Name: sampleQueue
CI-Type: jee.QueueSpec
CI-jndiNames: jms/testQueue

Name: sampleQCf
CI-Type: jee.QueueConnectionFactorySpec
CI-jndiNames: jms/sampleQCf

Tomcat Topology

The Tomcat plugin allows for the modelling of a Tomcat installation into the Deployit infrastructure as a hierarchical set of containers. Tomcat Server, Tomcat Common Context and Tomcat Virtual Hosts containers can then be included into Deployit environment definitions, to which deployables can be deployed to.

Tomcat Server

Models a Tomcat installation running on a host. This container must be defined under any Host in the Deployit infrastructure. The container supports OS specific stop and start commands used to control the stopping and starting of the Tomcat Server. In addition, stop and start wait times can be specified. Deployit will wait for the specified amount of time to elapse after the execution of a stop/start command.

Tomcat Common Context

Models the context.xml file present in the $TOMCAT_HOME/conf directory. This container must be defined under a Tomcat Server container. Only a single instance should be defined. Any Tomcat Resource can be deployed to this container.

Tomcat Virtual Host

Models a Tomcat virtual host definition, ie. $TOMCAT_HOME/conf/[enginename]/[hostname]. This container must be defined under a Tomcat Server container. Mutliple instances can be defined. Web Applications and Tomcat Resource can be deployed to this container.

Using the deployables and deployeds

The following table describes which deployable/container combinations are possible.

Deployable vs. Container table

The following table describes the effect a deployed has on it's container

Deployed Actions Table

Deploying Web Applications

Web Applications can be deployed to a Tomcat Virtual Host. The context root must be specified. The context root is used to create the corresponding application specific context xml in the virtual host.

Deploying Resources

Tomcat Resource can be deployed to a Tomcat Virtual Host or Tomcat Common Context. Every resource has an optional context property. This property is always set to context when the resource is deployed to Tomcat Common Context. When the resource is deployed to a Tomcat Virtual Host, the user can specify the name of the context to which the resource must be defined. When left blank, the plugin can default the value to that of the war in the current deployment. There must only be a single war in the current deployment for the defaulting to work. Example : deploying a war with context root set to sample, and a datasource to a virtual host will automatically result in the context property of the datasource been set to sample.

Extension points

The Tomcat plugin is designed to be extended through Deployit's Plugin API type system. Refer to Customization Manual for an explanation of the type system.

Adding additional context attributes

Tomcat context's have serveral attributes that can be set for a war. By default, the Tomcat Plugin only sets the unpackWAR and docBase attributes. When additional attributes are required, performing a type modification on the corresponding tomcat.WarModule can be done. For example, adding support for the antiResourceLocking attribute in synthetic.xml:

<type-modification type="tomcat.WarModule">
    <property name="antiResourceLocking" default="true" hidden="true"/>
    <property name="contextElementPropertyMapping" kind="map_string_string" hidden="true"
              default="unpackWAR:, docBase:, antiResourceLocking:"
</type-modification>

An additional hidden property antiResourceLocking with a default value of "true" is added to the deployed. The property is added to the contextElementPropertyMapping property's default value. This property is used to translate properties on the deployed to their xml equivalent in the Tomcat context. The left hand represents the property name in the deployed, while the right hand side represents the attribute name in the xml. When the right hand side is blank, the property name and xml equivalent are the same.

The same technique can be used to add attributes to other Tomcat resources like datasource, queues, etc.

Adding new context elements

Tomcat context's have several nested components or special features (Context Parameters, Lifecycle Listeners, etc.), that can be defined in the xml.

It is possible to model these features in the Tomcat Plugin and perform subsequence deployments of these resources. For example, adding support for the Context Parameter feature.

<Context>
  ...
  <Parameter name="companyName" value="My Company, Incorporated"
         override="false"/>
  ...
</Context>

Add to synthetic.xml:

<type type="tomcat.ContextParameter" extends="tomcat.ContextElement"
            deployable-type="tomcat.ContextParameterSpec">
    <generate-deployable type="tomcat.ContextParameterSpec" extends="tomcat.ContextElement"/>
    <property name="paramName" description="The name of the context parameter"/>
    <property name="value"/>
    <property name="override" kind="boolean" required="false" default="false"/>

    <!--inherited hidden -->
    <property name="elementTag" default="Parameter" hidden="true"/>
    <property name="elementName" default="paramName" hidden="true"/>
    <property name="elementPropertyMapping" kind="map_string_string" hidden="true"
              default="paramName:name, value:, override:"/>
</type>