Introduction

The build process for large portal projects is a very important and, often, underestimated task. Typical build process tasks include:

• Checking out components from a repository
• Compiling source code
• Replacing properties
• Automating testing
• Deploying components

The complexity of the deployment tasks increases as the number of subprojects in a project increases, and businesses often use Apache Ant as the tool of choice for automating these tasks. However, creating deployment tasks with Ant is more difficult when working with many deployment units. Even though the basic usage of Ant is very simple, issues such as the following can cause problems in larger J2EE projects that involve deploying large numbers of artifacts.

1. The build and deployment scripts get very complex over time, as new functionality is added.
2. Many similar tasks must be scripted separately because Ant lacks support for loops, inheritance, and conditional processing; therefore, build code is duplicated and is sometimes redundant.
3. The gap between daily or nightly build tasks and developer tasks for unit testing widens as complexity and customization is added. Sometimes it is not possible to build artifacts without doing a full build. For example, a central build script provides properties for subprojects. The subprojects, however, might not build stand-alone, because they are not aware of the properties that are provided during a full build.
4. Last but not least, deployment tasks performed with Ant do not include testing, by definition. This contradicts the desire to check your code quality on a daily basis.

Apache Maven offers a promising solution for these issues. Maven, which is fully compliant with Ant, uses different concepts to achieve the similar results. Ant can be seen as a scripting tool. Maven targets the project management aspect of software projects. It helps you perform all steps in the project lifecycle including build, deployment, test, report generation, and documentation. For an overview of Maven, see The Apache Maven project.

Maven has a very powerful plugin mechanism, however, many developers refrain from using Maven due to lack of experience, insufficient documentation, or perceived complexity.

This article shows how to perform daily builds with Maven, how to overcome some initial pitfalls, and how to set up a project infrastructure. The general project structure in Maven is already documented (see Resources); this article focuses on how to set up a typical IBM Rational Application Developer project structure. You walk through a complete example which covers the primary aspects of the build and deployment process. You see how to extract source from a version control system, build the source, deploy the resulting artifacts on IBM WebSphere Portal Server V5.1, and generate reports about the process. You can perform all these tasks from the command line (for example, using a batch job) or directly from the Rational Application Developer V6.0 workbench, using a Maven plugin.

The artifacts in the sample project include:

• A portlet project to be deployed on WebSphere Portal Server V5.1
• A library project to support the portlet project
• A simple project containing the files for the build and deployment process
• An EAR project to satisfy the J2EE validation of the IDE

Figure 1 shows these projects in the Rational Application Developer Resource perspective.

Back to top

Installing the software

The machine used for the example could be used for daily builds or as a developer's machine. You will be able to run Maven from the command line, as well as through the development environment using a plugin. Mevenide provides extensions to Rational Application Developer so you can run Maven tasks. For more information on Mevenide, see The Mevenide plugin.

You need to install the following components in order to run the examples:

• IBM Rational Application Developer V6.0 with WebSphere Portal Toolkit
• IBM WebSphere Portal Server V5.1
• Apache Maven 1.0.2
• Mevenide plugin for Eclipse 3.0
• A CVS Client, such as WinCVS

Install Rational Application Developer and WebSphere Portal on the same machine as described in the WebSphere Portal product documentation.

Install the CVS client on the machine that performs the build. If you have to authenticate against the version control system, make sure the client can handle .cvspass files. One CVS client that can handle these files is WinCVS. After you have successfully run the cvs login command (on the command line), you can find a file called .cvspass in your USER_HOME directory. This file will provide the credentials for further invocations of the cvs login command.

Install the Mevenide Plugin into Rational Application Developer. Although the plugin is not absolutely necessary, it helps with editing Maven-related files and running specific goals for certain build-steps.

To install Maven on a Microsoft® Windows® system:

1. Run the installer that comes with Maven.
2. Define the installation directory.
3. Let the installation run to completion.

After the installation has completed:

1. Define a JAVA_HOME variable that points to a Java™ installation directory. In testing the example, I set JAVA_HOME to the Java installation that comes with Application Developer:

   c:\apps\RAD60\runtimes\portal_base_v5\java\

   
   
2. Define a MAVEN_HOME variable that defines where you installed Maven. For example, I set MAVEN_HOME to:

   c:\apps\maven_1_0_2\

   
   

Back to top

Setting up the project

Next, look at the typical Rational Application Developer (hereafter called Application Developer) project setup. The main difference between this project and the standard Maven project is the folder layout. In the Maven default layout, subprojects are located in sub-folders of the main projects. The Application Developer workspace contains many projects at the same level, with one project as the central place for all build-related files. This can be the first pitfall when setting up Maven.

