Vanilla Java Project

If you have an existing Java project or you create one from scratch using a Maven archetype or your favorite IDE, then you can add the following pieces to your pom.xml to get up and running with WildFly Swarm. First we want to be able to create uber JARs that know what pieces of the Java EE API functionality should be included. To do this, we’ll use the WildFly Swarm Maven plug-in. Let’s add the WildFly Swarm Maven plug-in to our pom.xml:

<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>

We also want to include the WildFly Swarm BOM (bill of materials) as a dependency in our <dependencyManagement> section to help sort out the proper versions of all of the APIs and WildFly Swarm fractions that we may depend on:

<dependencyManagement>
    <dependencies>
        <!-- JBoss distributes a complete set of Java EE 7 APIs
            including a Bill of Materials (BOM). A BOM specifies
            the versions of a "stack" (or a collection) of
            artifacts. We use this here so that we always get
            the correct versions of artifacts. -->
        <dependency>
            <groupId>org.wildfly.swarm</groupId>
            <artifactId>bom</artifactId>
            <version>${version.wildfly.swarm}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Now you can add the fractions of the Java EE API you need (or leave the fractions out and let WildFly Swarm autodetect them; useful if migrating an existing WAR application)! Let’s take a look at some of the convenience that JBoss Forge brings.

Using JBoss Forge

JBoss Forge is a set of IDE plug-ins and CLI for quickly creating and working on Java projects. It has plug-ins for Netbeans, Eclipse, and IntelliJ to help you create Java projects, add CDI beans, add JPA entities, add and configure servlets, etc. Let’s look at a quick example. First verify you have JDK/Java 1.8 installed then install JBoss Forge.

Once you have Forge installed, you should be able to start up the CLI (all of these commands available in the IDE plug-in as well):

$ forge

Feel free to explore what commands are available by pressing Tab, which also gives auto-completion for any command. JBoss Forge is built on a modular, plug-in–based architecture which allows others to write plug-ins to take advantage of the built-in tooling for the CLI and your favorite IDE. Take a look at some of the addons contributed by the community, including AsciiDoctor, Twitter, Arquillian, and AssertJ. Let’s also install the WildFly Swarm addon for JBoss Forge:

[temp]$ addon-install 
--coordinate org.jboss.forge.addon:wildfly-swarm,1.0.0.Beta2

***SUCCESS*** Addon org.jboss.forge.addon:wildfly-swarm,
1.0.0.Beta2 was installed successfully.

Let’s try a project-new command to build a new Java EE project that will be built and packaged with WildFly Swarm. Follow the interactive command prompt with the following inputs:

[swarm]$ project-new
***INFO*** Required inputs not satisfied, interactive mode
* Project name:  hola-wildflyswarm
? Package [org.hola.wildflyswarm]: com.redhat.examples.wfswarm
? Version [1.0.0-SNAPSHOT]:  1.0
? Final name:  hola-wildflyswarm
? Project location [/Users/ceposta/temp/swarm]:

[0] (x) war
[1] ( ) jar
[2] ( ) parent
[3] ( ) forge-addon
[4] ( ) resource-jar
[5] ( ) ear
[6] ( ) from-archetype
[7] ( ) generic

Press <ENTER> to confirm, or <CTRL>+C to cancel.
* Project type: [0-7]

[0] (x) Maven

Press <ENTER> to confirm, or <CTRL>+C to cancel.
* Build system: [0]

[0] ( ) JAVA_EE_7
[1] ( ) JAVA_EE_6
[2] ( ) NONE

Press <ENTER> to confirm, or <CTRL>+C to cancel.
? Stack (The technology stack to be used in project): [0-2] 2
***SUCCESS*** Project named 'hola-wildflyswarm'
has been created.

So what we have right now is an empty Java project that doesn’t do too much. That’s OK, though; we’re just getting started. Let’s set it up for a JAX-RS application:

[hola-wildflyswarm]$ rest-setup --application-path=/
***SUCCESS*** JAX-RS has been installed.

Now, let’s add in the WildFly Swarm configurations like the Maven plug-in and the BOM dependency management section:

