Chapter 22. Portlet Development

The Red Hat JBoss Portal (JBoss Portal) interface is fully customizable with applications called portlets. Application development can be done by using the plain Portlet specification JSR-286. It is also possible to use the JBoss Portlet Bridge to write applications with JavaServerFaces (JSF), RichFaces or Seam.
Learn how to set up your project in a robust and effective way by using the JBoss Portal Bill of Materials (BOM).

22.1. Starting a Portlet Project

The Red Hat JBoss Portal (JBoss Portal) interface is fully customizable with applications called portlets. Application development can be done by using the plain Portlet specification JSR-286. It is also possible to use the JBoss Portlet Bridge to write applications with JavaServerFaces (JSF), RichFaces or Seam.
Learn how to set up your project in a robust and effective way by using the JBoss Portal Bill of Materials (BOM).

22.1.1. The Bill of Materials (BOM) Concept

To make managing dependencies easier, the BOM needed for developing typical portlet applications is available. The BOM is a Maven pom.xml file which specifies the versions of dependencies compatible with or provided by the Red Hat JBoss Portal (JBoss Portal).

Note

The JBoss Portal BOM is closely tied to JBoss EAP for maximum compatibility with the Red Hat JBoss Middleware stack.

22.1.2. Using the BOM

Below is the pom.xml file from the "Simplest Hello World" example portlet. This file contains all the necessary details.
In the <dependencyManagement> section, it declares gatein-3.5-bom as a <dependency> with import as the defined <scope>.
It indicates that the dependency will de facto be replaced with the dependencies in its dependencyManagement section.
As a result it is possible to declare the javax.portlet:portlet-api dependency in the <dependencies> section of the "Simplest Hello World" pom.xml, without specifying its <version>, <type> or <scope>. All of those parameters are managed by gatein-3.5-bom.

Example 22.1. Simplest Hello World Portlet


<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>

<artifactId>simplest-hello-world-portlet</artifactId>
<groupId>org.gatein.portal.quickstarts</groupId>
<name>Simplest Hello World Portlet</name>
<version>3.5.0.Final</version>
<packaging>war</packaging>
<description>The very essence of every possible portlet.</description>
<url>http://www.gatein.org</url>
<licenses>
    <license>
        <name>Apache License, Version 2.0</name>
        <distribution>repo</distribution>
        <url>http://www.apache.org/licenses/LICENSE-2.0.html</url>
    </license>
</licenses>

