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
andyourAppPackageName
you have to provide your app's name and its package name. In our example app, we invoke the task withant 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
andWEB-INF/web.xml
. The parameteryourAppPackageName
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 thebuild war -Dappname=yourAppName
command, which means the WAR file is built before the deploy. The location of the deploy folder is detected by using theserver.folder
property, by appending thewebapps
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.
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.