Getting ready to run Java EE Web Applications

Prerequisites

Preparing the environment to run a Java JPA/JSF based Web Application requires a set of tools and APIs that are described below. The order of installing and testing the presented components is relevant in some cases, therefore you have to do it in the order presented by this article.

The Java Development Kit

Java JDK 8, known as Java Development Kit, is required to compile and run Java applications, in particular also Java based Web Applications.

Download the latest available minor version, but keep in mind that it should be the major version 7 or 8 (recommended since you'll need it for other applications too). You need to download and install the JDK installation kit corresponding to your operating system, e.g., Linux 32/64 Bit, Windows 32/64 Bit, MacOS and so on. Run the installation kit and follow the instructions. Ensure that you have the corresponding rights, especially in Linux/UNIX environments, where you may want to do it as the root user or by using sudo from the command line.

Note: make sure that you are downloading and installing the JDK and not the JRE which does not contain the necessarily tools for compiling and building Java applications, instead it is only a running environment, as the name recommends it: Java Runtime Environment.

Finally, test the correctness of the installation by running java -version in a shell, where you should see information about the newly installed JDK environment.

The TomEE Plume Applications Server Container

Apache TomEE Plume is a Tomcat based Java EE (Enterprise Edition) container, allowing to run Java based Web Applications. At the moment of writing this article, the latest available version is v7.0.1. We encourage you to use this exact version if the deployment of your application fails with various exceptions.

Extract the downloaded archive content then start the TomEE server by using the startup.bat on Windows or startup.sh on UNIX/Linux. Test it by opening a web browser and navigating to http://localhost:8080 and you should see the TomEE welcome page. If during the startup the following error occurs:

Neither the JAVA_HOME nor the JRE_HOME environment variable is defined
At least one of these environment variable is needed to run this program

It means that we need to set the JAVA_HOME environment variable so that it points to the root folder of your JDK installation path. In an Windows environment, this is usually something like: C:\Program Files\Java\jdk.x.y_z where x.y_z is the version number.

Notes:

  • be sure that you download the TomEE Plume version, because the other variants (e.g., Web Profile or PLUS) does not contain the JPA and JSF API jars, required to run the Web Applications discussed in our book and tutorials.
  • instead of using TomEE Plume, one can download Tomcat and the set of required API jars. However, the application code is slightly different in various points, specially related to JPA features because Tomcat is not an JavaEE container. A full list of differences between TomEE versions and Tomcat is available on the TomEE / Tomcat comparison web page.

The MySQL JDBC Driver

MySQL Connector/J is the official JDBC driver for MySQL. Download and extract the platform independent archive, and its root folder contains a file named mysql-connector-java-x.y.z-bin.jar (x.y.z is the version number, currently being 5.1.40), which needs to be copied in the lib sub-folder of the TomEE Plume installation. Restart the TomEE Plume server to have this library available for your Web Applications.

The Jettison JSON Library

Jettison is a JSON library for Java. We need this library to serialize some of the multiple valued properties, such as the ones expressed with the help of enumerations, then store them to MySQL. Later, the inverse operation transforms the JSON serialization to enumeration literal values. Download the JAR file and copy it in the lib sub-folder of the TomEE Plume installation. Restart the TomEE Plume server to have this library available for your Web Applications.

The ANT Scripting Tool

Apache ANT is needed only to run an ANT script that we wrote, which allows to generate the skeleton of a Java JPA/JSF Web Application, compile it, build it and deploy it to a TomEE container for being run and made accessible on the web. The ANT script and the corresponding parameters used for each operation (task) are discussed later in this article.

Installing Apache ANT requires to unzip the downloaded archive and add its bin sub-folder to your PATH environment variable. Test the installation by running ant in a shell, and you should see:

Buildfile: build.xml does not exist!
Build failed

This is a normal error message, informing us that there is no build.xml ANT script file. We learn more about the build.xml file and its content, later in this article. In case that you are getting the following error:

Unable to locate tools.jar. Expected to find it in C:\Program Files\Java\jre1.x.y_z\lib\tools.jar

It means that the ANT tool tries to use the JRE as default JDK, and it does not finds the required components. This is solved by setting the JAVA_HOME environment variable to point to the root folder of your JDK installation path. In an Windows environment, this is usually something like: C:\Program Files\Java\jdk.x.y_z where x.y_z is the version number.

Create and Deploy Java JPA/JSF based Web Applications using the ANT Script

For simplicity reasons, we wrote an ANT script that allows to create the skeleton of a Java JPA/JSF based Web Application, compile it, build the war file and deploy it to TomEE Plume Server. One may also use Eclipse, NetBeans or other IDEs for doing the same tasks. The ANT script generates a folder structure, which is compatible with Eclipse, so in case you want to use Eclipse, you may simply create an Eclipse project from the existing application code.

First time when using the script you should edit it (use your favorite text or XML editor) and set the value of the server.folder variable so that it reprensets the path to your TomEE installation folder. Presuming that your OS is Windows, and the TomEE installation folder is "c:\tomeeplume", then you should have:

<property name="server.folder" value="D:\servers\tomeeplume"/>

For a UNIX/Linux environment, if your TomEE is located under "/srv/tomeeplume", it must be:

<property name="server.folder" value="/srv/tomeeplume">

Hint: make sure that the user has the rights to write on the webapps subfolder (e.g., /srv/tomeeplume/webapps) of your TomEE installation folder, specially when using UNIX/Linux.

We do not intend to provide an an ANT tutorial, so we'll not get get into specific ANT details, but only discuss the tasks and their meaning for our ANT script.

create app -Dappname=yourAppName -Dpkgname=yourAppPackageName

allows creating the folder structure. Instead of yourAppName and yourAppPackageName you have to provide your app's name and its package name. In our example app, we invoke the task with ant create app -Dappname=publicLibrary -Dpkgname=pl.

The script creates the folder structure, as well as the required files src/META-INF/persistence.xml, WEB-INF/faces-config.xml and WEB-INF/web.xml. The parameter yourAppPackageName is used to create the Java top level packages. If omitted, yourAppName is used as Java top package name instead. For the next tasks/commands you have to be sure that the ANT script file is located in the same folder as your web application folder (and not one level deeper in the web application folder). This way, one can use the same ANT script for building multiple web applications.

The optional parameter, -Dforce=true allows to overwrite an already existing application.

build war -Dappname=yourAppName

allows building the WAR file by using yourAppName as file name. The resulting WAR file will be in the same folder as the ANT script file. For our example app we use the following command: ant war -Dappname=publicLibrary

Hint: before being able to use this command, you have to edit the ANT script and modify the value of the server.folder parameter so it points to your TomEE installation folder.

deploy -Dappname=yourAppName

allows deploying the WAR file associated with yourAppName to the TomEE web server. It automatically executes the build war -Dappname=yourAppName command, which means the WAR file is built before the deploy. The location of the deploy folder is detected by using the server.folder property, by appending the webapps folder name. For our example app we invoke the following command: ant deploy -Dappname=publicLibrary.

Hint: we do not recommend using spaces in folder names, but if for any reason, the application name needs to contain spaces, then it has to be enclosed in double quotes, e.g. create app -Dappname="Hellow World". Notice that in such a case, the pkgname parameter becomes mandatory, since "Hello World" is not a valid Java package name, thus it can't be used for this purpose.

Presuming that we deployed the Minimal App on a local TomEE server, by executing build war -Dappname=minimalapp, we can use a Web Browser and enter the application's index page URL: http://localhost:8080/minimalapp/faces/views/books/index.xhtml.

Download the ANT Script

Some Points of Attention

Due to a bug (or an incomplete feature) in TomEE Plume v7.0.x (v7.0.1 at the moment of writing this article), an "empty" beans.xml file had to be added to the WEB-INF folder. We quote "empty" because the file itself contains only the root XML element, but no other relevant information for our applications, so this file must not be required at all. Below is the content of the "empty" WEB-INF/beans.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://java.sun.com/xml/ns/javaee" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
       xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
                           http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
</beans>

When this file is missing, a chain of Java Exceptions are thrwon:

SEVERE [localhost-startStop-1] com.sun.faces.config.ConfigureListener.contextInitialized
  Critical error during deployment: com.sun.faces.config.ConfigurationException: 
  Factory 'javax.faces.lifecycle.ClientWindowFactory' was not configured properly.
  ...long chain of Java Exceptions...
Caused by: javax.faces.FacesException: com.sun.faces.lifecycle.ClientWindowFactoryImpl
  ...long chain of Java Exceptions...
Caused by: java.lang.NullPointerException
  ...long chain of Java Exceptions...

SEVERE [localhost-startStop-1] com.sun.faces.config.ConfigureListener.contextDestroyed
  Unexpected exception when attempting to tear down the Mojarra runtime
  java.lang.IllegalStateException: Could not find backup 
  for factory javax.faces.application.ApplicationFactory. 
  ...long chain of Java Exceptions...

Note: this behavior is not present in TomEE Plume 1.7.x.