To import the sample code into the Application Developer workbench:

1. Download the attached ZIP file, and unzip it to some temporary directory.
2. Open Rational Application Developer in the Resource perspective.
3. Create a simple project named AddressBookDeployment. Select File => Import and import the contents of the AddressBookDeployment folder (from the extracted download) into this new project.
4. Create a portlet project called AddressBookPortlet. Do not choose to create a portlet. After the project is created, import the contents of the AddressBookPortlet folder (from the extracted download), and overwrite any existing files.
5. The Enterprise Application Project called AddressBookPortletEAR should have been created when the portlet project was created. (If not, create this EAR project manually). For this project, select File -> Import -> File System, and click Next. Choose the files from the AddressBookPortletEAR folder and import them into the workbench.
6. In the workspace, create a Java project called AddressBookLibraries. In the project settings, set JavaSource as a source folder, and build as the default output folder (see Figure 2). Again, select to import from the file system and import the Library project files from the AddressBookLibraries folder into the workbench.

After the setup is complete, your workspace should look like the sample workspace in Figure 1, and it should contain the files described in Figure 3.

The AddressBookDeployment project is the source for all build related activities. The project.xml, maven.xml and project.properties files define the basic layout of the build process. The fact that the same behaviour could be defined in any of these files can be confusing. For example, I set the source directory using this entry in project.xml:

<build>
       <sourceDirectory>${basedir}/JavaSource</sourceDirectory>
</build> 

You could also specify the source directory using the maven.build.src parameter in the project.properties file - the result is the same, no matter where you define the properties. The project.xml files in the other projects all extend the base project definition.

Table 1 describes some of the properties in project.properties that have been set to support this kind of project setup.

Table 1. Project setup properties

The main project.xml file in the AddressBookDeployment project contains the settings that apply to all projects, such as general project information or dependencies that apply to all projects. All local project.xml files can either override the properties set in the main project or they can define new or special settings for the individual sub-project.

For example, consider the setting for the *.class directory: The general setting is ${basedir}/build but in a web project. In the example, I want this value to be ${basedir}/WebContent/WEB-INF/classes, to comply with the Application Developer workspace settings and J2EE standards. Therefore, this property is overwritten in a local project.properties file.

Back to top

Refining the maven.xml file

The maven.xml file contains all task definitions that are specific to a particular project and that are not covered by the default functionality of maven plugins. The task definitions in Maven are called goals and can be viewed as equivalent of targets in Ant.

The more familiar you are with Maven, the smaller your maven.xml tends to be, because you learn how to use the built-in functionality. Initially, you might be inclined to write your tasks manually, just as you did in Ant. This is feasible, because you can use Ant scripts in Maven and you can extend these through the use of jelly constructs such as loops and conditions. In most cases, however, it is useful to check the capabilities of the plugins, because they might already have what you need.

In our example the maven.xml file contains the following goal definitions:

Because I want the example to be valid for more than one project of the same type, the portlet and library projects are defined as iterated comma-separated lists:

The tags used in maven.xml could be of various types referring to different plugins. For example, to use Ant you need a namespace definition (xmlns:ant="jelly:ant") and then all ant tasks can be executed by referring to the namespace prefix (<ant:exec executable="cvs">).

Back to top

Running Maven

For this example, you can run Maven either from the command line or from the workbench in Application Developer. The issue to consider here is which goals can be executed from which folder. You can run all aggregation goals (such as multiproject:site or the custom goals) from the folder containing the deployment project. You can also run single goals, such as jar or war goals, directly from the subproject's folder.

If you run Maven from the command line, Maven expects to find a project.xml definition in the current folder, similar to the way Ant expects to find a build.xml file.

The Mevenide plugin makes all goals available in an extra view, when the focus is on the maven.xml file. Alternatively, as shown in Figure 4, when you select a project.xml file, the goals are in a context menu in the project navigator view.

Back to top

Building the project

To perform a build, a goal called buildAll in the maven.xml file combines all functions that are needed for the build. It performs the jar and jar:install goals for library projects, and then performs the war goal on all portlet projects. The jar and war tasks build the appropriate artifacts with corresponding names, such as addressbookportlet.war. The jar:install task puts the jars into the local repository to be available for the build of the portlets.

Maven automatically compiles classes that have changed before packaging the artifacts, so you do not have to worry about this. As a comparison, building a jar in Ant would require the following steps:

