Perficient Portal Solutions Blog

Subscribe to RSS feed


Kevin StClair

Posts by this author: RSS

Maven and WebSphere Web Applications (Part 2)

The parent project of the multiple module web application uses the uses the <packaging>pom</packaging> tag and several <module> tags to indicate that it is controlling the build order of several artifacts. The control is provided through the reactor plugin.

The file structure that I use is:


The ear directory is empty  (except for pom.xml). The application.xml required for an EAR is generated by the was6 maven plugin. The directory structure of the web directory is not shown here but specified as the maven standard directory layout.

There are several fields in the various hidden control structures that must be internally consistent for the build and deploy to work. This is why I prefer to use a maven archetype (created yourself for your project team) project to generate web application projects from scratch. My experience in the field indicates that developers who copy and paste from existing projects often make mistakes which are very hard to diagnose.

These are the items that you need to address:

  • Provide unique namespace (groupId + artifactId) for ear and war modules that is predictable. I solve this by using parent groupId appended with .war or .ear for the child projects.
  • Ensure the parent/child relationship of the three pom.xml files through dependencies and parent references including the correct generated ids.
  • Ensure ibm-web-ext.xml and ibm-web-bnd.xml are included in the web module.
  • Ensure the .project and .classpath files include the correct RAD facets and library definitions for a maven project.
  • Ensure the parent pom.xml has a parent reference to a project that defines the required WAS dependencies (for proper compilation).

Maven and WebSphere Web Applications (Part 1)

Web Applications are WAR files that include java code and JSP files with a web.xml deployment descriptor that are intended to implement dynamic web functionality (as opposed to static web functionality which uses HTML files).

A portal team typically uses this packaging technique for the following artifacts:

  • Portal themes and skins
  • web services
  • iWidgets

WebSphere Approach for Web Applications

The WebSphere Application server only understands EAR files. EAR files are collections of WAR and JAR files with an application.xml deployment descriptor. Developers that come from a Tomcat or JBoss (or similar J2EE application server) background may be accustomed to performing a hot deploy that simply involves them placing a WAR or EAR file in a specific directory. The WebSphere deployment is more involved because of clustering and vendor extensions that provide more robust enterprise features.

Now let’s assume you are creating a Spring web service implementation for your business logic. RAD automatically creates an associated EAR project for your WAR project when you choose dynamic web application during the project creation wizard. The EAR file is deployed on the WebSphere_Portal server instance of the WebSphere Application Server that includes your portal application.

The EAR file can be placed on the server using several techniques:

  • administrative console (via the GUI)
  • wsadmin
  • RAD menus that add project to a local server configuration (technique used by many developers during coding/debugging)

The wsadmin approach is the obvious choice for scripting releases. The administrative console approach is a multiple screen wizard that forces developers to choose values for many vendor extensions and security configurations that are typically beyond the domain knowledge of a component developer.

Maven Approach for Web Applications

A best practice of maven is to follow the one artifact for each pom.xml convention. We have already seen that WebSphere expects an EAR file that contains a WAR file for a typical web application. The solution for this problem is to create a multiple module maven project that serves as the parent for the WAR and EAR files that are required.

The deployment of the EAR file is handled by the was6 maven plugin from codehaus. This plugin will require that your Continuous Integration (CI) server handling the deployments has a WebSphere Application Server installation on the same machine. This is required because the was6 plugin is a wrapper for the wsadmin client (which includes an IBM component that handles the secured communications with a remote WAS instance). The configuration of the was6 maven plugin always requires specifying a -DwasHome property value that points to the root of the WAS server installation. I am not aware of any set of JAR files that implement this functionality (unlike the xmlaccess tool discussed in my WebSphere Portal and Maven post that can be implemented by including jars as dependencies of your custom plugin).

Next up I will discuss the file structure of the project used for my proposed solution for web applications.

Next up: Maven and WebSphere Web Applications (Part 2)

The Portal URI Resolution Service

WebSphere Portal 6.0.1 introduced a capability called the URI resolution service or POC servlet  or the Resolver Framework depending on where you see it mentioned. The DeveloperWorks article called Accessing portal content with custom URLs is the most recent and informative post I have found describing this service.

This service was created to allow non-portal sites in your organization to link to your portal content (the acronym POC means Piece of Content). The service works by using the scheme portion of the URI to divert the request to a collection of handlers that use the chain of responsibility pattern to modify a Resolved object which ultimately communicates parameters to portal objects.

Some examples of where this concept is used include:

  • The JSR 286 Web Content Viewer uses POC URIs (prefixed with wcm:). The WCM web content pages work by selecting which page best fits the current content request.
  • The PageBuilder2 themes use this to implement dynamic content spots and many other items.
  • The Lotus Connections Portlets for WebSphere Portal also use POC URIs.
  • The iWidget/Mashup API concepts use this mechanism. In fact, all portlets in WPS 7.0 are wrapped with an iWidget interface via the PageBuilder2 theme.
  • The WebDAV mechanism uses POC URIs for resolving resource requests.

