I can make IT

Welcome to part two of my tutorial for developing lightweight Java web applications! I meanwhile created an online code repository for the source files yo that you may refer to them more easily. You can either visit the project site or you can checkout the source files representing this part of the tutorial by using Subversion and calling the following command:

I have always been the hands-on guy, and I've always disliked documentations and tutorials that explain aspect of something without a surrounding context So in this tutorial, I'm going to explain the aspects of lightweight Java web applications by using a complete example application that actually does something.

During this tutorial, I will often skip man explanations of the source code itself, pointing out only the interesting and challenging parts. To get the whole picture, please refer to the source code repository.

Introducing JPokerStats

The application that is going to be developed is simply called JPokerStats. I play a lot of poker and I use a self-written Ruby on Rails application to track the games I've played with my friends. Basically what I'm doing now is rewriting the software in Java.
The database model behind JPokerStats is made up of three tables that will store all necessary data:

This tutorial assumes that you are already familiar with object-relational-mapping technologies or at least the concept behind it.

Setting up the project

We start off with the application by creating a skeleton using the Maven archetype plugin. We can achieve this by executing:

This will create some basic files for us such as the Maven project description (pom.xml), the necessary directory structures and the web specific files such as the web.xml which we are going to modify instantly by replacing the 2.3 header declaration with a 2.4 declaration. You might object and say that version 2.5 web applications are currently state of the art. You're right on this but we'll leave the version set to 2.4 for now and I will explain why in a later part of this tutorial.

Dependencies

Next we're going to define the projects dependencies. It already has a dependency on JUnit that we upgrade from version 3.8.1 to version 4.4 to be able to use annotations for our tests.
As the title of this tutorial states, we are going to use a lot of external libraries as can be seen in the following list:

• JSF API/RI 1.2_07
• Facelets 1.1.14
• JPA 1.0
• Spring Framework 2.5.1
• Apache Shale 1.1.0-SNAPSHOT

We will be adding the needed artifacts to the pom.xml. Notice that I have declared some properties containing various version numbers for libraries. Most of them consist of more than one artifact, so referencing a single version property make it easier to upgrade them at a later time. Some artifacts are not available in the central repository and need to be downloaded from other repositories. I have included those in the pom.xml, but after adding dependencies you should run mvn compile to check if they are all available.
Some artifact scopes are defined as provided. This means that Maven supplies those libraries at compile time but does not include them in a software release file (in this case the web archive or WAR), assuming that the servlet container or application server will provide them. If your server does not include those libraries (e.g. Tomcat doesn't) you might want to change the scope from provided to compile.

The first Java code

To finish off this part of the tutorial, we're finally going to write some Java code for the JPA layer of our project. So I create three classes, Game, Player and GameResult an put some attributes in them. As JPA objects are simple Java beans or POJOs, this step is quite easy. To simply the work with attributes such as gender or gameType, we define some enumerations to help us with these values.
After writing the Java classes, we need to instrument them for use with JPA. This tutorial is going to use HSQLDB for data storage because it can be run out of the box and needs no additional setup. But since we are using JPA you could use any other supported database such as MySQL, postgreSQL or Oracle.

The primary key is going to be generated and we leave the decision on how to do this to JPA. The JPA implementation will use the method it thinks is most suitable for the database used.

JPA is able to translate enumerations to database value either by saving the values position (e.g. 2) within the enumeration or by saving the value itself as string (e.g. MALE). I prefer the latter method because it makes the database easier to read and those few extra bytes do not actually matter (at least to me). So we're going to specify this behavior on the getter for gender.

We'll use the same way of annotating fields for the other classes as well. In addition, JPA requires us the specify how to store temporal values such as the date on which a game took place. We choose DATE for real date values where the time doesn't matter and choose TIME when we want only the times saved. In case we needed date and time saved together, we would specify TIMESTAMP.

By this, we are done for this part of the tutorial. In the next part, we will introduce JPA based relationships between the entities and configure the database and Spring for our application.