When people talk about scalability, they are usually referring to how well an application performs with an ever-increasing load. Another type of scalability that needs attention during an application's life cycle is build scalability, or how well an application's build and deployment scales with ever-increasing complexity and components.

Maven is a build tool from Apache that addresses build scalability. Maven uses simple project descriptors and a highly extensible and open architecture to build, deploy, and release application components.

Through project descriptors, new components can be added to an application's build with little effort from a developer. Once added, Maven determines the component's placement in the application build order through its dependencies, and builds, deploys, and releases the new component and application bundle accordingly.

This article is not intended to be an extensive guide to using Maven and it assumes the reader has a working knowledge of Maven. For more in depth information about Maven's capabilities, visit http://maven.apache.org. Also, a good introduction to Maven's project descriptors and building a generic J2EE application with Maven is found in Charles Chan's article "Project Management: Maven Makes it Easy."

Benefits of Using Maven for WAS Deployment

With the tight integration between WebSphere Application Server (WAS) and WebSphere Studio Application Developer (WSAD), you may question the need to use an external tool to build and deploy J2EE applications to WebSphere. WSAD is a powerful, full-service tool that is capable of building J2EE applications and deploying them on WAS. However, there are some reasons for using Maven to supplement the building and deployment services provided by WSAD:

• Maven makes build independent of a developer's IDE. Developers are creatures of habit and prefer to work with the coding environment in which they are most comfortable and most productive. By using Maven to build and deploy applications, developers are free to use any IDE they choose, which should result in more efficient developers.
• Maven can easily be incorporated into a continuous integration environment. The frequent running of unit and integration tests and timely feedback afforded by continuous integration is crucial for team development. Maven builds are already supported by many continuous integration tools, including CruiseControl and Anthill.
• Maven runs on any environment with a J2SE SDK. Sometimes the target environment hosting WAS is not supported by a developer's chosen IDE. Even with the "write once, run everywhere" promise of Java, portability problems arise when Java applications are written on one environment and installed on another. Since Maven can run on every environment supported by WAS, J2EE applications can be built, tested, and deployed on the same environment hosting WAS, mitigating the chance portability issues go undetected.
• Maven can handle the most complex of build scenarios. As applications and systems become more complex and integrations between disparate enterprise resources become commonplace, it is essential that an application's build can be maintained easily and efficiently. Through a series of plug-ins, Maven is capable of interfacing with many commonly used, development resources. These plug-ins include support for testing through JUnit, source generation using XDoclet, static analysis via JDepend, interaction with Web servers such as Tomcat, plus many more. In addition to the existing Maven plug-ins, if an application's build needs to interface with a resource unsupported by Maven, plug-ins can easily be created using scripting, Java programming, or a combination of the two.

Installing the Needed Software

To illustrate how Maven can be utilized to deploy to WAS, a simple J2EE application will be deployed. The application will be bundled and deployed as an EAR and will consist of a utility JAR, an EJB JAR, and a WAR. For the purposes of this exercise, the development and deployment environment will consist of:

• WebSphere Application Server 5.1
• IBM JDK 1.4.1 (included with WAS install)
• Maven 1.0
• WebSphere 5.0/5.1 Plug-in 1.2

INSTALLING WAS
It is assumed that WAS is installed and working correctly. If WAS is not installed, run the WAS install wizard choosing the full installation.

Once WAS is installed, set the JAVA_HOME environment variable to $WAS_HOME/java, where WAS_HOME is the root directory of the WAS installation. This setting is required. The subsequent WAS deployment only works using IBM's JDK.

INSTALLING MAVEN
To install Maven, it's best to follow the Installing Maven instructions.

Once Maven is installed, create or edit the $HOME/build.properties file, where HOME is the user's home directory. In this file, add the following line:

maven.was5.home = $WAS_HOME

again, where WAS_HOME is the root directory of the WAS installation.

Of note, an Internet connection is required by Maven in order to download any needed dependency JARs. If the connection is through a proxy, additional proxy settings must be added to the $HOME/build.properties files.

INSTALLING WEBSPHERE PLUG-IN
The WebSphere 5.0/5.1 plug-in is available from the Maven Plug-ins project. Using this plug-in makes deploying J2EE applications to WAS extremely easy and provides a highly reusable approach to deploying many applications efficiently. To install the plug-in, use Maven itself. Simply enter the following command on a single line at a command prompt:

> maven plugin:download
-Dmaven.repo.remote=http://maven-plugins.sourceforge.net/maven/
-DgroupId=maven-plugins
-DartifactId=maven-was5-plugin
-Dversion=1.2

INSTALLING THE SAMPLE J2EE APPLICATION
The entire application is contained in the archive. To install the application, simply unarchive the files into any directory. This directory will be referred to as ROOT in the remainder of this article.

The Sample Application

PROJECT LAYOUT
In the situation of a multicomponent project, such as this J2EE application, it is easiest to divide the project into many modules with each one responsible for building a single component. Then have a top-level project controlling the building of the modules.

Each of the modules, as well as the top-level project, is a Maven project. Each of these Maven projects has the same general setup:

• A required Maven project descriptor (a project.xml file) that defines project dependencies, source files, and other metadata
• An optional Maven build script (a maven.xml file) that customizes the build for a project
• Optional project-specific properties (a project.properties file) used to customize the build setting for a project.

UTILITY JAR MODULE
The sample-util module (located at ROOT/modules/sample-util) creates a simple, utility JAR that might be shared across many application components. Setting up the sample-util JAR module is straightforward and involves defining the build information in the project descriptor as well as defining the target goal in the Maven build script.

Of note in the project descriptor is the sourceDirectory element. It defines the directory (relative to the sample-util directory) containing all the Java source files to be compiled into class files. These class files will be bundled into the sample-util JAR.

The Maven build script is as simple as it can get. It contains a single build goal, which is also defined as the default goal:

<!-- Install jar into local repository -->
<goal name="build" prereqs="jar:install"/>

The jar:install goal is the prerequisite goal because it is necessary for the JAR to be in Maven's local repository in order to build other subprojects depending on sample-util.

EJB JAR MODULE
The sample-ejb module (located at ROOT/modules/sample-ejb) creates an EJB JAR replete with all Java classes, deployed code, and EJB bindings needed for WAS deployment. Setting up this EJB JAR involves using a combination of out-of-the-box Maven plug-ins and customizing the build for WAS-specific details.

The build information found in this module's project descriptor is similar to that found in the sample-util project. The only change is the addition of dependencies. The most important dependency is the sample-util entry:

<dependency>
  <groupId>maven-was</groupId>
  <artifactId>sample-util</artifactId>
  <version>1.0</version>
  <properties>
    <ejb.manifest.classpath>true</ejb.manifest.classpath>
  </properties>
</dependency>

This dependency is crucial for a few reasons. First, it allows this project's source files to be compiled because all dependency JAR files are added to the compilation classpath. Second, it assures that Maven always builds the sample-util module before building the sample-ejb module. Last, the ejb.manifest.classpath element informs Maven to add the sample-util JAR to the classpath found in the EJB JAR's manifest, which is created by Maven.

The build script for this project is more involved than that found in the sample-util project. This is the result of the additional WAS-specific tasks that need to be completed in order to create an EJB JAR deployable on WAS.

Like the sample-util project, this project contains a build goal:

<!-- Install jar into local repository -->
<goal name="build" prereqs="ejb:install"/>

The ejb:install prerequisite goal is used to install the EJB JAR into the local repository so it too is available for building subsequent subprojects.

Prior to installing the EJB JAR to the local repository, WAS-specific deployed code must be added to the EJB JAR. This can be accomplished by attaining the was5:ejbDeploy goal provided by the WebSphere plug-in. To hook into Maven's build process, a custom post goal is defined:

<!-- generate deployment and rmic code for an ejb jar -->
<postGoal name="ejb:ejb">
  <attainGoal name="was5:ejbDeploy"/>
 
  <!-- copy jar with deployed code over original -->
  <copy file="${maven.was5.ejbDeploy.file.out}"
        tofile="${maven.build.dir}/${maven.final.name}.jar"/>
</postGoal>

This post goal is defined to run after the ejb:ejb goal, which creates the raw EJB JAR, is complete. The post goal in turn attains the was5:ejbDeploy goal and then copies the EJB JAR with deployed code over the original, raw EJB JAR.