This service can also be used for a few use cases you may not expect:

  • You can create a dynamic web content pages implementation that improves on web content pages (which still require you to create individual portal pages that are configured to certain Site Areas or content folders).
  • You can implement an inter-portlet communication process to replace wires (which require you to create a wire definition through portal administration).

I am going to explore these concepts in more detail in future posts.

Finding Practical Code Samples

You can find examples of resolvers by searching for the plugin.xml files that register them. This unix example would give you a list of EAR files in your installedApps directory:


Release Management for WebSphere Portal

Releasing your portal project to a brand new environment can be a fairly large challenge.

I maintain the reason for the challenge is that there are so many tools and procedures required for this process. It is difficult to find somebody on your team that has deep administrative experience coupled with a development background so that communication with the developers can occur with maximum efficiency during the mad rush to production that many teams experience. There will often be one or more developers on the team who are only familiar with packaging and deploying these artifacts using RAD/Eclipse or some other Integrated Development Environment (IDE) toolset. I maintain that a release manager should struggle to maintain the maxim that nothing ever goes to production without a script.

Consider the fact that your portal project will require several of these tools for deployment:

Each one of these toolsets is feature rich and complicated. Your release manager generally has to rely on the reference material published in the various infocenters and the IBM forums that address questions in these areas. These tools also change at a fairly rapid pace. Finally some tools do not have remote execution capability (which makes automation from a single machine more difficult).

The most recent advice from IBM concerning this topic is published in a DeveloperWorks article named IBM WebSphere Portal Version 6.0 staging scenarios using ReleaseBuilder.

I want to draw attention to the WebSphere Portal artifacts not covered by ReleaseBuilder and Items that cannot be staged with ReleaseBuilder sections that contain 9 portal artifacts and 4 other items for a combined total of 13 items that are not addressed by the recommended strategy. The more recent Manual steps prior to using ReleaseBuilder lists 10 portal artifacts and 17 environment configurations for a combined total of 27 items that require attention. Now let’s analyze these lists to come up with a comprehensive strategy.

The checklists for portal artifacts differ by one because one list combines themes/skins while another lists them separately.

These additional portal artifacts are listed separately because I wish to classify them as security configurations that some portal teams may not need to be aware of. This category of items generally involves placing jar files in a specific location and registering them with the server through REP/REE custom properties.
  • custom user registry
  • credential vault adapters
  • custom credentials
  • JAAS login modules
The next list combines portal hosted artifacts and adds a few of my own categories based on newer capabilities of WPS 7.x:
  • wcm content – syndication OR export/import of content libraries
  • pzn rules – pznload
  • wcm jsp component files – wsadmin (package as WAR file and reference as contextPath;jspPath in WCM)
  • iWidgets – wsadmin AND ConfigEngine
  • WebSphere Portlet Factory (WPF) portlets – ant
I will start addressing all these items in a series of posts that aim to use maven and some Continuous Integration (CI) server like Hudson to automate and document this complicated topic.

WebSphere Portal and Maven (Part 6)

You use a parent pom.xml file that each portlet project inherits from to encapsulate your dependencies and maven plugin bindings. This keeps all this code out of sight from your portlet project.

This first code posting shows the plugin definition under a pluginManagement section. This section is used to create any dependencies used by the plugin itself:

				<!-- Needed for ANT scp task -->
				<!-- Needed for propertyregexp task -->
				<!-- END: Needed for propertyregexp task -->
				<!-- For XSLT transformations -->


WebSphere Portal and Maven (Part 5)

I recommend using a maven plugin to package your logic. The reason is that the ANT antcall and XSLT tasks require file inputs (and do not support URIs). When you package these file resources into a jar (as you do with a plugin) then you can extract them to the correct relative filesystem locations as part of your mojo startup code. That means you don’t require developers to place these files into the projects themselves. This also means that you control the distribution of these key files and can replace them all at once in a new maven plugin version without having to email everyone that uses your artifacts.

The following source code example represents a java class that performs the setup and execution of your deployment logic:


WebSphere Portal and Maven (Part 4)

So far you have a compiled portlet and an XSLT capable of producing an xmlaccess request input file based on your specific portlet.xml file.

Next you create an ANT script that is capable of submitting your request to the portal server. The script presented below diverges to distinguish between local portlet deployments (when you are deploying to a portal server on the same machine on which you are building) and remote portlet deployments (when you are deploying to a remote portal server). The divergence is because local portlet deployments do not require any copying of the generated WAR file. For remote deployments I use the ANT scp task to copy the WAR file to the remote machine.

