CommunityBoard - Build and installation instructions

1. Introduction

1.1 CommunityBoard

The CommunityBoard project is a little Forum / Note publishing application. Its main purpose it to act as an introducting laboratory to Java EE programming. As such the functionalities are rather limited. Yet it covers the most fundamental aspects or issues with Java EE programing in the way it show hows to :

write entity beans with bi-directional relationship;
use these Entity beans in EJBs (Statless session beans);
use other EJBs in EJBs;
use EJBs in a servlet or a JSP located in a WAR (i.e. no processing of the @EJB annotation);
build a multi-module Java EE maven project with jars, wars, ears;
how to write JSPs with the JSTL (Ok I am not verys proud of these JSPs yet they do the job) and
deploy a multi-module ear within GLassfish and use a container defined datasource

1.2 This README document

This document covers the few steps required to build and install the CommunityBoard EAR on a Glassfish 3.0 server and presents avery brief manual intstruction. The document assumes a basic knowledge of maven command and the Glassfish 3.0 server.

As a sidenote, one should know the maven pom files provided here make usage of the maven-eclipse-plugin allowing a smooth project integration within eclipse simply by typing mvn eclipse:clean eclipse:eclipse at the root of the project. This command creates the eclipse project files (.project, .classpath, etc.).
This being said, the maven to eclipse project integration won't be covered any further in this document.

In the same way, this document assumes a basic knowledge of the usual maven commands and the basis of the Glassfish 3.0 Java EE application server on the reader side. We wont cover here the installation of both maven and glassfish and the way to use these tools.

2. A few technical informations

2.1. The project structure

The project structure is as follows :

CommunityBoard The agregation module: this one agregates the 3 other modules to produce a Java EE ear file containing the 3 other modules.

CommunityBoard_data The entity module (data layer). This one is a JPA project which provides the Java EE entity beans used by the project. This modules is packaged as a java .jar and defined as a jar module within the agregation ear.

CommunityBoard_services The services module (business layer). This modules provides the various business services used by the CommunityBoard application. This modules is packaged as a java .jar file on its own and defined as an ejb module within the agregation ear.

CommunityBoard_presentation The Web module (presentation layer). This modules provides the front controller as well as various JSPs used to present the data and provides the user with ways to manipulate the data. This module is packaged as a java EE .war file on its own and defined as a web module within the agregation ear.

pom.xml The root maven POM file.

docs A few files (mostly images) used by this README file.

Each individual module is very simple and only holds a few Java files or JSPs as well as its own maven POM file which defines the precise way to build it. This documentation won't cover much more into details the precise content of these modules and the author strongly encourage the reader to take a quick look at these modules before going any further with the reading of this document.

2.2. The project dependencies

The CommunityBoard project has only 2 dependencies. The snippet of the root maven POM file which defines the dependencies is :

        <dependency>
            <groupId>org.apache.derby</groupId>
            <artifactId>derbyclient</artifactId>
            <version>10.6.1.0</version>
        </dependency>
        <dependency>
            <groupId>javax</groupId>
            <artifactId>javaee-api</artifactId>
            <version>6.0-SNAPSHOT</version>
            <scope>provided</scope>
        </dependency>

derbyclient is the JDBC client to the Glassfish embedded Derby database we will be using.
javaee-api is a required compile time only dependency for pretty much every Java EE project.

There are actually a few more dependencies such as taglibs for the JSP files. It is however not required to declare these taglibs in the maven POM file as they are neither required for the maven compilation (JSPs are compiled by the application server) nor are they required at deployment (both eclipse and glassfish provide them natively).

3. Building and installation

3.1 Build the application

Building the application, thanks to maven, couldn't be more straightforward. One only needs to cd into the root folder of the project and build the application with the usual maven command :