1. Compile classes.
2. Copy properties to the destination directory.
3. Run the jar task in Ant.

Most of the most work in larger projects is typically spent on scripting these tasks for each project. This adds complexity because looping in Ant is tricky.

If a dependency to an open source library exists, Maven can download this library automatically. Because the IBM products are not available on the Web, the local dependencies must be defined. For the portlet project in the example, I defined the following dependencies in the local project.xml:

• portlet-api
• dynacache
• j2ee
• addressbooklibraries

For example, the portlet-api and dynacache dependencies cannot be satisfied from the open repository Maven initially contacts (they are part of the WebSphere Portal distribution), you must define these dependencies manually in the project.properties file of the deployment project.

In this case I defined a variable called wps.home to point to the shared library directory for the local WebSphere Portal installation:

wps.home=c:/apps/RAD60/runtimes/portal_v50/shared/app

We also defined a variable called maven.jar.portlet-api which defines the jar location relative to wps.home:

 maven.jar.wps = ${wps.home}/portlet-api.jar
 

Similarly, the j2ee jar has been set relative to a local WebSphere Application Server installation.

The addressbooklibraries dependency is satisfied, because this artefact is built from the AddressBookLibrary project, and through the execution of jar:install. This dependency is copied to the local Maven repository, and is therefore available for other projects, after jar:install has been executed.

Back to top

Deploying the project

The deployment of the sample project includes deploying shared libraries on WebSphere Portal, and then deploying the portlets. Before starting the automatic and daily deployment process, you need to define a directory as a shared library, and then register this library with the classloader of the application server WebSphere_Portal.

To define the shared library:

1. On the command line, in the config directory of the WebSphere Portal Server installation, run the command: wpsconfig start-admin-server.
2. After the start process has completed, access the WebSphere Administrative Console by opening the following in a Web browser:

   https://localhost:9043/admin/logon.jsp

   
   
