Getting started with WildFly Swarm

Wildfly Swarm is a project which can be used to provide your application as single archives with just enough of the Wildfly application server wrapped around it to support the application execution.

IMPORTANT: The Thorntail project (formerly known as WildFly Swarm) has reached End Of Life. The last Thorntail release is the 2.7.0. You are recommended to evaluate a migration plan for your applications. Check this tutorial to learn more: How to migrate Thorntail applications

What is WildFly Swarm?

So you probably have heard about microservices recently? Then you can be happy to hear that now you can create self-contained executable jar. This jar will contain all the services needed to start your application. So, how do we get started ?

  1. Firstly, adjust your pom.xml to include wildfly-swarm-plugin
  2. Turn your dependencies into wildfly-swarm dependencies.

You’ll eventually get another artifact with a name like to yourproject-swarm.jar.

Creating your first Project

Meanwhile we will try to run our first example which will be even simpler, as we will start from scratch, without any parent pom.xml. So create a simple Maven project with the following pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<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>swarm.demo.servlet</groupId>
  <artifactId>hello-swarm</artifactId>
  <name>Wildfly Swarm Example</name>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>war</packaging>

  <properties>
    <version.wildfly.swarm>1.0.0.Final</version.wildfly.swarm>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
    <failOnMissingWebXml>false</failOnMissingWebXml>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.wildfly.swarm</groupId>
        <artifactId>bom</artifactId>
        <version>${version.wildfly.swarm}</version>
        <scope>import</scope>
        <type>pom</type>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <build>
    <finalName>demo</finalName>
    <plugins>
      <plugin>
        <groupId>org.wildfly.swarm</groupId>
        <artifactId>wildfly-swarm-plugin</artifactId>
        <version>${version.wildfly.swarm}</version>
        <executions>
          <execution>
            <goals>
              <goal>package</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

  <dependencies>
    <!-- Java EE 7 dependency -->
    <dependency>
      <groupId>javax</groupId>
      <artifactId>javaee-api</artifactId>
      <version>7.0</version>
      <scope>provided</scope>
    </dependency>
    <!-- Wildfly Swarm Fractions -->
    <dependency>
      <groupId>org.wildfly.swarm</groupId>
      <artifactId>undertow</artifactId>
    </dependency>
  </dependencies>
</project>

Just three things to notice:

  • We have included a war packaging so that we will endup with a self-executable web application. Additionally, we have included the maven-war-plugin so that we will be able to create a compliant web archive, with no requirement to include web.xml (failOnMissingWebXml is false)
  • We have included the wildfly-swarm-plugin. This is bound to the package Maven goal phase. It will create a runnable archive, packaged with the required dependencies.
  • Finally, the required dependencies used in your project.

As we are going to run just a simple Servlet, all we need is:

    <dependency>
      <groupId>javax</groupId>
      <artifactId>javaee-api</artifactId>
      <version>7.0</version>
      <scope>provided</scope>
    </dependency>

    <dependency>
      <groupId>org.wildfly.swarm</groupId>
      <artifactId>undertow</artifactId>
    </dependency>
  </dependencies>

Now just include a simple Servlet in your project:

package swarm.demo.servlet;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

 
@WebServlet("/Hello")
public class HelloServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        resp.getWriter().write("Hello from Servlet at " + new java.util.Date());
    }
}

That’s all. Build your maven project with:

mvn clean package

Now you can run your application with:

mvn wildfly-swarm:run

A minimal version of WildFly will start (with just the dependencies you have included in the project) and the hello-swarm.war will be deployed:

swarm wildfly tutorial

Since WildFly Swarm supports one deployment per executable, it automatically adds a jboss-web.xml to the deployment if it doesn’t already exist. This is used to bind the deployment to the root of the web-server, instead of using the .war’s own name as the application context.

Now you can try to access the application with:

http://localhost:8080/Hello

swarm wildfly tutorial

Pretty neat isn’t it?

Beyond the basics

A whole lot of great examples of WildFly Swarm do exist at: https://github.com/wildfly-swarm/wildfly-swarm-examples

I’d strongly recommend to download and try them. As you can see from the examples, creating more complex applications will require just to include the correct wildfly-swarm dependencies will will eventually result in a new application server with the required capabilities. For example, if you needed to include JPA and PostgreSQL Driver in your simple project, then you would need including the following set of dependencies to your project:

    <dependency>
      <groupId>org.wildfly.swarm</groupId>
      <artifactId>jpa</artifactId>
    </dependency>
    <dependency>
      <groupId>org.wildfly.swarm</groupId>
      <artifactId>jpa-postgresql</artifactId>
    </dependency>
  </dependencies>

Configuring Dependencies is now simpler than ever, thanks to the Project generator: check out this article for more information about it: How to create a JEE application with WildFly Swarm in two simple steps

Found the article helpful? if so please follow us on Socials