Using the TomEE Maven Plugin

If you are looking for the fastest way to download, install, and run TomEE with or without webapps, then look no further! This blog post shows how to use the TomEE Maven Plugin to easily install and run TomEE and webapps with a single command.

Clean TomEE Install

The TomEE Maven Plugin will download, install, and run TomEE with a single Maven command:

$ mvn tomee:run

Just copy the pom.xml file below – (you can also get it from GitHub) – then run the command above and the TomEE Maven Plugin will download, install, and run a clean installation of TomEE. I say “clean” because the install does not include any Tomcat/TomEE default webapps. Type exit at the prompt when you want to stop the server.

Let’s take a quick look at the pom.xml file to see how it works.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.superbiz</groupId>
  <artifactId>tomee-install</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>TomEE :: Examples :: Install</name>
  <build>
    <directory>${project.basedir}</directory>
    <plugins>
        <plugin>
          <groupId>org.apache.tomee.maven</groupId>
          <artifactId>tomee-maven-plugin</artifactId>
          <version>8.0.1-SNAPSHOT</version>
          <configuration>
            <tomeeClassifier>plume</tomeeClassifier>
            <args>-Xmx512m -XX:PermSize=256m</args>
          </configuration>
        </plugin>
    </plugins>
  </build>
</project>

It’s pretty simple. The major thing to observe is the TomEE Maven Plugin (highlighted in green), which takes care of downloading, installing, and running TomEE.

You can copy and paste the pom.xml listing above or you can get it along with an example WAR by cloning the tomee-mvn-installation-example project on GitHub.

Default TomEE Install

You can add the default Tomcat/TomEE webapps by including the <removeDefaultWebapps>false</removeDefaultWebapps> to the TomEE plug-in configurations options as shown below:

<plugin>
  <groupId>org.apache.tomee.maven</groupId>
  <version>8.0.1-SNAPSHOT</version>
  <configuration>
    <tomeeClassifier>plume</tomeeClassifier>
    <args>-Xmx512m -XX:PermSize=256m</args>
    <removeDefaultWebapps>false</removeDefaultWebapps>
  </configuration>
</plugin>

WAR First TomEE Install

A WAR First TomEE install uses the TomEE Maven Plugin declared in a webapp. In other words, you start with a webapp’s pom.xml which downloads, installs, and runs TomEE with the webapp’s WAR file deployed. This is a great way to create complete TomEE applications without having to start with a TomEE server.

As an example, shut down the TomEE instance if you have it running by typing “exit” at the command prompt. If you haven’t cloned the example project, do so now. Next move the prompt into the hello-servlet directory under the cloned project.

$ get clone https://github.com/tomitribe/tomee-mvn-installation-example.git
...
$ cd tomee-mvn-installation-example/hello-servlet

Now, execute mvn clean install tomee:run.

$ mvn clean install tomee:run

With TomEE running use your web browser or cUrl to check if the webapp was deployed. It should return Hello World.

$ curl http://localhost:8080/hello-servlet/

Hello World

TomEE Maven Plugin: Configuration Parameters

In addition to the regular Maven parameters the TomEE plugin offers eleven optional configuration parameters. I’m going to talk about four of them but all eleven are documented on “TomEE Maven Plugin” pages (here and here) at the Apache TomEE web site. Each command includes over two dozen parameters which are either set by default or not required.

tomee:build

This command will download and install TomEE but will not run it.

tomee:run

This command will download, install and run TomEE in the foreground. You could also call this after tomee:build to run an already installed TomEE. You exit TomEE by typing “quit” or “exit”.

tomee:start

This command will download, install, and run TomEE in a background thread freeing up the command window.

tomee:stop

This command will quit or exit an TomEE instance that was run with tomee:start.

Conclusion

The TomEE Maven Plugin is really powerful as it makes it easier to do a number of operations on an existing TomEE instance in addition to downloading, installing, and running a fresh instance. Using the Maven plugin, TomEE can be installed and run with or without a fully deployed webapp. More documentation on the configuration options can be found here.