Minimal Maven-Based Web Application Project

In this post, we present the minimal ingredients of a mavenized standard J2ee web application from scratch to viewing the sample Hello World message under your favourite application server. Faithful to our diagram-first approach of tutorial presentation, we start with our main participants below.

1. Prerequisites

Let us first start by listing the prerequisites. First, is a maven installation at some root maven home denoted by M2_HOME . The mvn command under M2_HOME/bin should be included in your global PATH environment variable. Second, is your favourite application server. Here we use Sun Glassfish Enterprise Server v2.1.1 with a ‘standard’ domain configuration. Third is optionally a Java IDE into which you could open your mavenized Java project. We do not make use of any IDE here as any primitive text editor would suffice to create our sample Java class.

We also assume a basic knowledge of a standard Java web application as defined by the servlet specification. You should at least know the utility of the /WEB-INF directory inside a packaged WAR (web application archive) file and the web.mxl configuration file. The focus here is not on the technical details of every participant but on how to quickly concoct a functional web application skeleton.

2. Mavenization

As far as maven is concerned, a project pom.xml file has to be present at the project root directory. Then, Java code should reside under the [/src/main/java] directory to be picked up correclty by the compile phase. The requirements of a J2EE web application impose 2 more artifact directories which are the (a) [/src/main/webapp] directory for general web content and (b) [/src/main/webapp/WEB-INF] corresponding to everything that should belong into the WEB-INF directroy as specified by the latest Java Servlet specification. These 4 elements constitute our software participants and are summarized in the table below :

3. The WEB-INF/lib Directory

Why isn’t there a WEB-INF/lib directory in the diagram ? Well, in a well-behaved mavenized project, dependencides would be declared in the pom.xml file’s <dependencies> section to be eventually picked up by the ‘mvn package’ goal and lumped under the resulting WAR file’s output /WEB-INF/lib directory. Just declare correctly any libraries you need, the goal in the diagram above will take care of the rest.

4. The pom.xml File

This is what makes the web project 'mavenized'. It is maven's project description file and in our case will inlude the project identification triple (groupId, artifactId, version) plus the kind of packaging that we intend for our project. It's basically project type but in maven vocabulary. The 'war' packaging specified below is what will force maven to generate the WAR file and compose correctly its contents.

---

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>org.jt.webapps</groupId>
  <artifactId>minimal-webproj</artifactId>
  <version>1.0-SNAPSHOT</version>
  <name>Minimal Mavenized Web Application</name>

  <packaging>war</packaging>
</project>

---

5. The web.xml File

For a minimally functional web application, you will need a standard web.xml file. In a packaged WAR, this will reside directly under the WEB-INF directory. In a mavenized web application project, you have to create/place it under the [src/main/webapp/WEB-INF] directory. In the example below, we’ll just declare the root file of our web application to be the index.jsp file under the welcome-file tag.

---

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5"
  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/web-app_2_5.xsd">

  <welcome-file-list>
    <welcome-file>index.jsp</welcome-file>
  </welcome-file-list>
</web-app>

---

6. The index.jsp File

Our index.jsp sample file is really minimal. It does not even contain a reference to JSP. We just append the '.jsp' extension to a normal HTML file containing our greeting message.

---

<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
  <title>Minimal Mavenized Web Application Project</title>
</head>

<body>
<h2>Congratulations, It Works !!!</h2>

</body>

---

7. Building The Project

Once all the elements are well in place, we only have to execute the mvn command to compile and package the application into a WAR file. The command below executes all the goals from 'clean' to the 'package' goal which assembles the relevant artifacts into the application WAR. It should be executed at the root of the web project where resides the pom.xml file.

---

>mvn clean package
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------
[INFO] Building Minimal Mavenized Web Application
[INFO] task-segment: [clean, install]
[INFO] ------------------------------------------------------------------
[INFO] [clean:clean {execution: default-clean}]
[INFO] Deleting directory c:\\minimal-webproj\target
[INFO] [resources:resources {execution: default-resources}]
[INFO] skip non existing resourceDirectory c:\minimal-webproj\src\main\resources

