Sergey Nivens - Fotolia

Tutorial

How to deploy an embedded Tomcat server in an executable JAR with Maven example

There's nothing magical about packaging Java web apps in an executable JAR file. This embedded Tomcat tutorial shows you how to use the Apache Maven plugin to create and run an executable JAR that has Tomcat embedded within it.

Cameron McKenzie
By
Published: 24 May 2018

Historically, we packaged production-ready Java web apps as WAR files. A servlet engine, like an IBM WebSphere or Apache Tomcat server, would host multiple applications at once. But for a variety reasons -- the widespread adoption microservices and desire to perform highly isolated unit tests, for instance -- the one-to-many relationship between the Java web app and the servlet container has consolidated into a one-to-one.

The days needing to host a WAR file on a full-scale application server have given way to a new approach. Now, we embed Tomcat into an executable JAR file and run Java web apps as though they were a stand-alone Java application. Cloud-native computing and the microservices model have flipped the traditional Java Platform, Enterprise Edition deployment model on its head, with the Java embedded Tomcat server becoming the new normal. If you are doing modern enterprise Java development, you need to know how to created an embedded Tomcat server with Maven that can be deployed to clients as an executable JAR or WAR file.

Embedded Tomcat, Maven and the JDK

Fortunately, it's not that difficult to create an executable JAR file that hosts Java web apps on an embedded Tomcat server. In this tutorial, we'll demonstrate how easy it is to use Maven and embed Tomcat and Java web apps in an executable JAR file.

This embedded Tomcat tutorial has only two prerequisites:

  1. You must have the Java Development Kit (JDK) installed and configured. Version 8 the JDK or newer is preferred.
  2. You must have Maven 3.5 or newer installed in order to run the embedded Tomcat Maven command

That's it. You don't even need to download the Apache Tomcat server because Maven's Tomcat plug-in will acquire the Tomcat binaries for you.

How to created an embedded Tomcat server with Maven

This embeded Tomcat tutorial shows you how to create an executable JAR file using Apache Maven.

Create a new Java web app

Cloud-native computing and Java embedded Tomcat servers have flipped the traditional Java EE deployment model on its head.

This embedded Tomcat tutorial starts development completely from scratch and documents every step in the process -- from Java web app development to the deployment of the executable JAR file in which we embed Tomcat.

On my local workstation, I have created a folder named executable-jar-tutorial in which I will use Maven to help build and test the application. The Maven command to create the Java web project is:

<!-- This all goes on one line -->
mvn archetype-generate -DarchetypeArtifactId=maven-archetype-webapp

This Maven command runs in an interactive mode, which means you will be prompted for the following five pieces of input:

Embedded Tomcat Project Maven Command Parameters

plug-in version to use

Choose the latest, which will likely be 1.6.

groupId

com.mcnz.maven

artifactId

java-web-app

Version

1.0-embedded

Package

com.mcnz.maven

Here is what the output from the Bash shell window shows when we run the  Maven command:

/c/ executable jar example/
$ mvn archetype:generate -DarchetypeArtifactId=maven-archetype-webapp
Define value for property 'groupId': com.mcnz.maven
Define value for property 'artifactId': java-web-app
Define value for property 'version' 1.0-SNAPSHOT: : 1.0-embedded
Define value for property 'package' com.mcnz.maven: : com.mcnz.maven
Confirm properties configuration: Y: : Y
[INFO] ------------------------------------
[INFO] BUILD SUCCESS : EMBED TOMCAT EXAMPLE
[INFO] ------------------------------------

When the Maven build completes, we will edit a sample index.jsp file, which you'll find in the following directory:

C:\ executable jar tutorial \java-web-app\src\main\webapp

Develop Java web apps

Edit the index.jsp file so, when the Java web app runs, we can uniquely identify it as our own. I have updated the provided index.jsp file to read as follows:

<html>
  <body>
    <h2>Hello Java web app World!</h2>
    <p>How to create an executable jar file tutorial.</p>
    <p>An embed Tomcat example.</p>
  </body>
</html>

Save the index.jsp file, and close the editor. Doing so concludes the software development portion of this executable JAR tutorial.

The web app is only a single JSP (JavaServer Pages) file, so this is not a complicated application, nor is there any need for it to be. The goal here is not to master the Servlet and JSP API, but instead to create an executable JAR file with a Java web app and Tomcat embedded within. There is no need to complicate things by annotating Servlets or building a RESTful component. This is a proof of concept, so a simple Hello World file is sufficient.

