Integrating m2eclipse-wtp with IBM Rational Application Developer for Portlet Development

This is a walkthrough for integrating Maven with IBM Rational Application Developer for portlet development using m2eclipse-wtp.

Step 1 - Install IBM Rational Application Developer V8.0.4

Refer my previous notes - Setup a Portlet Development Environment With IBM Rational Application Developer 8

Step 2 - Install m2eclipse-wtp release 1.0.100

1) In RAD open the menu Window - Preferences - Install/Update - Available Software Sites, enable sites listed below,

* http://download.eclipse.org/eclipse/updates/3.6
* http://download.eclipse.org/webtools/repository/helios

2) In RAD open the menu Help -> Install New Software, add this new location:

http://download.jboss.org/jbosstools/updates/m2eclipse-wtp

and select the following check boxes:

* Maven Integration for Eclipse
* Maven Integration for WTP
* Expand Maven Integration for Eclipse Extras folder and select only m2e connector for maven archiver pom properties

Step 3 - Install m2e connectors for software configuration management (SCM)

In my case SVN is used as SCM, I first installed Subclipse V1.6.X from update site http://subclipse.tigris.org/update_1.6.x, then in RAD open the menu Window - Preferences - Maven - Discovery, click the Open Catalog button, and select/install the m2e-subclipse connector.

Step 4 - Setup Java EE and Maven preference

1)In RAD open the menu Window - Preferences - Java EE - Project, uncheck the "Add project to an EAR" checkbox.

2)In RAD open the menu Window - Preferences - Maven - WTP integration, uncheck the "Generate application.xml under the build directory" checkbox.

Step 5 - Add Maven projects into RAD workspace

Use RAD "Checkout Maven projects from SCM" or "Import Existing Maven Projects" wizard to add your Maven projects into RAD workspace.

In my demo project, I have a Maven project that consists of three modules: core, webapp and ear. When the projects are imported into RAD, the m2eclipse-wtp plugin apply appropriate facets to the projects based on the maven project types

Step 6 - Setup EAR project properties

This step is important to use RAD Portlet development features include debug/run on server, and edit WAS deployment descriptor.

1) Right click the ear project and select Properties - Project Facets, select the "Websphere Application(Co-existence)" and the "Websphere Application(Extended)" checkboxes, change the version based on your WAS server version

2) Right click the ear project and select Properties - Targeted Runtimes, select the "Websphere Portal" checkbox.

Congratulations! now you have set up a Maevn based portlet development environment in RAD.

Issues and Solutions

Issue - The EAR project popup menu doesn't show the option Open WebSphere Application Deployment

Solution - ensure in the ear module POM file, the maven-ear-plugin/configuration/version property is set to 5 or up.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-ear-plugin</artifactId>
  <version>2.6</version>
  <configuration>
    <!-- generate application.xml version 5, to enable RAD to edit WAS deployment descriptor -->
    <version>5</version>  
    <modules>
      <webModule>
        <groupId>${project.groupId}</groupId>
        <artifactId>demo-webapp</artifactId>
        <contextRoot>MavenDemoPortlet</contextRoot>
      </webModule>
    </modules>
  </configuration>
</plugin>

Issue - Open WebSphere Application Deployment for the EAR project shows error Could not open the editor: An unexpected exception was thrown.

Solution - check the ear project settings/org.eclipse.wst.common.component file, ensure the deploy-name attribute of wb-module has the same value as the Eclipse project name. This can be achieved by two different ways.

1) In ear module POM file, add the build/finalName property, and set the value as the ear module artifactId,

<build>
  <!-- 
    same as the artifactId, which is the RAD project name, and also the    
    deploy-name defined in settings/org.eclipse.wst.common.component    
  -->
  <finalName>demo-ear</finalName>
  ...
</build>

2) During the project import, use the [artifactId]-[version] Name template in Advanced setting.

Issue - Run/Debug the portlet on Server shows error EJPPG0024I: Web application with context root XXX is deployed in the application server but not registered with portal.

Solution - check the webapp project settings/org.eclipse.wst.common.component file, ensure the context-root property of wb-module has the same value as the contextRoot defined in the ear maven-ear-plugin. If they are different, either update the ear POM file, or set the m2eclipse.wtp.contextRoot or the build/finalNameproperty in webapp module POM to update the webapp project settings/org.eclipse.wst.common.component file.

<properties>
  <!-- this must be same as the contextRoot defined in the ear module-->
  <m2eclipse.wtp.contextRoot>MavenDemoPortlet</m2eclipse.wtp.contextRoot>
</properties>

Maven substitution and Freemarker template

If you're using Freemarker template in Maven projects, double check to be sure your templates are not alerted by Maven filtering during build process.

During Maven build, the Maven filtering process will scan all resources for property references surrounded by ${ and }. When it finds these references it will replace them with the appropriate value. If any Freemarker templates are in Maven resource directory (e.g. src/main/resources), and contains Freemarker variable names (surrounded by ${ and } as well) that are also maven property names, then these references will be replaced with maven property values.

An example is shown in below

<tr>
  <td class="label">Name:</td>
  <td>${name}</td>
</tr>

Where the ${name} variable is meant to a Freemarker variable name and should be replaced during application runtime using model values, however, during Maven build, it is replaced to the Maven project name and the final package file will have the template file with the variable substituted, as shown in below.

<tr>
  <td class="label">Name:</td>
  <td>My Maven project</td>
</tr>

Simple way to fix this is to use a different variable name that maven doesn't aware, or a better way is to disable the maven filtering for all Freemarker template files in the pom file. In order to do so, you need to declare two mutually exclusive resource sets, the first resource set execludes Freemark templates from the filtering, and the other resource set copies Freemark templates unaltered, as shown in below.

<resources>
  <resource>
    <directory>src/main/resources</directory>
    <filtering>true</filtering>
    <excludes>
      <exclude>**/*.ftl</exclude>
    </excludes>
  </resource>
  <resource>
    <directory>src/main/resources</directory>
    <filtering>false</filtering>
    <includes>
      <include>**/*.ftl</include>
    </includes>
  </resource>
</resources>