Maven integration for portlet projects with IBM Rational Application Developer

The Apache Maven framework, which helps automate the build process, has become more popular as developers focus on duplicating and reusing commands. IBM® Rational® Application Developer for WebSphere Software v9.0 introduces tooling support for Maven-based development. This article explains how Maven tooling can be integrated with Rational Application Developer's portlet tooling features to enhance both the development and the build experience.

Manish Aneja (mananeja@in.ibm.com), Project Lead, IBM

author photoManish Aneja is the project lead for the IBM Rational Application Developer – Portal Tools in the IBM Collaboration Solutions (ICS) group. In addition, he is experienced with agile development practices and automation for reliability and functionality testing. He has published several articles on the developerWorks Rational Application Developer wiki.



Awanish Kumar Singh (awansing@in.ibm.com), Software Engineer, IBM

author photoAwanish Kumar Singh is a software developer for the IBM Rational Application Developer – Portal Toolkit at the IBM India Software Labs, Gurgaon. He has experience in plug-in development, test automation, and automation frameworks. He has published several articles on developerWorks.



24 September 2013

Also available in Chinese

Apache Maven promotes quality and productivity by providing uniformity to a project's build infrastructure and clarity in using and applying the build best practices. The Maven framework primarily helps with build automation by simplifying multiple build requirements and standards into a common, flexible system that can be learned once and deployed across multiple projects.

Maven has become popular as developers move away from writing customized Apache Ant scripts to building Maven commands that can be duplicated and reused. Implementing a new build process using an organization's established standards is always cumbersome, and customized build scripts do not allow resource sharing across projects. Maven solves many of these problems by using standardized dependency management, artifact repositories, adapters connecting to external source code management, test systems, build technologies, and project schemes and archetype structures, which are templates containing static artifacts used as original patterns or models.

IBM® Rational® Application Developer for WebSphere Software, an integrated development environment, has introduced tooling support for Maven-based development. Rational Application Developer offers enriched tooling features such as project creation wizards, editors (Page Designer, Rich Page Editor), runtime test environments, and publishing support. Maven developers can use these features to enhance their development experience and productivity, and Rational Application Developer developers can use Maven capabilities and practices to streamline development and build lifecycle management.

This article shows how you can:

  • Populate the local Maven repository with runtime libraries
  • Create a portlet project using the IBM archetype
  • Publish the project to IBM® WebSphere® Portal Server using the Maven plugin
  • Convert an existing portlet project to a Maven configuration

Create a Maven-based portlet project

You can create a Maven-based portlet project in Rational Application Developer in two ways: Use the IBM archetype for portlet project creation, which is available at the IBM public repository for Maven (see Resources), or create the portlet project in Rational Application Developer using the portlet creation wizard, and then convert the Rational Application Developer portlet project to a Maven-based configuration. To deploy a portlet project on WebSphere Portal Server, you can use the IBM deployment plugin, which is also available on the IBM public repository. Figure 1 illustrates creation of a portlet project with the Maven tooling in Rational Application Developer:

Figure 1. Maven tooling in Rational Application Developer for portlet development
Create a portlet project with Maven tooling

The install and target project object models (POMs)

Dependencies for an application are uniquely specified in its pom.xml configuration file using the groupId, artifactId, and version parameters. To ensure that a Maven-based portlet project compiles, the libraries referenced in projects should be available in the Maven repository.

pom.xml files known as install POMs for WebSphere Portal Server and IBM® WebSphere® Application Server runtimes are available from the IBM public repository. Install POMs copy public libraries from server installations to the local Maven repository. In addition, target POMs add these runtime public libraries to the portlet project classpath for compilation. Target POMs can be used as a dependency in Maven projects. Figure 2 illustrates the use of install and target POMs in a Maven-based project:

Figure 2. Using install POM and target POM
Install and target POMs in a Maven-based project

There is one-to-one mapping of the required JAR files or libraries in target and install POMs. For a portlet project created using an IBM archetype, target POMs are added as a dependency in the project's pom.xml file by default. For portlet projects converted to a Maven configuration, you must manually add WebSphere Portal Server and WebSphere Application Server target POMs as dependencies. Using install POMs is a one-time activity for a local Maven repository.

Populating the server libraries to the local Maven repository