Another aspect of creating WAS deployable EJB JARs is ensuring the EJB deployment descriptor and WAS EJB bindings are bundled with the EJB JAR. Bundling resource files inside an EJB JAR is accomplished by placing them in the src/ejb directory of this module. The src/ejb directory is significant as it is the default setting for the maven.ejb.src property. This property defines the root directory containing files to be included in the EJB JAR. When the resource files found in this directory are copied into the EJB JAR, the directory structure is preserved. Therefore, by placing both the ejb-jar.xml and ibm-ejb-jar-bnd.xmi files in the src/ejb/META-INF directory, these files are easily bundled in the EJB JAR in their correct location.

WAR MODULE
The sample-war module (located at ROOT/modules/sample-war) creates a WAR containing JSPs, servlets, and other WAR resources. Setting up the WAR module is, again, straightforward and involves correctly defining dependencies in the project descriptor as well as customizing the build script.

The build information found in this module's project descriptor is similar to that found in the sample-util module. Again, some dependencies are added to ensure correct compilation and bundling:

<dependency>
  <groupId>maven-was</groupId>
  <artifactId>sample-ejb</artifactId>
  <version>1.0</version>
  <type>ejb</type>
</dependency>
<dependency>
  <id>commons-codec</id>
  <version>1.3</version>
  <properties>
    <war.bundle>true</war.bundle>
  </properties>
</dependency>

By adding the sample-ejb dependency, Maven always builds the sample-ejb module before building the sample-war module. Also, note the war.bundle element for the commons-codec dependency. This informs Maven to bundle the commons-codec JAR in the WEB-INF/lib directory of the final WAR.

Again, the build script is very simple, like that for the sample-util module. It contains the single build goal with the single prerequisite goal. This time the prerequisite is war:install:

<!-- Install war into local repository -->
<goal name="build" prereqs="war:install"/>

The war:install prerequisite is called to install the WAR into the local repository so it too is available for building subsequent modules.

As for the WAR resources, they are automatically bundled into the final WAR provided they reside in the src/webapp directory of this module. This src/webapp directory is special as it is the default setting for the maven.war.src property. This property defines the root directory housing the files to be included in the WAR. So, to include JSPs, images, deployment descriptors, and the like, simply place those resources in that directory.

EAR MODULE
The final module is the sample-ear module (located at ROOT/modules/sample-ear). This module is responsible for bundling all other modules into an EAR and deploying it to WAS. As before, this is accomplished through project dependencies and a custom build script.

In addition to the normal setup, this module requires a couple of property settings to aid with the deployment. These properties are added to the project.properties file and are as follows:

maven.ear.appxml.generate = true
maven.ear.displayname = MavenWasSample

The maven.ear.appxml.generate property informs Maven to generate the deployment descriptor for the application. The maven.ear.displayname property sets the application's display name. This change in name is needed because the default display name contains illegal characters and is an invalid WAS application name.

This module's project descriptor lists all the other modules as dependencies to ensure correct compilation and bundling (see Listing 1).

By adding the other module dependencies, Maven always builds the other projects before building the sample-ear module. Also, note the ear.bundle and ear.appxml.war.context-root elements for the dependencies. The ear.bundle element informs Maven to bundle each dependency's final artifact in the EAR. The ear.appxml.war.context-root is unique to WAR dependencies and specifies which context root to use for the Web application. This value is added to the EAR deployment descriptor that is generated by Maven.

Like the sample-ejb module, the build script for this module involves some WAS-specific tasks used to actually deploy and start the J2EE application.

Again, like the other modules, this module contains a build goal:

<!-- Install ear into local repository -->
<goal name="build" prereqs="ear:install"/>

Prior to installing the EAR to the local repository, the WAS-specific goals can be invoked to actually deploy the EAR. This is accomplished via a post goal set to run after the ear:ear goal, which creates the EAR, is completed. This post goal in turn attains the WAS goals to actually perform the application deployment (see Listing 2).

The post goal provides the means to either deploy the EAR (using the was5:installApp and was5:startApp goals) or reinstall the EAR (using the was5:reinstallApp) over an existing deployment. How that choice is determined will be illustrated shortly in the Rebuild the Application section.

TOP-LEVEL PROJECT
The top-level project (located at ROOT) is responsible for building all the modules and acts as a controller over the entire build process.

The project descriptor is quite simple and contains only rudimentary metadata about the project. It is simple because the top-level project contains no source code so all the build information is omitted.