3. Open Environment -> Shared libraries. Select localhost as node and WebSphere_Portal as server, and then click Apply.
4. Create a new shared library, assign a name and description, and select a directory as the classpath (such as c:\apps\RAD60\runtimes\shared_libs\ . For example, see Figure 5.
   Figure 5: Defining shared libraries for WebSphere Portal
   
   
5. Save the settings.
6. Now assign the shared library to the portal classloader:
   • In the console, open Servers => Application Servers=> WebSphere Portal. The portal server configuration displays.
   • Select classloader from the additional properties section, and select the classloader displayed here.
   • Open the Libraries section from the additional properties section and add a new shared library.
   • Select the library you created above, and save your settings.

You can now stop the administrative server because it is not needed anymore.

To deploy the shared libraries, a goal called deploySharedLibraries in the maven.xml file stops the server WebSphere_Portal, copies the shared libraries to the directory specified by the wps.shared.libs property, and starts the portal server again.

To deploy the portlets, the portlet project deployment folder contains two XMLAccess files: one for deploying and one for starting the portlet applications. You could use these files as models for deploying other portlet projects. You could copy and then edit the files to specify the appropriate settings for the of the new portlet projects (such as the name, uid, and filename). The deployPortlet goal in the maven.xml file deploys the generated portlet with the help of these two files. After you place your portlets on the pages in WebSphere Portal, these portlets are updated during the nightly build.

In addition to the single deployment goals, the maven.xml file defines a common deploy goal that runs the goals described above for all library and portlet projects.

Back to top

Reporting

One of most useful features of Maven is its ability to automatically run tests on the projects and to aggregate the test results into overview pages. This documentation can be directly deployed to a Web server so that all developers have the results of a nightly-build available in the morning.

The choice of reports to generate for each project depends on the settings in the global project.xml file:

<reports>
	...
	<report>maven-checkstyle-plugin</report>
	...
</reports> 

In our example, I include the following report definitions in the project setup:

Most of the reports are generated for each project. The multiproject and dashboard plugins combine the reports for the general overview in our deployment project. Those two plugins are the hardest to configure because the project structure is different from the default structure maven expects.

An overview page of the central project is displayed in Figure 6. The navigation has an entry for each subproject under the Projects header. Individual reports can be found in the Project Documentation section. Individual subproject reports (such as Junit) are important to the developers. The dashboard report for the deployment project is important for the project manager or the lead architect because it gives an overview of all project activities.

To set up the aggregated reports for the example, I defined the following properties in the global project.properties file:

maven.multiproject.basedir=${basedir}/../
maven.multiproject.excludes=AddressBookDeployment/project.xml
maven.multiproject.includes=*/project.xml
maven.multiproject.site.goals=site,dashboard:report-single

You define the base directory for multiprojects one level above each subproject, and you exclude the AddressBookDeployment project, because this is the top level project that is only relevant for aggregated results. To run the multiproject:site goal, the site goal and the dashboard:report-single goal run for each project.

Important: Exclude the AddressBookDeployment/project.xml. Including it can lead to an infinite loop when Maven iterates over subprojects and finds the main project again among the subprojects.

To aggregate the results in the dashboard view of the deployment project, some more properties are required in the project.properties file:

maven.dashboard.basedir=${basedir}/../
maven.dashboard.runreactor = false
maven.dashboard.rungoals = false
maven.dashboard.aggregators=
csall,csfiles,cserrors,cswarnings,junittests,juniterrors,junitfailures,junitpassrate,
pmdfiles,pmdviolations,tasklistclass,tasklistmethod,tasklist
maven.dashboard.includes=*/project.xml

The maven.dashboard.basedir property specifies where to start to the dashboard task--in this case one level up from the deployment project. The maven.dashboard.aggregators property defines which types of reports are to be aggregated in the dashboard view.

You can access individual project reports through the Projects navigation in the main view. An example of a detailed report is displayed in Figure 7, which is the JUnit view of the detailed report. This report gives details about all JUnit tests that were run for this individual project and their results.

To generate this project documentation just, open a command window and navigate to the AddressBookDeployment directory of the workbench. Run the maven multiproject:site command, which generates the reports on all projects and, similar to the jar generation, runs all tasks that are required before generating the reports, such as compiling classes, unit test classes, and then running unit tests.

After all documentation has been generated, the documentation can be accessed at ${maven.build.dir}/AdressBookDeployment/docs/index.html. The deployDocumentation goal, defined in maven.xml, copies all files to the directory of a Web server. The documentation can now be accessed by any team member in a Web browser.

Back to top

Defining the nightly-build goal

The nightly-build goal in the sample maven.xml file runs all goals described. You can configure the running of the maven nightly-build as a scheduled task on Windows or as a cronjob on UNIX-like systems.

This goal performs the following steps:

1. Update sources from cvs.
2. Build and deploy all artifacts to WebSphere Portal.
3. Generate the documentation Web server.

Back to top

Conclusion

Through its rich set of plugins that are already available, Maven is an amazing tool for all build-related activities that need automated tasks. Because it also includes Ant as a plugin, it should be a moderate effort to migrate build procedures from Ant to Maven. Maven’s ability to run tests and generate reports is a very useful feature to implement quality assurance and automated testing in J2EE projects, and can be a big help for build processes.

One drawback when using Maven is the fact that Maven is not yet extensively documented; therefore, the usage of Maven in critical projects still needs some evaluation. In addition, Maven support is primarily available only through mailing lists. This form of support can be a risk for big project. However, the overall picture of Maven suggests that this tool will be used in more and more projects in the future and the community will grow fast.

Back to top

Download

Description	Name	Size	Download method
Code samples in zip format	0503_boog-maven-examples.zip	26KB	FTP|HTTP

Information about download methods

Resources

• For a brief introduction to Maven, read Project management: Maven makes it easy.
  
  
• The Apache Maven project is the main site for information on and access to Maven code.
  
  
• For an overview of Mevenide, and to download the plugin, see Mevenide Master.
  
  
• Maven Magic provides an overview of Maven and differentiates it from Ant.
  
  
• WebSphere Portal product documentation provides access to all the latest product documentation for all versions and editions of WebSphere Portal.
  
  
• WebSphere Portal zone provides an ever-growing collection of technical resources related to WebSphere Portal.
  
  
• The Rational Application Developer area on developerWorks includes a wide variety of technical materials for Java developers who want to use this IBM development environment.
  
  

About the author

Hinrich Boog is an IT Specialist in the IBM e-business Innovation Center in Hamburg, Germany, where he is engaged in architecture, development and operational aspects of enterprise portal and content management projects across EMEA. He holds a masters degree in Computer Science from Freie Universität Berlin and is currently pursuing a master's degree in Total Quality Management at Universität Kaiserslautern.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Installing the software
• Setting up the project
• Refining the maven.xml file
• Running Maven
• Building the project
• Deploying the project
• Reporting
• Defining the nightly-build goal
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Rational Application Developer for WebSphere Software
• Buy: Rational Application Developer for WebSphere Software

Dig deeper into WebSphere on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers