+

Search Tips   |   Advanced Search

Create a simple portlet


View the basic steps for creating a simple portlets that include writing the portlet code, compiling java source, creating the JAR file, writing the portlet descriptors, setting up the WAR file directory structure, and packaging and deploying portlets.

Before developing portlets, setup an environment that makes the tasks of writing, compiling, and testing portlets easier. Rational Application Developer includes a test environment used to run and debug the portlets without having to manually deploy them to the server. We can setup the run time environment for debugging portlets on the local development machine or on a remote server. Refer to the documentation for Rational Application Developer for complete setup instructions.

Rational Application Developer provides wizards to help build, test, and deploy portlets using all of the APIs and related classes and interfaces available in the portlet run time environment. We can also build portlets using our own dev environment and tools. If we are not using wizards to develop portlets, the following topics describe the mechanics of building a simple portlet.


Write the portlet code

The Hello World portlet provides an introduction to writing the first portlet. The portlet is provided along with the source in the IBM Portlet Samples package, available from the portlet catalog by searching for navcode 1WP10017Z. Hello World provides the fewest methods required for a portlet. It uses the portlet response object to write simple output directly to the portal page.

Figure 1. Example: Java source for Hello World portlet (standard portlet API) 

package com.ibm.wps.samples.jsr;

import javax.portlet.*;
import java.io.*;

public class HelloWorld extends GenericPortlet {
 
   public void init (PortletConfig portletConfig) throws UnavailableException, PortletException
   {
      super.init(portletConfig);
   }

   public void doView(RenderRequest request, RenderResponse response)
                      throws PortletException, IOException
   {

      // set return content type 
      response.setContentType("text/html");
      PrintWriter writer = response.getWriter();
      writer.println("<p class='wpsPortletText'>Hello Portal World!</p>");
    }

}

If we are familiar with writing to the IBM portlet API, here are some of the key differences between this standard API example and the corresponding Figure 6.

API element IBM portlet API Java Portlet Specification
import statements org.apache.jetspeed.portlet javax.portlet
Portlet class PortletAdapter GenericPortlet which also can throw a PortletException
Request object PortletRequest RenderRequest
Response object PortletResponse RenderResponse

Also notice that the content type must be set in the response.


Compiling Java source

Compile your Java source files: Before you compile the Java source, set the CLASSPATH for the compiler to find the JAR files for any portlet packages that the portlet uses by running the following command:

The following JAR files should be set in the CLASSPATH to compile portlets:

Then, compile the portlet using the fully qualified path to the Java portlet source. 

   appserver\java\bin\javac -classpath %WAS_CLASSPATH%;path_to\portletapi_20.jar 
        com.ibm.wps.samples.jsr.HelloWorld.java 

   appserver\java\bin\javac -classpath %WAS_CLASSPATH%;path_to\portletapi_20.jar 
        com.ibm.wps.samples.v4.HelloWorld.java


Creating the JAR file

Next, the portlet must be packaged in the JAR file format. To create a JAR file with the name HelloWorld.jar command: 

   jar -cf HelloWorld.jar HelloWorld.class

Refer to the JDK documentation for more information about the JAR command.


Writing the portlet descriptors

The following samples can be packaged with the Hello World portlet.


Set up the WAR file directory structure

Before you package the portlet, the class files and resources must be arranged in the WAR file directory structure described here. A portlet application exists as a structured hierarchy of directories.

Do not package .tld files for tag libraries provided by the portal or application server installation with the portlet application WAR file, including the IBM portlet API tags, JSR 168 and 286 portlet tags and the Java Standard Tag Library (JSTL).

The application server searches for security policy files in the location of the enterprise application archive rather than the Web application archive. Therefore, the portal server copies was.policy from the appname.war/META-INF directory to the generated appname.ear/META-INF directory during deployment of a portlet WAR file.


Packaging and deploying portlets

To deploy a portlet and run it on the server, it must be packaged in the form of a Web application ARchive or WAR file. The WAR file format contains the Java classes and resources that make up one or more portlets in a portlet application. The resources can be images, JSP files, Write the portlet descriptors, and property files containing translated message text. Packaging portlet classes, resources, and descriptive information in a single file makes distribution and deployment of portlets easier.