To install public libraries that are provided by server runtimes to a local Maven repository using install POM, follow these steps:

  1. Open Rational Application Developer in a new workspace, or use an existing one.
  2. To create a new Maven build run configuration, go to Run > Run Configurations....
  3. In the Run Configurations dialog, select the Maven Build option.
  4. Click New in the context menu. A New Run Configuration section opens, as shown in Figure 3:
Figure 3. Installing public libraries
Run configuration dialog to use for installing a POM

Populating the local Maven repository with WebSphere Portal Server runtime libraries

To install public libraries from WebSphere Portal Server to the local Maven repository:

  1. Enter the name in the Name field.
  2. Set the Base directory with RAD install directory/plugins/com.ibm.etools.portal.server.tools.common.core/resources/scripts/Portal 8 plugins.
  3. Type install in the Goals field.
  4. In the Parameters section, click Add to set the parameter name serverInstallationFolder. To set the parameter value, use the path of the WebSphere Portal installation folder (for example, C:/IBM/WebSphere/WP80x/PortalServer)
  5. Apply the changes and Run the configuration.

Populating the local Maven repository with WebSphere Application Server runtime libraries

WebSphere Portal Server is installed on top of WebSphere Application Server, so the portlet project also references public APIs from WebSphere Application Server. You also need those libraries in the local Maven repository to compile the portlet project successfully.

Use the Run Configuration as shown in Figure 3 to install public libraries from WebSphere Application Server to the local Maven repository, following these steps:

  1. Input the configuration Name.
  2. Set the Base directory with RAD install directory/plugins/com.ibm.etools.maven.javaee.core/resources/scripts/WAS 8 plugins.
  3. Enter install in the Goals field.
  4. In the Parameters section, click Add to set the parameter name serverInstallationFolder. To set the parameter value, use the path of the WebSphere Application Server installation folder (C:/IBM/WebSphere/AppServer).
  5. Apply the changes and Run the configuration.

Portlet project creation using the IBM archetype

Now you're all set to create a portlet project using the IBM archetype. Archetypes help you work efficiently because they make replicating best practices or organizational templates easier. The IBM archetype (portletapp-portlet20) for portlet projects is available on the IBM public repository for Maven. You can use this IBM archetype to generate a JSR 286 portlet project targeting WebSphere Portal Server v8.0. Follow these steps to create a portlet project using the IBM archetype:

  1. Go to File > New > Project....
  2. Select Maven > Maven Project.
  3. Click Next on the New Project dialog. The New Maven Project Wizard starts.
  4. Accept the default values on the first page of the wizard and click Next.
  5. On the Select an Archetype page, select All Catalogs in the Catalog drop-down.
  6. Enter portlet20 in the Filter text field. An IBM archetype with a Group Id of com.ibm.tools.archetype, an Artifact Id with the choice portletapp-portlet20, and a Version of 1.0 are listed in the archetype table.
  7. Select the IBM archetype portletapp-portlet20 and click Next. The result is the dialog shown in Figure 4.
Figure 4. Portlet project created using the IBM archetype
Creation of portlet project using IBM archetype

Now all you have to do is enter the sample values. For Group Id, enter com.test.demo. For Artifact Id, portlettitle, and portletclass, enter MyLatestPortlet. Click Finish.

A portlet project is created in the workspace. Figure 5 shows the project's tree structure.

Figure 5. Portlet project tree structure
Sample tree structure for the new project

Go to the Maven Dependencies tree node and expand it. Notice, as shown in Figure 6, that the JAR files from WebSphere Portal Server and WebSphere Application Server are added in the portlet project classpath, which you'll use for the compilation of the portlet project.

Figure 6. Public JAR files are added in the portlet project classpath
List of JAR files added to the project classpath

Now open the pom.xml file of the portlet project and go to the Dependencies tab. In the Dependencies section you see the entry of the target POM for WebSphere Portal Server and WebSphere Application Server. The source view of pom.xml resembles Listing 1.

Listing 1. Target POM as a dependency in pom.xml
<dependencies>
    <dependency>
        <groupId>com.ibm.tools.target</groupId>
        <artifactId>was</artifactId>
        <version>8.0.0</version>
        <type>pom</type>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>com.ibm.tools.target</groupId>
        <artifactId>portal</artifactId>
        <version>8.0.0</version>
        <type>pom</type>
        <scope>provided</scope>
    </dependency>