I prefer the scp task because you can place the file into the ${wp_profile}/installableApps directory (which follows standard IBM practice). This method requires that you have a shell account on the remote machine with correct write privileges. I’ll admit that I have used the nexus/archiva snapshot repository URL as an input to the xmlaccess request when I didn’t have a shell account. This hack avoids the copying procedure, but I would avoid this method when possible because the logic to predict the URL is not as robust. You can plug any type of remote copying or URL based sharing method into this portion of the script.

The name of your web module in the wps admin console will default to ${artifactId}-${version}.war because that is derived from the filename of the deployed WAR file. Adjusting this would require some deeper level maven hacks that I like to avoid. However, the name of your web module in the AppServer admin console is under your control. I like to use ${MyCompany}_ as a prefix so that all your projects can be quickly filtered to distinguish them from the existing IBM modules.

Here is the ANT script:

<project default="install.local">
	<target name="install.local" depends="private.local.init, private.deploy" />
	<target name="install.remote" depends="private.remote.init, private.deploy" />

	<target name="private.local.init">
		<property name="file.url" value="file:///${basedir}/${project.artifactId}-${project.version}.war" />

	<target name="private.deploy">
		<!-- Step 1: Generate xmlaccess input from portlet.xml -->
		<echo message="Step 1: Generate xmlaccess request: target/deployme.xml" />
		<xslt in="../WebContent/WEB-INF/portlet.xml" out="deployme.xml" force="true" style="xmlaccess-input.xsl">
			<param name="WAR_URL" expression="${file.url}" />
			<param name="DISPLAY_NAME" expression="MyCompany_${project.artifactId}" />

		<!-- Step 2: Run the install/update xmlaccess script -->
		<!-- If the java process is forked then the CLASSPATH must be set  -->
		<echo message="Step 2: Deploying portlet using xmlaccess input: target/deployme.xml" />
		<java classname="" logError="true" resultproperty="xmlaccessReturnCode">
			<arg line="-in target/deployme.xml" />
			<arg line="-user ${wpsuser}" />
			<arg line="-password ${wpspassword}" />
			<arg line="-url http://${wpshost}:${wpsport}/${wpscontext}/config" />
			<arg line="-out target/output.xml" />

		<!-- Step 3: Determine result of deployment attempt -->
		<echo message="Step 3: Determine script result..." />
		<taskdef resource="net/sf/antcontrib/antlib.xml" />
				<equals arg1="${xmlaccessReturnCode}" arg2="0" />
				<length property="fileLength" file="output.xml" />
				<loadfile property="output.result" srcFile="output.xml" />
				<condition property="output.result" value="output.xml is empty">
					<equals arg1="${fileLength}" arg2="0" />
				<echo message="----- output.xml starts -----" />
				<echo message="----- output.xml ends ----/apps/IBM/Profiles-" />
				<fail message="Execution of deployme.xml Failed">
							<equals arg1="${xmlaccessReturnCode}" arg2="0" />
				<echo message="Execution of deployme.xml OK" />

	<!--Use SCP to copy the WAR file to the remote machine -->
	<target name="private.remote.init">
		<scp file="${project.artifactId}-${project.version}.war" todir="${scpuser}@${wpshost}:${remotedir}" password="${scppassword}" trust="true" />
		<property name="file.url" value="file:///${remotedir}/${project.artifactId}-${project.version}.war" />

The next post in the series will explain how the XSLT and and the ANT code is combined in a maven plugin to perform your portlet deployment.

Next up: WebSphere Portal and Maven (Part 5)


WebSphere Portal and Maven (Part 3)

The deployment of a portlet to a portal server is accomplished using xmlaccess (also called the XML configuration interface). At this point I need to point out that the deploy goal of maven is a separate concept from a portlet deployment. The maven deploy goal is intended to move your packaged maven artifact to the maven repository server. A portlet deployment means that you are moving and installing your portlet onto a portal server where it can be placed onto a page and receive requests.

You actually perform your portlet deployment during the pre-integeration-test phase of the maven lifecycle. This is done here instead of the deploy phase because you would not want to share the code with other developers if your integration tests fail during the integration-test phase.

The input file of an xmlaccess request is an XML configuration file with specialized syntax to describe your intended operation. You want to modify the DeployPortlet.xml sample file included in your portal installation and replace it with parameters that match the portlet you wish to deploy.

I have created an XSLT file that can process the portlet.xml descriptor and produce a valid xml configuration file that you can send in an xmlaccess request. Readers should notice that this is a modified form of the DeployPortlet.xml sample file included with the portal. In a future post I will describe how and where this file gets executed during the build.

<?xml version="1.0"?>