user@notebook:/data/.../workspace$ mvn clean install
[INFO] Scanning for projects...
[INFO] Reactor build order: 
[INFO]   Niceideas CommunityBoard project
[INFO]   Niceideas CommunityBoard - data layer
[INFO]   Niceideas CommunityBoard - business layer
[INFO]   Niceideas CommunityBoard - presentation layer
[INFO]   Niceideas CommunityBoard - Agregate EAR
[INFO] ------------------------------------------------------------------------
[INFO] Building Niceideas CommunityBoard project
[INFO]    task-segment: [clean, install]
[INFO] ------------------------------------------------------------------------
...
...
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] Niceideas CommunityBoard project ...................... SUCCESS [3.103s]
[INFO] Niceideas CommunityBoard - data layer ................. SUCCESS [6.652s]
[INFO] Niceideas CommunityBoard - business layer ............. SUCCESS [2.206s]
[INFO] Niceideas CommunityBoard - presentation layer ......... SUCCESS [4.780s]
[INFO] Niceideas CommunityBoard - Agregate EAR ............... SUCCESS [1.459s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 18 seconds
[INFO] Finished at: Sun Oct 24 09:47:18 CEST 2010
[INFO] Final Memory: 28M/119M
[INFO] ------------------------------------------------------------------------

The above is what should be displayed on the console if the build is successful (really there's no reason for it not to be successful).

The build ends up with the project ear file located at ./CommunityBoard/target/CommunityBoard-1.0-SNAPSHOT.ear. This is the file we will be deploying within Glassfish.

3.2 Create the datasource

This section and the one below assume the glassfish application server is started and the user/reader has access to the administration console.
(Just as a sidenote, glassfish is typically started by : $ glassfish/bin/startserv domain2)

In addition to the glassfish application server, the glassfish embedded derby database server should be started as well. (Just as a sidenote, the embedded derby is typically started by : $ glassfish/bin/asadmin start-database --dbport 1527 --dbhome glassfish/databases)

3.2.1 Define the datasource

A datasource named jdbc/CommunityBoardDS in the JDNI tree is required for the CommunityBoard application to work properly. Under glassfish the datasource is easily defined through the admin console by using the 2 links under the Resource/jdbc menu on the left :

First, one should create a new Connection Pool named CommunityBoardPool for a Derby database. The type of the resource is javax.sql.Datasource :

On the next page, one should go to the bottom of the page and set the connection properties as follows :

The mandatory properties are :

DatabaseName : CommunityBoard

User : admin

Password : whatever

The other properties depend pretty much on your local glassfish installation. In general the embedded derby server is configured by default as accepting any string as password (hence the whatever above).

Then one should create a new JDBC resource named jdbc/CommunityBoardDS and using the provided Derby Pool :

This is it. The datasource is created an available to deployed applications.

3.2.2 Create the database.

Now the CommunityBoard database should be created. This involves creating the four tables used by the application and populating them with initial test data.
The project contains a DDL file located at CommunityBoard_data/src/main/ddl/create_db.sql and a little SQL file containing the test data located at CommunityBoard_data/src/main/ddl/insert_test_data.sql.

The reader is free to use pretty much any SQL client she is used to. With DBVisualizer for instance, the SQL statements from the SQL files can be easily executed (only one after the other when using the free version of the tool though).
Under DBVisualizer, the DB connection is defined as follows :

The derby JDBC client driver can be located in the maven local repository once the project has been built at least once.

Please notice that the DDL file should be edited a little bit before usage. It cannot be immediately executed as is, at least not without removing first the 4 first lines which contains drop statements in case the script is executed many times. These drop statements should be commented out or the script will most likely fail upon execution.

3.3 Deploy the ear

Deploying the ear file built by maven is a piece of cake with glassfish. We'll use the glassfish admin console here for the sake of simplicity.

The ear file to be deployed has been generated by maven in CommunityBoard/target/CommunityBoard.ear

One only needs to select the Applications item in the menu on the left and then click on Deploy.
On the next page, when one selects the ear we have built previously, the admin console fullfils automatically the rest of the page :

If everything goes fine, the admin console should display the following page which shows the CommunityBoard application successfuly deployed :

The user can now reach the following URL with her favorite browser to start using the application : http://localhost:8080/CommunityBoard_presentation/controller/login.do.

The test data insertion script should have created a few users, the first one is

Username : user1

Password : pwd1

which one simply need to type in on the following screen :

4. A few concerns ...

Just a few concerns :

The JSP are most likely too complicated and a JSP expert would surely be able to do the same or more in twice less lines of code using proper JSP tags.
Besides, there is the concept of backing bean which I couldn't dig very much into details.
Well, don't shoot me, I did my best in such a short time.
I am not yet 100% sure the ServiceLocator used in the web layer to grasp references on EJB's is required. It's just that I haven't been able to find a way to make the @EJB annotation work from within the servlet or the JSP pages once I put them and the EJBs in separated projects.
So I thi8nk glassfish just doesn't take into accound a WAR project for annotation processing and hence the ServiceLocator is required.
(Please don't hesitate to contact me should you have a better understanding of this issue or a fix to submit for it)

`CommunityBoard`	The agregation module: this one agregates the 3 other modules to produce a Java EE ear file containing the 3 other modules.
`CommunityBoard_data`	The entity module (data layer). This one is a JPA project which provides the Java EE entity beans used by the project. This modules is packaged as a java `.jar` and defined as a `jar` module within the agregation ear.
`CommunityBoard_services`	The services module (business layer). This modules provides the various business services used by the CommunityBoard application. This modules is packaged as a java `.jar` file on its own and defined as an `ejb` module within the agregation ear.
`CommunityBoard_presentation`	The Web module (presentation layer). This modules provides the front controller as well as various JSPs used to present the data and provides the user with ways to manipulate the data. This module is packaged as a java EE `.war` file on its own and defined as a `web` module within the agregation ear.
`pom.xml`	The root maven POM file.
`docs`	A few files (mostly images) used by this README file.

`DatabaseName`	: `CommunityBoard`
`User`	: `admin`
`Password`	: `whatever`