Getting Started

There are three ways to get started with WildFly Swarm. You can start out with a blank Java Maven or Gradle project and manually add dependencies and Maven plug-ins. Another option is to use the WildFly Swarm Generator web console to bootstrap your project (similar to Spring Initializr for Spring Boot). Lastly, you can use the JBoss Forge tool, which is a generic Java project creation and altering tool which makes it easy to add Java classes, dependencies, and entire classes of functionality (e.g., JPA and transactions) to a Java Maven project. We highly recommend JBoss Forge in general, and we will use it in the guide here. For completeness, we’ll also include the minimal plug-ins and dependencies you might need for a vanilla Java project. JBoss Forge also has plug-ins for the three most popular Java IDEs (Eclipse, Netbeans, or IntelliJ). 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]:

1. (x) war
2. ( ) jar
3. ( ) parent
4. ( ) forge-addon
5. ( ) resource-jar
6. ( ) ear
7. ( ) from-archetype
8. ( ) 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]

• ( ) JAVA_EE_7

• ( ) JAVA_EE_6
• ( ) 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.