<dependencies>

Publish the portlet project to WebSphere Portal server using the Maven plugin

Deployment in an integration or release environment copies the final package to the remote repository for sharing with other developers and projects. Rational Application Developer tooling for WebSphere Portal provides a deployment plugin that can be used to publish your portlet project to the server. The IBM deployment plugin is available from the IBM public repository.

To publish a portlet on the WebSphere Portal Server, first open the pom.xml of the created portlet. Then, in the <build><plugins></plugins></build> tag, copy the code contained in Listing 2.

Listing 2. Code to add to the deployment plugin
<plugin>
    <groupId>com.ibm.tools.plugin</groupId>
    <artifactId>portal-deployment-maven-plugin</artifactId>
    <version>1.0</version>
    <executions>
        <execution>
            <phase>integration-test</phase>
            <goals>
                <goal>deploy-portlet</goal>
            </goals>
        </execution>
    </executions>
</plugin>

If you want to target a remote portal server or customize certain settings, you can do so in the <configuration> tag by providing the desired configuration parameters of the IBM portal deployment plugin, shown in Listing 3.

Listing 3. Configuration parameters of the deployment plugin
file  <file></file>
/**
 * The module file which will be deployed.
 * @parameter expression="${deploy-portlet.file}" default-value=
 * "${project.build.directory}/${project.build.finalName}.$
 * {project.packaging}"
 * @required
 */

username  <username></username>
/**
 * The username of the portal
 * @parameter expression="${deploy-portlet.username}"
 * default-value="wpsadmin"
 * @required
 */

password  <password></password>
/**
 * The password of the portal
 * @parameter expression="${deploy-portlet.password}"
 * default-value="wpsadmin"
 * @required
 */

hostname  <hostname></hostname>
/**
 * The hostname of machine on which portal installed
 * @parameter expression="${deploy-portlet.hostname}"
 * default-value="localhost"
 * @required
 */

port<port></port>
/**
 * The port which will be used for the deployment
 * @parameter expression="${deploy-portlet.port}" default-value="10039"
 * @required
 */


contextroot  <contextroot></contextroot>
/**
 * The context root of the portal
 * @parameter expression="${deploy-portlet.contextroot}" default-value="wps"
 * @required
 */

scheme  <scheme></scheme>
/**
 * The scheme which will be used for the deployment
 * @parameter expression="${deploy-portlet.scheme}" default-value="http"
 * For now only http scheme is supported in this plugin
 * @required
 */

profilepath  <profilepath></profilepath>
/**
 * The path of the WebSphere Portal profile, required in case of EAR
 * deployment
 * @parameter expression="${deploy-portlet.profilepath}"
 */

cell  <cell></cell>
/**
 * The cell which will be used for the deployment, required in case of EAR
 * deployment
 * @parameter expression="${deploy-portlet.cell}"
 */

You can check the default values of the configuration parameters using content assist. Listing 4 shows how the snippet in pom.xml appears if you use the configuration parameters.

Listing 4. Deployment plugin with configuration parameters
<plugin>
      <groupId>com.ibm.tools.plugin</groupId>
      <artifactId>portal-deployment-maven-plugin</artifactId>
      <version>1.0</version>
      <executions>
	  <execution>
	    <phase>integration-test</phase>
          <configuration>
	   <username>wpsadmin</username>
	   <password>wpsadmin</password>
	   <hostname>localhost</hostname>
	   <port>10039</port>
	   <profilepath>C:\IBM\WP80\wp_profile</profilepath>
	   <cell>awan</cell>
          </configuration>
	    <goals>
	   <goal>deploy-portlet</goal>
	    </goals>
	  </execution>
      </executions>
 </plugin>

Now that you have added the reference of the Maven deployment plugin in your pom.xml, go to Maven > Update project.... In the project's context menu, update the project configuration per the updated values in the pom.xml.

To publish the project to the server, select the project and, from its context menu, select Run As > Maven Build.... In the Goal field, type integration-test. Click Run.

Maven execution starts, and you can see the execution logs in the console. After it finishes, check the BUILD SUCCESS message at the end of the log in the console. You will also see the message:

[main] INFO com.ibm.portal.mvn.plugin.DeployPortletPlugin  - 
Portlets are successfully deployed on portal server

Verify that the portlet is deployed to WebSphere Portal Server by searching for it in the portal administrator console. You can check how it's rendered by placing the portlet in a portal page.

Convert a Rational Application Developer portlet project to a Maven project

So far you learned how you can use the Maven tooling options provided for portlet project scenarios in Rational Application Developer. You can also convert a Rational Application Developer portlet project to Maven project. This method provides advanced tooling features such as close integration with target portal runtimes, WYSIWYG editors, and drag and drop of Dojo and jQuery widgets and events.

Set up the workspace

You need to set your workspace level preferences to map the normal Java EE preferences to Maven settings. To do so:

  1. Go to Window > Preferences.
  2. Select Java EE > Maven > Maven Project Settings.
  3. Click Set all Maven values on the Maven Project Settings page.
  4. Click Apply.
  5. Select Java EE > Project.
  6. Uncheck Add Project to the EAR file check box on the Project page.
  7. Click OK.

Figure 7 shows how to establish your Maven settings.

Figure 7: Apply maven project settings
Map normal Java EE preferences to Maven settings

To create the portlet project in Rational Application Developer:

  1. Go to File > New... > Project....
  2. In the New Project wizard, select Portlet project.
  3. Click Next.
  4. Enter a portlet project name, and select WebSphere portal v8.0 as target runtime.
  5. Click Modify in the configuration section.
  6. Select JSR286 as the portlet API and Basic portlet as the portlet type.
  7. Finish the wizard.

A new portlet project is created and displayed in the Enterprise Explorer view.

Note: When you finish the wizard, you might see a dialog notification regarding a change of perspective. If so, select No, because you intend to use the Maven configuration.

Converting to the Maven configuration

Now you're ready to convert to the Maven configuration. To do so:

  1. Right-click the portlet project you just created to launch its context menu.
  2. Select Configure > Convert to Maven Project. A Create new POM wizard dialog displays.
  3. Select war in Packaging.
  4. Finish the wizard.

You might get some compilation errors after conversion, because the runtime classpath becomes empty. That's because the JAR files required for project compilation are missing in the portlet project classpath. To resolve this issue, you need to add the target POM as dependencies to the pom.xml of the portlet project. These targets POMs are available at IBM public repository.

To add the target POM as dependencies:

  1. Open the pom.xml of the portlet project.
  2. Click the Dependencies tab.
  3. Click Add in the Dependencies section.
  4. Enter com.ibm.tools.target in the Filter field. The Select Dependency dialog opens.
  5. Add com.ibm.tools.target portal 8.0.0 POM and com.ibm.tools.target was 8.0.0 POM as dependencies.
  6. Save pom.xml.

Figure 8 shows the Select Dependency dialog.

Figure 8. Adding POMs as dependencies
The Select Dependency dialog

Ensure that the scope of the dependencies is provided. Listing 5 shows what the dependencies in the POM look like:

Listing 5. Target POMs as dependencies
<dependencies>
    <dependency>
        <groupId>com.ibm.tools.target</groupId>
        <artifactId>was</artifactId>
        <version>8.0.0</version>
        <type>pom</type>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>com.ibm.tools.target</groupId>
        <artifactId>portal</artifactId>
        <version>8.0.0</version>
        <type>pom</type>
        <scope>provided</scope>
    </dependency>
</dependencies>

Select Maven > Update Project from the portlet project's context menu in the Enterprise Explorer view. After the update completes, you should have no errors in the Problems view or the Marker view, and the WebSphere Portal Server public libraries should be added in the portlet project's Maven classpath.


Conclusion

Maven integration helps developers follow build and development best practices, and this article provided an overview of how to enable Maven support for portlet projects. It showed how the local Maven repository can be populated with runtime libraries. It also showed how you can create a portlet project using the IBM Maven portlet archetype and how it can be published to WebSphere Portal Server using a Maven-based deployment plugin. Finally, you learned how to convert a Rational Application Developer portlet project to a Maven configuration.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=946058
ArticleTitle=Maven integration for portlet projects with IBM Rational Application Developer
publish-date=09242013