Generic Top

The early-bird price of the new Learn Spring Security OAuth course packages will increase by $50 on Wednesday:

>> CHECK OUT THE COURSE

1. Introduction

In this tutorial, we'll explore the differences between starting a Spring Boot web application via the mvn spring-boot:run command and running it after it is compiled into a jar/war package via the java -jar command.

Let's assume here you're already familiar with the configuration of the Spring Boot repackage goal. For more details on this topic, please read Create a Fat Jar App with Spring Boot.

2. The Spring Boot Maven Plugin

When writing a Spring Boot application, the Spring Boot Maven plugin is the recommended tool to build, test, and package our code.

This plugin ships with lots of convenient features, such as:

  • it resolves the correct dependency versions for us
  • it can package all our dependencies (including an embedded application server if needed) in a single, runnable fat jar/war and will also:
    • manage for us the classpath configuration, so we can skip that long -cp option in our java -jar command
    • implement a custom ClassLoader to locate and load all the external jar libraries, now nested inside the package
    • find automatically the main() method and configure it in the manifest, so we don't have to specify the main class in our java -jar command

3. Running the Code with Maven in Exploded Form

When we're working on a web application, we can leverage another very interesting feature of the Spring Boot Maven plugin: the ability to automatically deploy our web application in an embedded application server.

We only need one dependency to let the plugin know we want to use Tomcat to run our code:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId> 
</dependency>

Now, when executing the mvn spring-boot:run command in our project root folder, the plugin reads the pom configuration and understands that we require a web application container.

Executing the mvn spring-boot:run command triggers the download of Apache Tomcat and initializes the startup of Tomcat.

Let's try it:

$ mvn spring-boot:run
...
...
[INFO] --------------------< com.baeldung:spring-boot-ops >--------------------
[INFO] Building spring-boot-ops 0.0.1-SNAPSHOT
[INFO] --------------------------------[ war ]---------------------------------
[INFO]
[INFO] >>> spring-boot-maven-plugin:2.1.3.RELEASE:run (default-cli) > test-compile @ spring-boot-ops >>>
Downloading from central: https://repo.maven.apache.org/maven2/org/apache/tomcat/embed/tomcat-embed-core/9.0.16/tomcat-embed-core-9.0.16.pom
Downloaded from central: https://repo.maven.apache.org/maven2/org/apache/tomcat/embed/tomcat-embed-core/9.0.16/tomcat-embed-core-9.0.16.pom (1.8 kB at 2.8 kB/s)
...
...
[INFO] --- spring-boot-maven-plugin:2.1.3.RELEASE:run (default-cli) @ spring-boot-ops ---
...
...
11:33:36.648 [main] INFO  o.a.catalina.core.StandardService - Starting service [Tomcat]
11:33:36.649 [main] INFO  o.a.catalina.core.StandardEngine - Starting Servlet engine: [Apache Tomcat/9.0.16]
...
...
11:33:36.952 [main] INFO  o.a.c.c.C.[Tomcat].[localhost].[/] - Initializing Spring embedded WebApplicationContext
...
...
11:33:48.223 [main] INFO  o.a.coyote.http11.Http11NioProtocol - Starting ProtocolHandler ["http-nio-8080"]
11:33:48.289 [main] INFO  o.s.b.w.e.tomcat.TomcatWebServer - Tomcat started on port(s): 8080 (http) with context path ''
11:33:48.292 [main] INFO  org.baeldung.boot.Application - Started Application in 22.454 seconds (JVM running for 37.692)

When the log shows the line containing ‘Started Application', our web application is ready to be queried via the browser at the address http://localhost:8080/

4. Running the Code as a Stand-Alone Packaged Application

Once we pass the development phase and we want to progress towards bringing our application to production, we need to package our application.

Unfortunately, if we are working with a jar package, the basic Maven package goal doesn't include any of the external dependencies.

This means that we can use it only as a library in a bigger project.

To circumvent this limitation, we need to leverage the Maven Spring Boot plugin repackage goal to run our jar/war as a stand-alone application.

4.1. Configuration

Usually, we only need to configure the build plugin:

<build>
    <plugins>
        ...
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
        ...
    </plugins>
</build>

But our example project contains more than one main class, so we have to tell Java which class to run, by either configuring the plugin:

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <executions>
        <execution>
            <configuration>
                <mainClass>com.baeldung.webjar.WebjarsdemoApplication</mainClass>
            </configuration>
        </execution>
    </executions>
</plugin>

or by setting the start-class property:

