Prerequisites

Preparing the environment to run a Java EE web application (with JPA and JSF) requires a set of tools and APIs that are described below. The order of installing and testing the components is relevant in some cases, therefore we recommend to do it in the order described below.

The Java Development Kit

Java JDK 8, known as Java Development Kit, is required to compile and run Java programs. Download the latest available 7.x or 8.x version. You need to download and install the JDK corresponding to your operating system, e.g., Linux 32/64 Bit, Windows 32/64 Bit, MacOS and so on. Run the installation and follow the instructions. Ensure that you have the required 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 (Java Runtime Environment) which does not contain the necessarily tools for compiling and building Java applications.

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 Java EE "container", allowing to run Java EE web apps. We have used version v7.0.1, so if you install a newer version and run into problems with your deployment effort (getting various exceptions) you may go back to v7.0.1.

Extract the downloaded archive content and 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) do not contain the required JPA and JSF API jars.
• 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.

Create and Deploy Java EE Web Applications using the ANT Script

For simplifying things, we provide an ANT script that allows to create the skeleton of a Java EE web app, 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.

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

The ANT Scripting Tool

Apache ANT is needed only to run an ANT script , 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 find 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.