<properties>
    <!-- GateIn Bill of Materials (BOM) version -->
    <org.jboss.bom.gatein-bom.version>1.0.0.Final</org.jboss.bom.gatein-bom.version>
    
    <!-- Plugin versions and settings -->
    <jboss.as.plugin.version>7.1.1.Final</jboss.as.plugin.version>
    <!-- maven-compiler-plugin -->
    <maven.compiler.plugin.version>2.5.1</maven.compiler.plugin.version>
    <maven.compiler.target>1.6</maven.compiler.target>
    <maven.compiler.source>1.6</maven.compiler.source>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<dependencyManagement>
    <dependencies>
        <!--
            Define the version of JBoss Portal we build for. In its dependencyManagement,
            JBoss Portal Bill of Materials (BOM) specifies the versions, types and scopes
            of dependencies which are granted to be compatible with (or indeed in many cases
            provided by) JBoss Portal.
        -->
        <dependency>
            <groupId>org.jboss.bom</groupId>
            <artifactId>gatein-3.5-bom</artifactId>
            <version>${org.jboss.bom.gatein-bom.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- 
        The versions, scopes and types of these dependencies are managed in gatein-*-bom.
        You need to name only groupId and artifactId here.
        Name only those artifacts you refer to in your code.
        Look at gatein-*-bom POM file for the complete list of available artifacts.
    -->
    <dependency>
        <groupId>javax.portlet</groupId>
        <artifactId>portlet-api</artifactId>
    </dependency>
</dependencies>

<build>
    <finalName>${project.artifactId}</finalName>
    <plugins>
        <plugin>
            <groupId>org.jboss.as.plugins</groupId>
            <artifactId>jboss-as-maven-plugin</artifactId>
            <version>${jboss.as.plugin.version}</version>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>${maven.compiler.plugin.version}</version>
            <configuration>
                <source>${maven.compiler.source}</source>
                <target>${maven.compiler.target}</target>
            </configuration>
        </plugin>
    </plugins>
</build>

</project>
Further steps, after you have set up the pom.xml file for your project, depend on the technology you have chosen for writing portlets.

22.2. Building and Deploying Portlets

  1. Ensure that the instance of your JBoss Portal is running.
  2. Open a command line and navigate to the root directory of your portlet project.
  3. Type this command to build and deploy the archive: mvn clean package jboss-as:deploy
To deploy to other than default localhost:9999 JBoss instance, copy the following configuration just after <version>${jboss.as.plugin.version}</version> in the pom.xml file and adjust it to suit your needs. Note that <username> and <password> elements can be omitted sometimes, depending on your JBoss security settings.
<configuration>
    <hostname>127.0.0.1</hostname>
    <port>9999</port>
    <username>admin</username>
    <password>secret</password>
</configuration>
This will deploy target/simplest-hello-world-portlet.war to the running instance of the portal.

22.3. Standard Portlet Development (JSR-286)

Note

For an introduction to Portlet development, see Section 21.1, “JSR-168 and JSR-286 overview”
JSR-286 information is available from the Java Community Process Program located at: http://jcp.org/en/jsr/detail?id=286.

22.3.1. Java Configuration

After configuring the Maven pom.xml file, continue implementing a basic JSR-286 compatible portlet. An example of such a portlet is contained in the portal Quickstart "Simplest Hello World Portlet"

Example 22.2. SimplestHelloWorldPortlet.java


package org.jboss.portal.portlet.samples;

import java.io.IOException;
import java.io.PrintWriter;

import javax.portlet.GenericPortlet;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;

/**
* The simplest posible Portlet.
* 
* @author Peter Palaga
*/
public class SimplestHelloWorldPortlet extends GenericPortlet {
/**
 * Serves the VIEW mode. Writes "Hello World !" to the response writer.
 * 
 * @see javax.portlet.GenericPortlet#doView(javax.portlet.RenderRequest, javax.portlet.RenderResponse)
 */
@Override
public void doView(RenderRequest request, RenderResponse response) throws IOException {
    PrintWriter writer = response.getWriter();
    writer.write("Hello World !");
    writer.close();
}
}
Two important things have occurred:
  • javax.portlet.GenericPortlet was extended from the javax.portlet:portlet-api artifact.
  • The doView() method has been overridden.
Edit and help portlet modes are not supported in this portlet. To add them, override the doEdit() and doHelp from javax.portlet.GenericPortlet and configure the portlet.xml file accordingly.

22.3.2. portlet.xml

The portlet.xml file for a plain JSR- 286 portlet is as follows:

Example 22.3. portlet.xml


<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" version="2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd">
<portlet>
    <description>Simplest Hello World Portlet is the very essence of every possible Portlet.</description>
    <portlet-name>SimplestHelloWorldPortlet</portlet-name>
    <display-name>Simplest Hello World Portlet</display-name>
    <portlet-class>org.jboss.portal.portlet.samples.SimplestHelloWorldPortlet</portlet-class>
    <supports>
        <mime-type>text/html</mime-type>
        <portlet-mode>view</portlet-mode>
        <!-- You can uncomment the other modes when your portlet-class supports them
        <portlet-mode>edit</portlet-mode>
        <portlet-mode>help</portlet-mode>
        -->
    </supports>
    <portlet-info>
        <title>Simplest Hello World Portlet</title>
    </portlet-info>
</portlet>
</portlet-app>

22.3.3. web.xml

There is no need to configure filters, servlets or mapping for a plain JSR- 286 portlet to work. However the maven-war-plugin artifact requires the web.xml by default. It can suffice to include a web.xml file which contains only the root element:

Example 22.4. web.xml


<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    version="2.5">
    <!-- 
        There is no need to configure any filters, servlets, mapping & co. for this demo to work
        but maven-war-plugin by default requires this file.
    -->
</web-app>

22.3.4. Building and Deploying Portlets

Build and deploy the portlet by following the included procedure.
Import the portlet and add the portlet to a page to test its functionality. See the User Guide for instructions.

Procedure 22.1. Build and Deploy the Portlet

  1. Ensure the portal instance is running.
  2. Open a command line and navigate to the root directory of the portlet project.
  3. To deploy to portal instances not listening on localhost:9999 paste the following configuration immediately after <version>${jboss.as.plugin.version}</version> in the pom.xml file
    
    <configuration>
      <hostname>127.0.0.1</hostname>
      <port>9999</port>
      <username>admin</username>
      <password>secret</password>
    </configuration>
    Adjust the configuration to suit individual requirements. <username> and <password> may be omitted depending on the portal's security settings.
    This will deploy target/simplest-hello-world-portlet.war to the running instance of the portal.
  4. Run mvn clean package jboss-as:deploy