[hola-wildflyswarm]$ wildfly-swarm-setup --context-path=/
***SUCCESS*** Wildfly Swarm is now set up! Enjoy!

That’s it! Now let’s build and try to run our new WildFly Swarm microservice:

[HelloResource.java]$ cd ~~
[hola-wildflyswarm]$ wildfly-swarm-run

You should see it successfully start, but it doesn’t do anything or expose any REST services. But what did JBoss Forge create for us here? If you look at the directory structure, you should see something similar:

./pom.xml
./src
./src/main
./src/main/java
./src/main/java/com/redhat/examples/wfswarm/rest
    /RestApplication.java
./src/main/resources
./src/main/webapp
./src/test
./src/test/java
./src/test/resources

Pretty bare bones! If we look at the pom.xml, we see some relevant Java EE APIs and the WildFly Swarm plug-in/BOM:

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.wildfly.swarm</groupId>
        <artifactId>bom</artifactId>
        <version>${version.wildfly-swarm}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      <dependency>
        <groupId>com.redhat.spec</groupId>
        <artifactId>jboss-javaee-6.0</artifactId>
        <version>3.0.3.Final</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.redhat.spec.javax.servlet</groupId>
        <artifactId>jboss-servlet-api_3.0_spec</artifactId>
        <scope>provided</scope>
      </dependency>
      <dependency>
        <groupId>com.redhat.spec.javax.ws.rs</groupId>
        <artifactId>jboss-jaxrs-api_1.1_spec</artifactId>
        <scope>provided</scope>
      </dependency>
    </dependencies>
      <build>
        <finalName>hola-wildflyswarm</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>
            <configuration>
              <properties>
                <swarm.context.path>/</swarm.context.path>
              </properties>
            </configuration>
          </plugin>
        </plugins>
      </build>

Remember, however, WildFly Swarm will only package the pieces of the Java EE framework that you need to run your application. In this case, we’ve already set up JAX-RS APIs, so WildFly Swarm will automatically include the JAX-RS and servlet fractions of an application server and embed them in your application.

Let’s see how we can add some more functionality.

Add the HTTP Endpoints

Now let’s create a new JAX-RS endpoint with the rest-new-endpoint command and the interactive wizard, filling in the prompts using the following example as guidance:

[hola-wildflyswarm]$ rest-new-endpoint
***INFO*** Required inputs not satisfied, interactive mode
? Package Name (The package name where type will be created) 
[com.redhat.examples.wfswarm.rest]:

* Type Name (The type name):  HolaResource

[0] (x) GET
[1] ( ) POST
[2] ( ) PUT
[3] ( ) DELETE

Press <ENTER> to confirm, or <CTRL>+C to cancel.
? Methods (REST methods to be defined): [0-3]
? Path (The root path of the endpoint):  api/hola
***SUCCESS***
REST com.redhat.examples.wfswarm.rest.HolaResource created

That’s it! Forge has created the ./src/main/java/com/redhat/examples/wfswarm/rest/HolaResource.java JAX-RS resource for us, and it looks similar to this:

package com.redhat.examples.wfswarm.rest;

import javax.ws.rs.Path;
import javax.ws.rs.core.Response;
import javax.ws.rs.GET;
import javax.ws.rs.Produces;

@Path("/api/hola")
public class HolaResource {

        @GET
        @Produces("text/plain")
        public Response doGet() {
                return Response.ok("method doGet invoked")
                               .build();
        }
}

Let’s go to the root of the project, build it, and try to fire it up again:

[HelloResource.java]$ cd ~~
[hola-wildflyswarm]$ wildfly-swarm-run

And navigate in a web browser to http://localhost:8080/api/hola (if an endpoint is not correctly displayed at this endpoint, please go back and check the preceding steps):

What did we just do? We built a JAX-RS web application using native Java EE with the JBoss Forge tooling and then ran it as a microservice inside WildFly Swarm!

Externalize Configuration