Create and embedded Tomcat JAR with Maven

The mvn archetype command issued in the step creates a pom.xml file that Maven uses to compile, build and deploy the application. Initially, the POM (Project Object Model) file is relatively slim, with the only necessary parts being the JUnit dependency and project preamble.

<?xml version="1.0" encoding="UTF-8"?>

<project>
   <!-- Embed Tomcat example preamble -->
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.mcnz.maven</groupId>
   <artifactId>java-web-app</artifactId>
   <version>1.0-embedded</version>
   <packaging>war</packaging>

   <!-- Embed Tomcat example JUnit dependency -->
   <dependencies>

      <dependency>
         <groupId>junit</groupId>
         <artifactId>junit</artifactId>
         <version>4.11</version>
         <scope>test</scope>
      </dependency>
   </dependencies>

       <!--End of the embed Tomcat example -->
</project>

How to use the embedded Tomcat Maven plug-in

To create an executable JAR file, the pom.xml file needs to be updated with a reference to the embedded Tomcat Maven plug-in. We'll do this by adding the following build descriptor immediately after the dependencies section:


 <build>
   <!-- plugin to embed Tomcat in a Java JAR file -->
    <finalName>javawebapp</finalName>
    <pluginManagement>
      <plugins>
          <plugin>
             <groupId>org.apache.tomcat.maven</groupId>
             <artifactId>tomcat7-maven-plugin</artifactId>
             <version>2.1</version>

             <configuration>
               <!-- context root for Java web apps -->
               <path>/tutorial</path>
               <!-- name of Tomcat executable jar file -->
               <finalName>executable.jar</finalName>
             </configuration>

          </plugin>
       </plugins>
    </pluginManagement>
 </build>

With the pom.xml file edited and updated with a reference to the Tomcat plug-in for Maven, the final step is to build the project and call on the appropriate goal -- tomcat7:exec-war-only -- to create the executable JAR file. When this embedded Tomcat Maven goal is invoked, the Tomcat plug-in for Maven will automatically place the embedded Tomcat server inside the executable JAR.

/c/ executable jar example/javawebapp
$ mvn clean install tomcat7:exec-war-only
[INFO] --- embed tomcat maven plugin running
[INFO] -------------------------------------------
[INFO] BUILD SUCCESS : EXECUTABLE JAR FILE CREATED
[INFO] -------------------------------------------
[INFO] Total time: 3.970 s
[INFO] -------------------------------------------

If the command to create an executable JAR file with an embedded Tomcat server runs successfully, a new file named executable.jar should appear in the target subfolder of the Maven project. Normally, a simple Java web app like this wouldn't be more than 10 KB inside, but since there is an embedded Tomcat server contained within, the file size will be over 8,500 KB.

JAR file
The JAR file appears after successfully running the command to embed Tomcat in an executable JAR file.

How to run an executable JAR file

To run the executable JAR file, issue the following command:

java -jar executable.jar

This command will trigger the embedded Tomcat server to start, and the hosted Java web application will become available at the following address:

http://localhost:8080/tutorial/index.jsp

tomcat
When you embed Tomcat in an executable WAR, Java web apps will be accessible through the browser.

And that's it. Those are all of the steps required in order to create an executable JAR file that is capable of hosting a single Java web app in a Java embedded Tomcat server.

Revisit the Maven POM

By the way, there is value in being able to see the pom.xml file in its entirety, so here is the full file from the completed tutorial:

<?xml version="1.0" encoding="UTF-8"?>
<project>

 
  <!-- create an executable jar file example -->
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mcnz.maven</groupId>
  <artifactId>javawebapp</artifactId>
  <version>1.0-embedded</version>
  <packaging>war</packaging>


  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.11</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  

   <!-- Maven embedded Tomcat server example -->
   <build>
      <finalName>javawebapp</finalName>
      <pluginManagement>
           <plugins>
            <plugin>
               <groupId>org.apache.tomcat.maven</groupId>
               <artifactId>tomcat7-maven-plugin</artifactId>
               <version>2.1</version>
               <configuration>
                 <!-- context root for Java web apps -->
                 <path>/tutorial</path>
                 <!-- name of executable jar file -->
                 <finalName>executable.jar</finalName>
               </configuration>
            </plugin>
         </plugins>
      </pluginManagement>
   </build>
   <!-- end of embedded Tomcat server tutorial -->

</project>

Dig Deeper on Java cloud platforms