In the following section, we will use Maven to create our first Java EE 7 web project. We will then add a welcome page for our application and use Maven again to deploy the project on the server. Maven is a complex tool that cannot be covered fully in the space we have here; what follows will use only a fraction of the possibilities it offers. For background knowledge on Maven, we recommend you study the Maven User Center tutorial (http://maven.apache.org/users/index.html) or relevant textbooks (Sonatype 2014) in  parallel to this chapter.

2.3.1  Creating an Empy Java EE 7 Web Project with Maven

The Maven system offers users the opportunity to define templates for particular types of Java projects. The generation of a template for a company project, for example, enables a higher degree of project standardization. These templates are known in Maven as archetypes. Corresponding archetypes also exist for Java EE 7 applications.

A pared down, “bare essentials” archetype for Java EE 7 projects has been developed by Adam Bien, whose credentials include membership of the Java Community Processes expert panel that worked on the Java EE 7 specification^[1]. We will use his template to generate an initial Maven project configuration and structure for our application.

In order to accomplish this, we will first either create a new directory for all current and future projects, or choose an existing directory to use^[2]. In the following section, we will name the directory Java-EE-Workspace. We will then switch to this directory in the command prompt and execute Maven with the archetype mentioned above. Please be aware that the command will be given with all options in one line of the command prompt:

mvn archetype:generate -DarchetypeGroupId=com.airhacks -DarchetypeArtifactId=javaee7-essentials-archetype -DarchetypeVersion=1.2

Since Maven refers to a central directory in the Web for information about the archetypes and libraries required for the project, working with Maven requires us to maintain a connection to the Internet. Maven creates a directory called .m2 in the Home directory of the user, where it deposits local copies of data and libraries requested from the central directory. This increases the speed at which Maven runs during subsequent use.

The creation of Maven projects in interactive mode (standard setting) occurs in a step-by-step fashion whereby different information about the project is requested from the user. First, we will be asked by Maven about the groupId: a unique identifier for the organization or group that created the project. It is customary here to use the fully qualifed domain name of the individual organization; for our book, therefore, we will enter the domain of dpunkt.verlag, de.dpunkt:

Define value for property 'groupId': : de.dpunkt

Next, we will be asked for the artifactId, a unique base name for the primary artifact that is created by the project. This is usually a Java archive (e.g. WAR or EAR). A typical Maven-generated artifact takes the form <artifactId>-<version>.<extension>; however, the archetype we are using disregards the version number at this step. For our project, we will use the name my-aktion as the artifactId.

Define value for property 'artifactId': : my-aktion

Next, the version number can also be entered. 1.0-SNAPSHOT is provided as a default value. The addition of SNAPSHOT indicates that this version is still in development. We can accept this default by pressing the enter key.

Define value for property 'version':  1.0-SNAPSHOT: :

When asked for the property package, we will enter the value de.dpunkt.myaktion and press the enter key. This value will later serve as a prefix for our project’s Java packages.

Define value for property 'package':  de.dpunkt: : de.dpunkt.myaktion

Next, all information that has been entered thus far will be summarized and can be confirmed by pressing Y and then the enter key:

[INFO] Generating project in Interactive mode
[INFO] Archetype repository missing. Using the one from [com.airhacks:javaee7-essentials-archetype:1.2] found in catalog remote
Define value for property 'groupId': : de.dpunkt
Define value for property 'artifactId': : my-aktion
Define value for property 'version':  1.0-SNAPSHOT: :
Define value for property 'package':  de.dpunkt: : de.dpunkt.my-aktion
Confirm properties configuration:
groupId: de.dpunkt
artifactId: my-aktion
version: 1.0-SNAPSHOT
package: de.dpunkt.my-aktion
Y: : Y

You will then receive confirmation from Maven that the project has been successfully created (BUILD SUCCESS):

[INFO] ----------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: javaee7-essentials-archetype:1.2
[INFO] ----------------------------------------------------------
[INFO] Parameter: groupId, Value: de.dpunkt
[INFO] Parameter: artifactId, Value: my-aktion
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: de.dpunkt.my-aktion
[INFO] Parameter: packageInPathFormat, Value: de/dpunkt/my-aktion
[INFO] Parameter: package, Value: de.dpunkt.my-aktion
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: groupId, Value: de.dpunkt
[INFO] Parameter: artifactId, Value: my-aktion
[INFO] project created from Archetype in dir: C:\Users\MS\my-aktion
[INFO] ----------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ----------------------------------------------------------
[INFO] Total time: 02:03 min
[INFO] Finished at: 2014-06-10T20:32:06+01:00
[INFO] Final Memory: 11M/112M
[INFO] ----------------------------------------------------------

In the directory Java-EE-Workspace, you will now find a directory called my-aktion that contains the project structure for the Java EE web project. The configuration of the Maven project is stored in the file pom.xml^[3]. All information that has been entered thus far in interactive mode will be stored there, as will a number of values provided by the archetype. The file is nevertheless very compact (see Listing 2-1).

<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/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>${groupId}</groupId>
    <artifactId>${artifactId}</artifactId>
    <version>${version}</version>
    <packaging>war</packaging>
    <dependencies>
        <dependency>
            <groupId>javax</groupId>
            <artifactId>javaee-api</artifactId>
            <version>7.0</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
    <build>
        <finalName>${artifactId}</finalName>
    </build>
    <properties>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <failOnMissingWebXml>false</failOnMissingWebXml>
    </properties>
</project>

Listing 2-1     Initial Maven project configuration file pom.xml.

Essentially, our pom.xml file states that a web archive is to be created from the project (tag <packaging>), that the name of the web archive (and therefore also the web application) is my-aktion (tag <finalName>), that our project is dependent on the Java EE 7 API (tag <dependency>) and that Java 8 should be used (tag <maven.compiler.source> or <maven.compiler.target>).  Over the course of this workshop, we will continue to add to the file pom.xml and to integrate additional dependencies to libraries or plug-ins into the project. Our first change involves setting the character set for the source files of our project to UTF-8. To accomplish this, we will insert the following tag in the <properties> section:

<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

Theoretically, the my-aktion project that we have created can already be deployed in WildFly. However, since the project does not yet contain a Facelet, no pages can be displayed within the browser. Since we have not yet set up an IDE, you are free to choose the  text editor with which you wish to create the Facelets for your application’s welcome page. A suitable, free option is Notepad++, which offers a number of useful functionalities including syntax highlighting for different formats (http://notepad-plus-plus.org/).

Using the text editor, we will create a file index.xhtml in the directory my-aktion\src\main\webapp as shown in Listing 2-2. Make sure that the file is actually saved in the specified directory under the given name.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" 
        xmlns:h="http://xmlns.jcp.org/jsf/html"> 
    <h:head> 
        <title>Workshop Java EE 7</title> 
    </h:head> 
    <h:body> 
        <h1>Java EE 7: Welcome to our Workshop!</h1> 
    </h:body> 
</html>

Listing 2-2     Facelet index.xhtml

We have now created a Java EE web project with Maven and added the first Facelet. In order for the application server to recognize that it is dealing with a JSF application, we must add the configuration file faces-config.xml (as shown in Listing 2-3) to the directory my-aktion\src\main\webapp\WEB-INF. If directories are not present in your project folder, you must create these as well.

<?xml version="1.0" encoding="UTF-8"?>
<faces-config version="2.2"
    xmlns="http://xmlns.jcp.org/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
        http://xmlns.jcp.org/xml/ns/javaee/web-facesconfig_2_2.xsd">
</faces-config>

Listing 2-3 Configuration file faces-config.xml

This is not the only way to enable JSF for the application in the application server. For the moment, however, it is the easiest, since this file will also be required to internationalize our application in Chapter 4.

In the following section, we will make the project available on WildFly. In order to do this, all sources must be compiled and a web archive must be created built and deployed on the application server.

2.3.2 The First Build and the First Deployment

Maven’s functionality can be extended using plug-ins. We will use a Maven plug-in for WildFly to simplify the build and deployment process. The WildFly Maven plug-in enables us to transfer a web archive to the application server directly via the network. Plug-ins can be added to Maven projects using the file pom.xml. Within the <build> tag, we can add a <plugins> tag to specify our plug-ins. We can insert the WildFly plug-in as follows:

<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/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>${groupId}</groupId>
    <artifactId>${artifactId}</artifactId>
    <version>${version}</version>
    <packaging>war</packaging>
    <dependencies>
        <dependency>
            <groupId>javax</groupId>
            <artifactId>javaee-api</artifactId>
            <version>7.0</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
    <build>
        <finalName>${artifactId}</finalName>
        <plugins>
            <plugin>
                <groupId>org.wildfly.plugins</groupId>
                <artifactId>wildfly-maven-plugin</artifactId>
                <version>1.0.1.Final</version>
            </plugin>
        </plugins>
    </build>
    <properties>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <failOnMissingWebXml>false</failOnMissingWebXml>
    </properties>
</project>

Listing 2-4 Extended Maven project configuration file pom.xml.

Now we’re away! In order for the application to be deployed in WildFly, WildFly must be started. If this is not – or is no longer – the case, we can start the server in stand-alone mode as described in section 2.2.3. Use a new Windows command prompt to access the project directory my-aktion.

The WildFly-Maven plug-in provides several commands for controlling the deployment process^[4]. We will start the deployment of the project by using the following Maven command:

mvn package wildfly:deploy

This command specifies two Maven goals as parameters: package and wildfly:deploy. Maven goals perform a series of commands aimed at fulfilling a clearly defined goal.

The Maven goal package belongs to the standard phase of the Maven lifecycle and is responsible for ensuring that all classes are compiled and a web archive is created. The resulting file can be found in the target directory of the project folder. The Maven goal wildfly:deploy is made available by the Maven WildFly plug-in and carries out the deployment of the web archive on WildFly. Several status messages regarding the build and deployment process will appear in your window. Finally, a success message with the date and time should appear:

[INFO] ----------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ----------------------------------------------------------
[INFO] Total time: 3.439 s
[INFO] Finished at: 2014-06-10T20:55:20+01:00
[INFO] Final Memory: 13M/78M
[INFO] ----------------------------------------------------------

Take a look at the application server window. A message showing the action should appear here directly after deployment:

20:58:04,290 INFO  [org.wildfly.extension.undertow] (MSC service thread 1-2) JBAS017534: Registered web context: /my-aktion
20:58:04,311 INFO  [org.jboss.as.server] (management-handler-thread - 1) JBAS018559: Deployed "my-aktion.war" (runtime-name : "my-aktion.war")

We can also undo the deployment by executing the following command in the project folder:

mvn wildfly:undeploy

The removal of the application will also be displayed in the application server window:

20:59:16,125 INFO  [org.jboss.as.server] (management-handler-thread - 1) JBAS018558: Undeployed "my-aktion.war" (runtime-name: "my-aktion.war")

The build process works incrementally, which means that only new elements or elements that have changed since the last build will be compiled or added (during the creation of the web archive). For this reason, multiple iterations of elements that have been deleted or moved around within the project structure can still be located in the resulting web archive. It is necessary, therefore, to clean the project up from time to time; the Maven goal clean can help us to do this. The following command deletes the build area within the project’s target directory.

mvn clean

For the next section, you should have deployed the project successfully as described earlier using mvn package wildfly:deploy.

2.3.3 Testing the Deployment

We now want to test whether deployment has been carried out correctly. To do this, we can start a browser and access the following URL:

http://localhost:8080/my-aktion/index.jsf

Pay attention to upper and lower case, since Java EE differentiates between upper and lower case letters in URLs after the domain name.

If deployment was successful, the browser will display our site as an output as illustrated in Fig. 2-1.

Fig. 2-1 The welcome page of the My-Aktion application following successful deployment

Did you see something similar on your display? Congratulations! You have created your first Java EE web application and made it available on a WildFly application server. If not, you should review the individual steps once more and be on the lookout for potential errors.

As you will doubtless have noticed, the application does not yet possess any logic, and our only page consists of static content. Over the course of this book, you will learn step-by-step how real web applications are developed with Java EE. However, the build and deployment process will remain the same from this point onwards.

---