At the time of this writing, WildFly Swarm does not have an opinionated way of doing configuration and folks can choose to use well-established configuration, frameworks like Apache Commons Configuration or Apache DeltaSpike Configuration. Feel free to pay attention to this JIRA thread for more. In this section, we’ll take a look at quickly adding Apache DeltaSpike Configuration for our configuration needs.

Apache DeltaSpike is a collection of CDI extensions that can be used to simplify things like configuration, data access, and security. Take a look at the DeltaSpike documentation. We’re going to use a CDI extension that lets us easily inject configuration properties that can be sourced from properties files, the command line, JNDI, and environment variables. To take advantage of CDI, JAX-RS, and DeltaSpike, let’s add a dependency on the jaxrs-cdi WildFly Swarm Fraction for integrating CDI and JAX-RS:

    <dependency>
      <groupId>org.wildfly.swarm</groupId>
      <artifactId>jaxrs-cdi</artifactId>
    </dependency>

We’ll also want to add a dependency on the DeltaSpike libraries:

    <dependency>
      <groupId>org.apache.deltaspike.core</groupId>
      <artifactId>deltaspike-core-api</artifactId>
      <version>1.5.3</version>
    </dependency>
    <dependency>
      <groupId>org.apache.deltaspike.core</groupId>
      <artifactId>deltaspike-core-impl</artifactId>
      <version>1.5.3</version>
    </dependency>

We can create a new file called META-INF/apache-deltaspike.properties as well to store our application-specific properties. In this example, we’ll try to grab our environment-specific properties from OS environment variables like we’ve been doing with the other frameworks and then default to values that may not exist. Edit your HolaResource class to add the @ConfigProperty annotation:

@Path("/api/hola")
public class HolaResource {

    @Inject
    @ConfigProperty(name = "WF_SWARM_SAYING",
        defaultValue = "Hola")
    private String saying;

    @GET
    @Produces("text/plain")
    public Response doGet() {
        return Response.ok(saying + " from WF Swarm").build();
    }
}

With this simple annotation, we’re able to quickly inject our properties from either the META-INF/apache-deltaspike.properties file, from the command line, from environment variables, or from JNDI. We will default to “Hola” if there is no environmental variable set. Take a look at the Apache DeltaSpike documentation for more ways to group or customize the functionality.

Now we can run our service with either java -jar target/hola-wildflyswarm-swarm.jar or with mvn clean install wildfly-swarm:run. We should see the default response “Hola from WF Swarm” and if we set the environment variable WF_SWARM_SAYING, then we should be able to alter the saying:

$ mvn clean install wildfly-swarm:run

$ export WF_SWARM_SAYING=Yo
$ mvn clean install wildfly-swarm:run

Expose Application Metrics and Information

To expose useful information about our microserivce, all we need to do is add the monitor fraction to our pom.xml:

    <dependency>
      <groupId>org.wildfly.swarm</groupId>
      <artifactId>monitor</artifactId>
    </dependency>

This will enable the WildFly management and monitoring functionality. From the monitoring perspective, WildFly Swarm exposes some basic metrics:

• Information about the node on which WildFly Swarm is running at /node

• JVM heap usage at /heap

• JVM/process thread information at /threads

We can also add our own health endpoints that can invoke some actions or query parts of our microservice to easily expose how our service is doing. You can leverage the built-in health checking probes of most modern clusters to call your microservice health endpoints to determine whether or not the microservice is healthy, and in some cases, just kill it and restart. See the WildFly Swarm documentation for more on adding health probes.

How to Run This Outside of Maven

We’ve seen a couple ways to run our WildFly Swarm microservice. For development, you’ll probably run with the Maven plug-in like this:

$ mvn clean install wildfly-swarm:run

When you build the binary, you can run it like this:

$ mvn clean package

This will take our project, whether it’s packaged as a JAR or a WAR (as specified by the <packaging> definition in your pom.xml) and turn it into an executable uber JAR. Then you can run it like this:

$ java -jar target/hola-wildfly-swarm.jar

Note, whatever your final build-artifact is named, the WildFly Swarm Maven plug-in will add the -swarm.jar extension to the name.