Tomcat Plugin Manual

Preface

This document describes the functionality provided by the Tomcat plugin.

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

Overview

The Tomcat plugin is an XL Deploy 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 (that is, $TOMCAT_HOME/conf/context.xml).
• Deployment 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.
• Deployment of configuration files to a Tomcat Server.
• Deployment of libraries files to a Tomcat Server.

Requirements

• XL Deploy requirements

  • XL Deploy: version 4.5+
  • Tomcat versions: 5.5.x, 6.x, 7.x, 8.x (Unix and Windows)

• Infrastructural requirements

  • User credentials for accessing the host running the Tomcat Server.
  • Tomcat must run in the background (see Starting Tomcat).
    • On Unix, Tomcat should be installed as a daemon or the Tomcat startup script should start Tomcat in the background.
    • On Windows, you must install Tomcat as a service.

  Refer to the documentation for your version of Tomcat for information about running Tomcat in the background.

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 deployit-manifest.xml 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.

<?xml version="1.0" encoding="UTF-8"?>
<udm.DeploymentPackage version="1.0" application="SampleApp">
  <deployables>
    <jee.War name="SampleApp-1.0.war" file="SampleApp-1.0.war">
      <tags />
      <scanPlaceholders>true</scanPlaceholders>
      <checksum>b4759ef62eaf3a89db260f51ad0d1d749d22f7e4</checksum>
    </jee.War>
    <tomcat.DataSourceSpec name="testDatasource">
      <tags />
      <jndiName>jdbc/sampleDatasource</jndiName>
      <driverClassName>com.mysql.jdbc.Driver</driverClassName>
      <url>jdbc:mysql://localhost/test</url>
      <username>{{DATABASE_USERNAME}}</username>
      <password>{{DATABASE_PASSWORD}}</password>
      <connectionProperties />
    </tomcat.DataSourceSpec>
    <jee.QueueSpec name="sampleQueue">
      <tags />
      <jndiName>jms/testQueue</jndiName>
    </jee.QueueSpec>
    <jee.QueueConnectionFactorySpec name="sampleQCf">
      <tags />
      <jndiName>jms/sampleQCf</jndiName>
    </jee.QueueConnectionFactorySpec>
  </deployables>
</udm.DeploymentPackage>

Tomcat Topology

The Tomcat plugin allows for the modeling of a Tomcat installation into the XL Deploy infrastructure as a hierarchical set of containers. Tomcat Server, Tomcat Common Context and Tomcat Virtual Hosts containers can then be included into XL Deploy 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 XL Deploy 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. XL Deploy 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 (that is, $TOMCAT_HOME/conf/[enginename]/[hostname]). This container must be defined under a Tomcat Server container. Multiple 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

Deployed Actions Table

The following table describes the effect a deployed has on its container.

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. If you want to deploy the WAR file in the exploded mode, you need to package the WAR file using tomcat.ExplodedWar instead of jee.War.

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. For 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 XL Deploy's Plugin API type system. Refer to Customization Manual for an explanation of the type system.

Adding additional context attributes

Tomcat context's have several 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 side represents the property name in the deployed, while the right hand side represents the attribute name in the XML. When the right 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, and so on.

Adding new context elements

Tomcat contexts have several nested components or special features (Context Parameters, Lifecycle Listeners, and so on), 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="jee.ResourceSpec"/>
    <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="targetDirectory" default="${deployed.container.contextDirectory}" hidden="true"/> 
    <property name="targetFile" default="${deployed.context}.xml" hidden="true"/> 
    <property name="template" default="tc/context/context-element.ftl" hidden="true"/> 
</type>

Troubleshooting

Starting Tomcat

XL Deploy expects the Tomcat start command to return and leave Tomcat running. This means that the default Tomcat start script will cause XL Deploy to hang during deployment. You can specify start and stop commands on the Tomcat server.

For example, to start and stop Tomcat 7 when it is installed as a daemon on Unix, use service tomcat7 start or /etc/init.d/tomcat7 start. On Windows, use net start tomcat7.

Tip: If your start and stop scripts only return when Tomcat is actually started or stopped, set the wait times on the Tomcat server to 0.

Restarting Tomcat after deployment

If you are running Tomcat on Unix and you find that the Tomcat server does not restart after application deployment, you may need to use the nohup command with the sleep option. This ensures that the SSH connection is not closed before the restart is processed. For example:

nohup /usr/local/apache-tomcat-7.0.42/bin/catalina.sh start && sleep 2

Disabling management of context.xml

If you find that the Tomcat plugin deploys additional files that cause conflicts, you may need to disable its management of the context.xml file, as described in the deployed actions table. To disable management, locate the following line in the <XLDEPLOY_HOME>/conf/deployit-defaults.properties file:

#tomcat.manageContextXml=true

Change the line to:

tomcat.manageContextXml=false

Release notes

Version 4.5.1

• Improvements
• DEPL-7790 - Make start/stop steps in tomcat-plugin idempotent
• Bug
• DEPL-7962 - Fixed issue where undeploying a WAR would not remove the configuration XML from all containers in the environment
• DEPL-6448 - Fixed issue where Tomcat start/stop scripts would only work when Tomcat was installed on C: drive

Version 4.5.0

• Compatible with XL Deploy 4.5

Version 4.0.0

• Compatible with XL Deploy 4.0
• DEPL-5534: Added support for Tomcat 8

Version 3.8.0

• Updated to use plugin-api-3.8.0

Version 3.7.0

• Bug
  • [DEPLOYITPB-2988] - The Tomcat plugin contains an upgrader that is not needed

Version 3.6.0

• Bug
  • [DEPLOYITPB-2728] - Cannot create War Settings for petclinic on Windows using Tomcat Plugin
  • [DEPLOYITPB-2746] - Type "tomcat.TomcatServer" should be called "tomcat.Server"