WebSphere Portal includes an administrative portlet for installing, uninstalling, and updating portlets. Portlets contained in WAR files have the advantage of being dynamically downloaded and installed. The portal administrator can download a WAR file from the Internet and then use the portal administration interface to install the portlet to WebSphere Portal. After installation, the portlet is ready for use and does not require the server to be restarted. To package the portlet in a WAR file, we can use the JAR utility to package the portlet into a WAR file.

Because Windows limits the maximum path length to 260 characters, the name of the WAR file must be less than 25 characters. On a portal server running on Windows, installing a WAR file with a name that is more than 25 characters will result in an error.

We can also run the build-war-file or build-ear-file tasks to build the .war and .ear files.

See the "Building .ear and .war files" link in the Related task section for information.


IBM portlet API examples for Hello World

Figure 6. Example: Java source for Hello World portlet (IBM) 

package com.ibm.wps.samples.v4;

import org.apache.jetspeed.portlet.*;
import java.io.*;

public class HelloWorld extends PortletAdapter {

   public void init (PortletConfig portletConfig) throws UnavailableException
   {
      super.init(portletConfig);
   }

   public void doView(PortletRequest request, PortletResponse response)
                      throws PortletException, IOException
   {
      PrintWriter writer = response.getWriter();
      writer.println("<p class='wpsPortletText'>Hello Portal World!</p>");
   }

}

Figure 7. Example: Web application deployment descriptors (IBM) 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" 
                         "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app id="WebApp">
        <display-name>HelloWorld</display-name>
        <servlet id="com.ibm.wps.samples.HelloWorld.a0ae41f2d3c1001710b7b313e1a97">
        <servlet-name>HelloWorld</servlet-name>
        <servlet-class>com.ibm.wps.samples.v4.HelloWorld</servlet-class>
        </servlet>
    <servlet-mapping 
       id="ServletMapping_com.ibm.wps.samples.HelloWorld.a0ae41f2d3c1001710b7b313e1a97">
        <servlet-name>HelloWorld</servlet-name>
        <url-pattern>/HelloWorld/*</url-pattern>
    </servlet-mapping>
</web-app>

As described in Deployment descriptors, the href attribute of the <portlet/> element references the servlet ID from Web deployment descriptors.

The portlet deployment descriptors references the portlet_1.1.dtd, which portal server finds in the PORTAL_HOME/installer/wp.ear/installableApps/wps.ear/wps.war/dtd directory. Do not package the DTD with the portlet application WAR file.

Figure 8. Example: Portlet deployment descriptor (IBM) 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE portlet-app-def PUBLIC "-//IBM//DTD Portlet Application 1.1//EN" 
                                 "portlet_1.1.dtd">
<portlet-app-def>
  <portlet-app uid="com.ibm.wps.samples.HelloWorld.a0ae41f2d3c1001710b7b313e1a97" 
               major-version="1" minor-version="0">
    <portlet-app-name>HelloWorld application</portlet-app-name>
    <portlet id="com.ibm.wps.samples.HelloWorld" 
             href="http://setgetweb.com/p/portal80/WEB-INF/web.xml#com.ibm.wps.samples.HelloWorld.a0ae41f2d3c1001710b7b313e1a97"
             major-version="1" minor-version="0">
      <portlet-name>HelloWorld portlet</portlet-name>
      <cache>
        <expires>0</expires>
        <shared>NO</shared>
      </cache>
      <allows>
        <maximized/>
        <minimized/>
      </allows>
      <supports>
        <markup name="html">
          <view/>
        </markup>
      </supports>
    </portlet>
  </portlet-app>
  <concrete-portlet-app uid="com.ibm.wps.samples.HelloWorld.313e1a97f47.2">
    <portlet-app-name>HelloWorld application</portlet-app-name>
    <concrete-portlet href="http://setgetweb.com/p/portal80/#com.ibm.wps.samples.HelloWorld">
      <portlet-name>HelloWorld portlet</portlet-name>
      <default-locale>en</default-locale>
      <language locale="en">
        <title>HelloWorld portlet</title>
        <title-short></title-short>
        <description></description>
        <keywords></keywords>
      </language>
    </concrete-portlet>
  </concrete-portlet-app>
</portlet-app-def>


Parent: Understand the basics
Related:
Build .ear and .war files