Apache Tomcat Maven Plugin

groupId and Mojo name change

Since version 2.0-beta-1 tomcat mojos has been renamed to tomcat6 and tomcat7 with the same goals.

You must configure your pom to use this new groupId:

    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.tomcat.maven</groupId>
          <artifactId>tomcat6-maven-plugin</artifactId>
          <version>2.2</version>
        </plugin>
        <plugin>
          <groupId>org.apache.tomcat.maven</groupId>
          <artifactId>tomcat7-maven-plugin</artifactId>
          <version>2.2</version>
        </plugin>
      </plugins>
    </pluginManagement>

Or add the groupId in your settings.xml

  <pluginGroups>
    ....
    <pluginGroup>org.apache.tomcat.maven</pluginGroup>
    ....
  </pluginGroups>

Known limitations

Some goals are not yet available with the tomcat7 mojo. Those container goals are available with the tomcat6 mojo, you only need to update the manager url in your pom.

Use http://localhost:8080/manager/text rather than the default tomcat6 url.

Context Goals

Redeploying a WAR project

The goals required to redeploy a WAR project depend upon how it was deployed:

• To redeploy a WAR project deployed by tomcat:deploy you can type:

  mvn package tomcat6/7:redeploy

• To redeploy a WAR project deployed by tomcat:exploded you can type:

  mvn war:exploded tomcat6/7:redeploy

• To redeploy a WAR project deployed by tomcat:inplace you can type:

  mvn war:inplace tomcat6/7:redeploy

• To redeploy a context.xml file deployed by tomcat:deploy you can type:

  mvn tomcat6/7:redeploy

  Note: Depending on the docBase specified in the context.xml you may also need to call war:exploded or war:inplace as above.

Undeploying a WAR project

To undeploy a WAR from Tomcat you can type:

mvn tomcat6/7:undeploy

Starting a WAR project

To start a WAR in Tomcat you can type:

mvn tomcat6:start

Stopping a WAR project

To stop a WAR in Tomcat you can type:

mvn tomcat6:stop

Listing session statistics

To list the session statistics for a deployed WAR project you can type:

mvn tomcat6:sessions

Container Goals

Listing deployed applications

To list all the currently deployed applications in Tomcat you can type:

mvn tomcat6:list

Listing server information

To list information about the Tomcat version, OS, and JVM properties you can type:

mvn tomcat6:info

Listing JNDI resources

To list all the JNDI resources available within Tomcat you can type:

mvn tomcat6:resources

Alternatively, to list only JNDI resources of a specific type you can type:

mvn -Dmaven.tomcat.type=my.class.name tomcat6:resources

Listing security roles

To list the available security roles available within Tomcat you can type:

mvn tomcat6:roles

Build an Executable War/Jar

Starting with Version 2.0 of the plugin you can build an executable war/jar with an embedded Apache Tomcat7.

This is only supported with the tomcat7 plugin.

Note Your project must have a packaging value of pom or war.

Artifact to add to your war module:

<project>
  ...
  <packaging>war or pom</packaging>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.tomcat.maven</groupId>
        <artifactId>tomcat7-maven-plugin</artifactId>
        <version>2.2</version>
        <executions>
          <execution>
            <id>tomcat-run</id>
            <goals>
              <goal>exec-war-only</goal>
            </goals>
            <phase>package</phase>
            <configuration>
              <path>foo</path>
              <!-- optional, needed only if you want to use a preconfigured server.xml file -->
              <serverXml>src/main/tomcatconf/server.xml</serverXml>
              <!-- optional values which can be configurable -->
              <attachArtifactClassifier>default value is exec-war but you can customize</attachArtifactClassifier>
              <attachArtifactClassifierType>default value is jar</attachArtifactClassifierType>
            </configuration>
          </execution>
        </executions>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

Artifact to add to your pom module:

<project>
  ...
  <packaging>war</packaging>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.tomcat.maven</groupId>
        <artifactId>tomcat7-maven-plugin</artifactId>
        <version>2.2</version>
        <executions>
          <execution>
            <id>tomcat-run</id>
            <goals>
              <goal>exec-war-only</goal>
            </goals>
            <phase>package</phase>
            <configuration>
              <!-- optional only if you want to use a preconfigured server.xml file -->
              <!--
              <serverXml>src/main/tomcatconf/server.xml</serverXml>
              -->
              <warRunDependencies>
                <warRunDependency>
                  <dependency>
                    <groupId>a groupId</groupId>
                    <artifactId>and artifactId</artifactId>
                    <version>version</version>
                    <type>war</type>
                  </dependency>
                  <contextPath>/</contextPath>
                </warRunDependency>
              </warRunDependencies>
              <!-- naming is disabled by default so use true to enable it -->
              <enableNaming>true</enableNaming>
              <!-- extra dependencies to add jdbc driver, mail jars, etc. -->
              <extraDependencies>
                <extraDependency>
                  <groupId>org.apache.derby</groupId>
                  <artifactId>derby</artifactId>
                  <version>10.1.3.1</version>
                </extraDependency>
                <extraDependency>
                  <groupId>javax.mail</groupId>
                  <artifactId>mail</artifactId>
                  <version>1.4</version>
                </extraDependency>
              </extraDependencies>
            </configuration>
          </execution>
        </executions>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