The build script is also very simple, yet very crucial to building the entire application. The default goal of the build script is build. This goal uses the Maven reactor plug-in to propagate the build goal to all of the modules contained in the application. The reactor is responsible for determining the module build order based on their individual dependencies and is responsible for attaining the build goal for each of the modules. The relevant goals are shown in Listing 3.

Deploying the J2EE Application

BUILD THE APPLICATION
With all the project descriptors and build scripts in place for the module, building and deploying the EAR is a simple exercise:

1. Ensure the WAS server is running.
2. Execute Maven from ROOT:

   > maven

3. Sit back and witness the magic.

What is actually witnessed from the command line are the steps Maven takes to build and deploy the application.

First, the Maven reactor determines the build order of the modules based on their interdependencies. This is indicated by the following output:

Starting the reactor...
Our processing order:
sample-util
sample-ejb
sample-war
sample-ear

Next, the first module, sample-util, is built. This is indicated by the following output:

+----------------------------------------
| Executing (build): sample-util
| Memory: 9M/10M
+----------------------------------------

The subsequent output details all the goals attained in order to create the sample-util JAR. These goals include:

• java:compile: compiles all the source files
• test:test: runs any JUnit tests
• jar:jar: actually bundles everything into the final sample-util JAR

After sample-util is built, sample-ejb is built as illustrated by the output:

+----------------------------------------
| Executing (build): sample-ejb
| Memory: 10M/19M
+----------------------------------------

The proceeding output details the step taken to create the sample-ejb EJB JAR. These steps for the most part mirror those taken to build the sample-util JAR.

Of special note are the many lines of output involving the was5:ejbDeploy goal whose successful completion is indicated by:

[wasEjbDeploy] EJBDeploy complete.
[wasEjbDeploy] 0 Errors, 0 Warnings, 0 Informational Messages

Next, sample-war is built, which is indicated by the output:

+----------------------------------------
| Executing (build): sample-war
| Memory: 17M/19M
+----------------------------------------

Again, a series of goal output follows detailing the steps required to build the WAR.

Finally, sample-ear is built starting with the output:

+----------------------------------------
| Executing (build): sample-ear
| Memory: 17M/19M
+----------------------------------------

Of special note in the subsequent output are the many lines of output involving the was5:installApp and was:startApp goals whose successful completion are respectfully indicated by:

[wasInstallApp] ADMA5013I: Application MavenWasSample installed successfully.

and

[wasStartApp] Started Application [MavenWasSample]

VERIFY THE DEPLOYMENT
After Maven is finished deploying the EAR, the application can be tested to ensure the EAR was successfully deployed. The Web application contains a simple JSP page accessible at http://localhost:9080/sample/digest.jsp. If the EAR is working properly, the page should display a simple form that can be used to perform MD5 hashing of entered text.

REBUILD THE APPLICATION
Once the application is working correctly, it may become necessary to reinstall the application if it is ever modified. This can also be accomplished through Maven by adding a property to the command line:

> maven -Dwas.reinstall.app=true

Customize the Deployment

Throughout the article a WAS default installation on a local machine was assumed. To deploy the application to a WAS instance with a special configuration, the build needs to be modified to accommodate those unique environments. Luckily, the WebSphere plug-in provides many configurable properties that can be set to alter the deployment behavior. Some of the most commonly used properties are shown in Table 1.

To use the SE properties, simply specify new property values on the command line. For example, to deploy the application to a different server needing user authentication, use a command like the following:

> maven -Dmaven.was5.server=myserver -Dmaven.was5.username=deployer
-Dmaven.was5.password=pw4deployer

The plug-in offers a wider range of configuration properties than those listed above and used in this article. Be sure to visit the WebSphere plug-in Web site to learn all of the plug-in's options

Promise of Build Scalability

In the beginning of this article, it was stated that Maven could help address build scalability by making it easy to add and maintain new components to a J2EE application.

How easy is it to add another EJB JAR or WAR to this application? To add another utility JAR, EJB JAR, or WAR to the application, all that needs to be done is to replicate the subproject structure for the type of component to be added, modify the project descriptor with the new project metadata and dependencies, and finally add the new component to the EAR's list of dependencies. After that is complete, when Maven is used next to deploy the EAR, the new component will be built with all the other modules and it will be bundled in the final J2EE application.

Summary

The ease of building and deploying J2EE applications and its ability to interface with an ever-increasing number of development tools and resources make Maven a viable build solution for WAS deployment.