Sergey Nivens - Fotolia

Get started Bring yourself up to speed with our introductory content.

How to embed Tomcat and Java web apps in an executable JAR

There's nothing magical about packaging Java web apps in an executable JAR file. This tutorials shows you how to embed Tomcat and run your Java web apps from the command line.

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 of reasons -- the widespread adoption of 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 of 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.

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.

Embedded Tomcat example prerequsites

This tutorial has only two prerequisites:

  1. You must have the Java Development Kit (JDK) installed and configured. Version 8 of the JDK or newer is preferred.
  2. You must have Maven 3.5 or newer installed.

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.

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

Create a new Java web app

This 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 five pieces of input that should be provided as follows:

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

Let us show you step by step how to embed Tomcat and Java web apps in an executable file.

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.

Use Maven to embed Tomcat

The mvn archetype command issued in the first 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>

The Tomcat plug-in for Maven

To create an executable JAR file, the pom.xml file needs to be updated with a reference to the 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 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 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 on an 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>

 

   <!-- plugin to create an embedded Tomcat server -->
   <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 embed Tomcat example -->

</project>

This was last published in May 2018

Dig Deeper on Java cloud platforms

Join the conversation

4 comments

Send me notifications when other members comment.

Please create a username to comment.

Do you have addititional questions on embedding Tomcat and Java web apps in an executable JAR?
Cancel
Always timely and an excellent MVP-based tutorial!
Cancel
Thanks for the kind words.

This sets the base for some of the Java/Jakarta microprofile and Spring Boot tutorials that are about to come. The embedded Tomcat and executable JAR are exactly what's consumed by a Docker container and orchestrated by Kubernetes.
Cancel
how can i add database to it ? i tried after changing dynamic web app to maven and neccessary changes as your post to pom.xml but then when i run it said it failed to connect the database.I am wondering it is just tomcat server and is there a way to add sql database ? thank you it was really helpful tutorial .

Daniel M
Cancel

-ADS BY GOOGLE

SearchCloudApplications

SearchSoftwareQuality

SearchHRSoftware

SearchSAP

SearchERP

DevOpsAgenda

Close