<xsl:output method="xml" indent="yes"/>
<xsl:param name="WAR_URL"/>
<xsl:param name="DISPLAY_NAME"/>

<xsl:template match="/">
	<xsl:comment>Generated version: 1.0</xsl:comment>
		<portal action="locate">

<xsl:template match="wps:portlet-app">
	<web-app action="update" active="true" uid="{@id}.webmod">
		<url><xsl:value-of select="$WAR_URL"/></url>
		<!-- Use the maven artifactId as the display name in the WAS console with a prefix to group together -->
		<display-name><xsl:value-of select="$DISPLAY_NAME"/></display-name>
		<servlet action="update" referenceid="{wps:portlet/wps:portlet-name}.servlet"/>
		<portlet-app action="update" uid="{@id}">
            <xsl:apply-templates select="wps:portlet"/>

<xsl:template match="wps:portlet">
	<portlet action="update" name="{wps:portlet-name}" />


Next up: WebSphere Portal and Maven (Part 4)

WebSphere Portal and Maven (Part 2)

This post assumes that you have installed an automated build stack (which consists of maven, a maven compatible repository server, and a continuous integration (CI) server). This post also assumes that you have installed and configured the m2eclipse plugin for your RAD/Eclipse IDE. The details of these installations are beyond the scope of this series of posts.

A maven repository is software (like archiva or nexus) that stores your dependencies in a single remote server. Corporate development shops often choose to maintain an internal repository server which mirrors the maven central repository. The internal repository offers greater control, security, and faster internal downloads. IBM does not publish the portal dependencies to the maven central repository. (You will find that the majority of open sources projects will publish to maven central).

Since IBM does not publish the portlet dependencies you need an internal repository for compiling portlets (unless you use the system dependency scope and a private repository, but I don’t think this approach is as maintainable in a team development setting.)

So what are your dependencies?

I have taken two approaches for figuring this out:

  1. Go into RAD and find the Project Build Path and examine the WebSphere Portal v7.0 library definition and copy all the jar names and locations. Upload all these files to your internal server. List all these files as provided scope dependencies in your project. I’ll admit I have done this before figuring out the next method.
  2. Locate the ${PortalServer}/doc/compile/portletapi_20.jar file and list this as a provided scope dependency.

What is the difference between these methods?

If I developed any bizarre classpath issues (like NoSuchMethodError) I would revert to the first method to ensure I was replicating the RAD wizard exactly.

You use the provided scope of maven because you want to compile your code using the jar but the actual implementation jars are provided by the portal server when you deploy the code to a running portal server. The following command deploys your dependency to a remote maven repository:

mvn deploy:deploy-file -DartifactId=portletapi20 -Dversion=7.0 -Dpackaging=jar -Dfile=portletapi_20.jar -DrepositoryId=${repnamehere} -Durl=${repurlhere}

You should note that all these parameter values were items thought up by you. I find that using artifactId=${name}.jar without the jar extension and using a version number to correspond to your WebSphere Portal Server (WPS) version help maintain the logical link between these jars and their source. Finally ${repnamehere} and ${repurlhere} are values that make sense at your organization.

I always create a parent maven project of type pom that each portlet project inherits from (the reasons for this will become clearer in future posts). This parent project links the dependency as:







At this point your portlet project can compile and will be packaged as a WAR file suitable for deployment on your portal server.

Next up: WebSphere Portal and Maven (Part 3)




WebSphere Portal and Maven

“Well it works on my machine” is the single most frustrating developer quote you will hear while working on a portal project. The open source world has experienced great success with automating builds and server deployments using apache maven and continuous integration (CI) servers like hudson, continuum, cruise control and others. Investing time in the beginning of your project to establish and use a build system provides several benefits:
  1. You get a precise deployment instructions by forcing deployment through scripts. Developers do not get to tweak things outside the process. You do not end up with one lead who does all the magic (and gets sick or goes on vacation like many of us other humans), or a series of differing answers from developers who each use their own methods.
  2. Deploying through scripts guarantees reliability and traceability for environments below production. The majority of your bugs should be found in these environments so diagnosing bugs becomes easier with tools like recent changes list and SCM commit comments exposed through the web interface of your CI server.
  3. The reports capability of maven allows leads and architects to catch integration and design issues sooner in the development cycle. (For example, CPD and PMD rules can look for import statements in layers of your architecture where they don’t belong, like importing java.sql.* in your UI layer when data access should be handled in the services layer).
  4. The continuous integration servers allow the quality assurance team to see where code is moving in real time so that they do not need to question developers about when versions are placed on different environments.
  5. Developers can check a single project out from SCM without needing a “magic workspace” of related dependencies because maven and the snapshot repository handles the dependencies.
The following series of posts will explain practical examples of maven and portal used at client sites.