Generated executable jar/war

With the above configuration you can execute the generated jar due to its embedded Tomcat container

java -jar yourjar

Help output

usage: java -jar [path to your exec war jar]
 -ajpPort <ajpPort>                     ajp port to use
 -clientAuth                            enable client authentication for
                                        https
 -D <arg>                               key=value
 -extractDirectory <extractDirectory>   path to extract war content,
                                        default value: .extract
 -h,--help                              help
 -httpPort <httpPort>                   http port to use
 -httpProtocol <httpProtocol>           http protocol to use: HTTP/1.1 or
                                        org.apache.coyote.http11.Http11Nio
                                        Protocol
 -httpsPort <httpsPort>                 https port to use
 -keyAlias <keyAlias>                   alias from keystore for ssl
 -loggerName <loggerName>               logger to use: slf4j to use slf4j
                                        bridge on top of jul
 -obfuscate <password>                  obfuscate the password and exit
 -resetExtract                          clean previous extract directory
 -serverXmlPath <serverXmlPath>         server.xml to use, optional
 -X,--debug                             debug

Run Mojo: run your Maven war project quickly!

When developing a war project, you usually build your war and deploy it to an installed Tomcat instance. This is time and resources consuming and also requires a local Tomcat instance.

The run mojo gives you the opportunity to avoid those efforts by simply running your war inside an embedded Tomcat instance in your Maven build.

NOTE If you have a multi module Maven project and use Maven3, you don't need to install all modules before using the run goal, just use tomcat6/7:run from the root module and the plugin will auto detect the build output directory from various modules and replace dependencies with those directories in the webapp classloader.

Running an embedded Tomcat

Configure your pom with the plugin version (for other mojo parameters see each mojo's documentation).

And use: mvn tomcat6/7:run

  <plugin>
    <groupId>org.apache.tomcat.maven</groupId>
    <artifactId>tomcat7-maven-plugin</artifactId>
    <!-- or if you want to use tomcat 6.x
    <artifactId>tomcat6-maven-plugin</artifactId>
    -->
    <version>2.2</version>
    <configuration>
      <!-- http port -->
      <port>9090</port>
      <!-- application path always starts with /-->
      <path>/</path>
      <!-- optional path to a context file -->
      <contextFile>${tomcatContextXml}</contextFile>
      <!-- optional system propoerties you want to add -->
      <systemProperties>
        <appserver.base>${project.build.directory}/appserver-base</appserver.base>
        <appserver.home>${project.build.directory}/appserver-home</appserver.home>
        <derby.system.home>${project.build.directory}/appserver-base/logs</derby.system.home>
        <java.io.tmpdir>${project.build.directory}</java.io.tmpdir>
      </systemProperties>
      <!-- if you want to use test dependencies rather than only runtime -->
      <useTestClasspath>false</useTestClasspath>
      <!-- optional if you want to add some extra directories into the classloader -->
      <additionalClasspathDirs>
        <additionalClasspathDir></additionalClasspathDir>
      </additionalClasspathDirs>
    </configuration>
    <!-- For any extra dependencies needed when running embedded Tomcat (not WAR dependencies) add them below -->
    <dependencies>
      <dependency>
        <groupId>org.apache.derby</groupId>
        <artifactId>derby</artifactId>
        <version>\${derbyVersion}</version>
      </dependency>
      <dependency>
        <groupId>javax.mail</groupId>
        <artifactId>mail</artifactId>
        <version>1.4</version>
      </dependency>
    </dependencies>
  </plugin>

Maven project structure

  pom.xml             (top level pom with packaging pom)
  my-api/pom.xml      (API project with packaging jar)
  my-api-impl/pom.xml (API implementation project with packaging jar)
  my-webapp/pom.xml   (webapp project with packaging war)

With the structure given above, from the top level directory use mvn tomcat6/7:run -pl :my-webapp -am.

Use it with selenium mojo

You can use this mojo to start your application in a Tomcat instance and run your selenium test against this instance.

The following configuration will start an embedded Tomcat in the pre-integration-test and stop it in the post-integration-test.

  <plugin>
    <groupId>org.apache.tomcat.maven</groupId>
    <artifactId>tomcat7-maven-plugin</artifactId>
    <!-- or if you want to use tomcat 6.x
    <artifactId>tomcat6-maven-plugin</artifactId>
    -->
    <version>2.2</version>
    <executions>
      <execution>
        <id>tomcat-run</id>
        <goals>
          <goal>run-war-only</goal>
        </goals>
        <phase>pre-integration-test</phase>
        <configuration>
          ....
          <fork>true</fork>
          ....
        </configuration>
      </execution>
      <execution>
        <id>tomcat-shutdown</id>
        <goals>
          <goal>shutdown</goal>
        </goals>
        <phase>post-integration-test</phase>
      </execution>
    </executions>
  </plugin>