[INFO] [compiler:compile {execution: default-compile}]
[INFO] Compiling 1 source file to c:\minimal-webproj\target\classe
[INFO] [resources:testResources {execution: default-testResources}]
[INFO] skip non existing resourceDirectory c:\minimal-webproj\src\test\resources

[INFO] [compiler:testCompile {execution: default-testCompile}]
[INFO] No sources to compile
[INFO] [surefire:test {execution: default-test}]
[INFO] No tests to run.

[INFO] [war:war {execution: default-war}]
[INFO] Packaging webapp
[INFO] Assembling webapp[minimal-webproj] in [c:\minimal-webproj\trget\minimal-webproj-1.0-SNAPSHOT]
[INFO] Processing war project
[INFO] Copying webapp resources[c:\minimal-webproj\src\main\webapp
[INFO] Webapp assembled in[93 msecs]
[INFO] Building war: c:\minimal-webproj\target\minimal-webproj-1.0-SNAPSHOT.war
[INFO] ------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------
[INFO] Total time: 4 seconds
[INFO] Finished at: Wed Feb 01 16:59:55 CET 2012
[INFO] Final Memory: 13M/31M
[INFO] ------------------------------------------------------------------

---

The lines in bold character show the successive maven goals. We have included a dummy Java class called MyPojo.java just to illustrate a non-empty execution of maven's compiler:compile phase and show that the corresponding MyPojo.class file ends up under the /classes directory of the packaged WAR.

8. Deploying The Project

The [war:war] maven goal above is the one that generates the WAR file under the /target directory. With the web application WAR file under your belt, you are free to deploy it under your favourite application server. We used Glassfish Enterprise Server v2.1.1 as application server and used its administration console to add the web application (just click the 'Web Applications' link and the 'Add' button). If you are using tomcat, just drop the WAR under the /webapps directory of your tomcat root directory.

Architecture Diagram First Approach

1. Introduction
We start our blogging 'career' with one simple idea. That, in presenting or writing an article

about any kind of Java-based distributed system, an information often lacking in the tutorials

which I come across is a 'beautiful' architecture diagram clearly pointing out the set of

participants; at least runtime participants.

2. Software Participants
Distributed systems are usually modeled by graph-theoretic means into nodes and edges. It
is these nodes that are the participants exchanging 'messages'. In a typical presentation of a
Java-based software system, it is rarely the case that the most important participants be listed
or presented in a unified diagram right from the beginning. We advocate a diagram-first
approach that presents a top-view of the system and its main protagonists (i.e. participants).
If this is the first thing that a developer encounters, il will serve as a mental hook upon which
to register the details of the presentation. By contrast, classical or dominant presentation adopt
(rather unconsciously perhaps), a 'Syntax-First' approach; there often seems to be a rush to
show the first fragments of relevant configuration or the 'hottest' annotations to use. This is a
'parachuting' presentation. The developer is parachuted into the technology without telling him
how he found himself at that point of the coding space.

3. Hidden Software Participants
In today's complex distributed systems, these are just too many threads, too many listeners, too
many interceptors, and quite a few 'implicit' steps which participate in the successful operation
of a runnig distributed Java-based architecture. It's simply impossible to list every potential
participant both visible and 'implicit'. We shall call these 'implicit' participants, hidden participants.

The idea is to bear in mind, when drawing an introductory architecture diagram, the existence
of these hidden participants, and to make intelligent choices as to which should be revealed to
the developer. Personally, I often found it useful when Message-Driven-Beans (MDBs) are
explained, that the application server's JMS broker be explicitly mentioned and given due 'respect'.

Any software professional with little experience in message-oriented systems, can leave with a very partial understanding of MDBs if no mention is ever given to the application server's part in the functioning of the whole JMS setup.