<properties>
    <start-class>com.baeldung.webjar.WebjarsdemoApplication</start-class>
</properties>

4.2. Running the Application

Now, we can run our example war with two simple commands:

$ mvn clean package spring-boot:repackage
$ java -jar target/spring-boot-ops.war

More details regarding how to run a jar file can be found in our article Run JAR Application With Command Line Arguments.

4.3. Inside the War File

To understand better how the command mentioned above can run a full server application, we can take a look into our spring-boot-ops.war.

If we uncompress it and peek inside, we find the usual suspects:

  • META-INF, with the auto-generated MANIFEST.MF
  • WEB-INF/classes, containing our compiled classes
  • WEB-INF/lib, which holds our war dependencies and the embedded Tomcat jar files

That's not all though, as there are some folders specific to our fat package configuration:

  •  WEB-INF/lib-provided, containing external libraries required when running embedded but not required when deploying
  • org/springframework/boot/loader, which holds the Spring Boot custom class loader — this library is responsible for loading our external dependencies and making them accessible in runtime

4.4. Inside the War Manifest

As mentioned before, the Maven Spring Boot plugin finds the main class and generates the configuration needed for running the java command.

The resulting MANIFEST.MF has some additional lines:

Start-Class: com.baeldung.webjar.WebjarsdemoApplication
Main-Class: org.springframework.boot.loader.WarLauncher

In particular, we can observe that the last one specifies the Spring Boot class loader launcher to use.

4.5. Inside a Jar File

Due to the default packaging strategy, our war packaging scenario doesn't differ much, whether we use the Spring Boot Maven Plugin or not.

To better appreciate the advantages of the plugin, we can try changing the pom packaging configuration to jar and run mvn clean package again.

We can now observe that our fat jar is organized a bit differently from our previous war file:

  • All our classes and resources folders are now located under BOOT-INF/classes
  • BOOT-INF/lib holds all the external libraries

Without the plugin, the lib folder would not exist, and all the content of BOOT-INF/classes would be located in the root of the package.

4.6. Inside the Jar Manifest

Also the MANIFEST.MF has changed, featuring these additional lines:

Spring-Boot-Classes: BOOT-INF/classes/
Spring-Boot-Lib: BOOT-INF/lib/
Spring-Boot-Version: 2.1.3.RELEASE
Main-Class: org.springframework.boot.loader.JarLauncher

Spring-Boot-Classes and Spring-Boot-Lib are particularly interesting, as they tell us where the class loader is going to find classes and external libraries.

5. How to Choose

When analyzing tools, it's imperative to take account of the purpose these tools are created for. Do we want to ease the development or ensure smooth deployment and portability? Let's have a look at the phases most affected by this choice.

5.1. Development

As developers, we often spend most of our time coding without needing to spend a lot of time setting up our environment to run the code locally. In simple applications, that's usually not a concern. But, for more complex projects, we may need to set environment variables, start servers, and populate databases.

Configuring the right environment every time we want to run the application would be very impractical, especially if more than one service has to run at the same time.

That's where running the code with Maven helps us. We already have the entire codebase checked out locally, so we can leverage the pom configuration and resource files. We can set environment variables, spawn an in-memory database, and even download the correct server version and deploy our application with one command.

Even in a multi-module codebase, where each module needs different variables and server versions, we can easily run the right environment via Maven profiles.

5.2. Production

The more we move towards production, the more the conversation shifts towards stability and security. That is why we cannot apply the process used for our development machine to a server with live customers.

Running the code through Maven at this stage is bad practice for multiple reasons:

  • First of all, we would need to install Maven
  • Then, just because we need to compile the code, we need the full Java Development Kit (JDK)
  • Next, we have to copy the codebase to our server, leaving all our proprietary code in plain text
  • The mvn command has to execute all phases of the life cycle (find sources, compile, and run)
  • Thanks to the previous point, we would also waste CPU and, in the case of a cloud server, money
  • Maven spawns multiple Java processes, each using memory (by default, they each use the same memory amount as the parent process)
  • Finally, if we have multiple servers to deploy, all the above is repeated on each one

These are just a few reasons why shipping the application as a package is more practical for production.

6. Conclusion

In this tutorial, we explored the differences between running our code via Maven and via the java -jar command. We also ran a quick overview of some practical case scenarios.

The source code used in this article is available over on GitHub.

Generic bottom

The early-bird price of the new Learn Spring Security OAuth course packages will increase by $50 on Wednesday:

>> CHECK OUT THE COURSE
Comments are closed on this article!