Introduction

I've often been asked the question: "What is the simplest portlet one can create from scratch for WebSphere Portal Version 4.1?" The trite answer is "hello world". The longer, detailed answer is what this article is about. I'm going to take you through creating the simplest of portlets for WebSphere Portal. We'll start with some Java code, compile and package that. Then we'll look at the deployment descriptors needed for telling the application server and the portal about the portlet. Finally we'll package it all together and deploy the new portlet into the portal.

Back to top

Section 1 - Create the directory structure

To start off, you must create a directory structure in which you create your portlet. Here's what I'll use for this simple portlet:

• helloWorld\com\ibm\portlets\sample - where your source will go
• helloWorld\WEB-INF - where the deployment descriptors live
• helloWorld\WEB-INF\lib - where the JAR file will go

Back to top

Section 2 - Create the Java

The sample directory is where we will put our Java source file. Create a file named HelloWorld.java in the sample directory and open it in your favorite text editor. Here's the class that you will need to type (or cut and paste) into the HelloWorld.java file:

package com.ibm.portlets.sample; 
 
//portlet APIs 
import org.apache.jetspeed.portlet.*; 
import org.apache.jetspeed.portlets.*; 
 
//Java stuff 
import java.io.*; 
 
public class HelloWorld extends AbstractPortlet { 
 
  public void 
        service(PortletRequest 
        request, PortletResponse 
        response) 
    throws PortletException, 
        IOException { 
 
    PrintWriter writer = 
        response.getWriter(); 
    writer.println("Hello World!"); 
  } 
}

Back to top

Section 3 - Compile the code

Once we have created the source file, we are ready to compile the Java code. The script below could be used in a batch file to compile the portlet. We start by defining some environment variables, such as where our Java home is. It's usually a good idea to compile this using the JDK provided with the WebSphere Application Server since that is the environment we will be running under. We also set our PATH so that we can get to the Java compiler. Set the variable LIBPATH to point to the directory where the WebSphere JAR files are located. Next, we build a variable called CP for our compilation classpath. The CP variable could be built on a single line, but we broke it up to show the various JAR files required. We then invoke the Java compiler and compile our code. This assumes we are in the helloWorld directory. Adjust your directory paths as appropriate for your installation.

set JAVA_HOME=C:\WebSphere\AppServer\java 
set PATH=%JAVA_HOME%\bin 
set LIBPATH=C:\WebSphere\AppServer\lib 
set CP=. 
set CP=%CP%;%LIBPATH%\j2ee.jar 
set CP=%CP%;%LIBPATH%\websphere.jar 
set CP=%CP%;%LIBPATH%\app\wpsportlets.jar 
set CP=%CP%;%LIBPATH%\app\wps.jar 
set CP=%CP%;%LIBPATH%\app\portlet-api.jar 
 
javac -classpath %CP% com\ibm\portlets\sample\HelloWorld.java 

If for some reason this doesn't compile, you're going to have to fix the errors before moving on. A couple common errors are:

• Typos - mistyped class names, paths, variable names
• File name - the file name and the class name must match. In our case, the file name is HelloWorld.java and the class name is HelloWorld. If you have changed one, change the other.
• Editor woes - make sure your editor really saves the file as text. An editor like WordPad does not save as text by default.

Back to top

Section 4 - Create the JAR file

Once the Java source is compiled, we need to create a JAR file in the WEB-INF\lib directory. Again, assume we are in the helloWorld directory. These statements could be included as part of a batch file, if you created one in Section 3. It relies on having the PATH set to get to the jar program.

set JAVA_HOME=C:\WebSphere\AppServer\java 
set PATH=%JAVA_HOME%\bin 
 
jar -cv0f .\WEB-INF\lib\HelloWorld.jar com/ibm/portlets/sample/*.class 

Back to top

Section 5 - Create the deployment descriptors

You will need to create two XML files:

• helloWorld/WEB-INF/web.xml - the web deployment descriptor.
• helloWorld/WEB-INF/portlet.xml - the portlet deployment descriptor.

web.xml - the Web deployment descriptor

The Web deployment descriptor is needed for WebSphere Portal. Portlets extend Servlets now, so the Web deployment descriptor is needed to declare the Servlet (portlet) class.

<?xml version=
        "1.0" encoding=
        "UTF-8"?> 
<!DOCTYPE web-app 
  PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" 
  "http://java.sun.com/j2ee/dtds/web-app_2.2.dtd"> 
<web-app id="HelloWorldWebApp"> 
  <display-name>HelloWorldPortlet<
        /display-name> 
  <servlet id="Servlet_1"> 
    <servlet-name>HelloWorld<
        /servlet-name> 
    <servlet-class>com.ibm.portlets.sample.HelloWorld<
        /servlet-class> 
  </servlet> 
  <servlet-mapping id=
        "ServletMapping_1"> 
    <servlet-name>HelloWorld<
        /servlet-name> 
    <url-pattern>/HelloWorld/*<
        /url-pattern> 
  </servlet-mapping> 
</web-app>

portlet.xml - the portlet deployment descriptor

The portlet deployment descriptor defines the portlet to the portal. Each portlet is mapped to a Servlet defined in the Web deployment descriptor by way of the href attribute on the portlet element. These references are denoted in red. A portlet must define a unique id that each concrete portlet can reference. Each concrete portlet references a portlet using the given id in the href attribute of the concrete-portlet element. These references are denoted in purple.

<?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.portlets.sample.HelloWorld.1"> 
    <portlet-app-name>HelloWorld0Portlet<
        /portlet-app-name> 
    <portlet href="WEB-INF/web.xml#Servlet_1" id=
        "Portlet_1"> 
      <portlet-name>HelloWorld<
        /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.portlets.sample.HelloWorld.1.2"> 
    <portlet-app-name>Concrete HelloWorld<
        /portlet-app-name> 
    <context-param> 
      <param-name>Author<
        /param-name> 
      <param-value>tcat@us.ibm.com<
        /param-value> 
    </context-param> 
    <concrete-portlet href=
        "Portlet_1"> 
      <portlet-name>HelloWorld<
        /portlet-name> 
      <default-locale>en<
        /default-locale> 
      <language locale=
        "en"> 
        <title>Hello World<
        /title> 
      </language> 
    </concrete-portlet> 
  </concrete-portlet-app> 
</portlet-app-def>

Many things can go wrong when creating these XML files. You will not find out until you attempt to deploy the portlet into the portal. Here's some things to double check.

• Verify that for every XML element you have a closing element.
• Check for mistyped class names, especially for this example if you named your class something other than HelloWorld.
• Make sure your id and href attributes match.
• Make sure your editor really saves the file as text.

Back to top

Section 6 - Create the WAR file

Finally, we are ready to create the WAR file for distribution. We'll use the standard jar command to build the WAR file. We run this from the helloWorld directory.

set JAVA_HOME=C:\WebSphere\AppServer\java 
set PATH=%JAVA_HOME%\bin 
 
jar -cf HelloWorld.war WEB-INF 

Back to top

Section 7 - Deploy the WAR file

1. Login to the portal as the portal administrator -- wpsadmin.
2. Select the Portal Administration page group.
3. Select the Portlets page and the Install Portlets portlet. It should be selected for you.
   
   Figure 1. Install Portlets administration page
   
   
4. Click .
5. Find the location of WAR file, select it, and click .
   
   Figure 2. File selection dialog
   
   
6. Click . This could take some time, so wait for it to finish.
7. Verify Portlet is HelloWorld. Click . Again, wait for it to complete.
   
   Figure 3. Portlet install verification screen
   
   
8. Finally, you should see this confirmation: .
   

If you get some sort of error during deployment, this usually means that you've made a mistake in one of your XML files. Take a look in the latest log file:
%WPS_HOME%/log/wps_YYYY.MM.DD-HH.MM.SS.log

Some common mistakes made with the XML files are listed in Section 5. You might also check the following:

• The XML declaration must be first line in file (no whitespace).
• The xml files have the correct names, in the correct case.

Back to top

Section 8 - Add portlet to the welcome page

1. Select the Work with Pages page group.
2. On the Edit Layout and Content page, under Page Group, select the Home page group.
3. Then select the Welcome page.
   Figure 4. Edit layout and content screen
   
   
4. Click .
5. Search on Name Contains: Hello, click .
6. Click beside HelloWorld portlet, click .
   
   Figure 5. Search for portlets
   
   
7. Highlight HelloWorld, click the add portlet icon ( ).
   
   Figure 6. Add portlet to page screen
   
   
8. Click to reactivate the page.
9. Select Home in the drop-down to view the portlet. We've placed our portlet on the bottom left-hand side of the Welcome page.
   
   Figure 7. Portal displaying our portlet
   
   

Back to top

Conclusion

Now you can rejoice as you have just created a new portlet! You now know how to create a simple portlet from scratch. You wrote, compiled and packaged the Java code. You then created the deployment descriptors and packaged the portlet for distribution and deployment. Finally, you deployed the portlet into your portal.

From here, it is possible for you to write any portlet. Good luck and have fun!

Top of page

Resources

• Portlet Developer's Guide (PDF File)
  
  
• WebSphere Portal for Multiplatforms
  
  
• WebSphere Developer Domain Portal Zone
  
  

About the author

Ron Lynn (a.k.a. tcat) is an Advisory software engineer at IBM's Santa Teresa Lab. Ron has worked on both sides of knowledge management. He enjoys playing with his 6 month old son Rowan, making wooden toys for said son, and futzing with Linux on his PlayStation 2.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Section 1 - Create the directory structure
• Section 2 - Create the Java
• Section 3 - Compile the code
• Section 4 - Create the JAR file
• Section 5 - Create the deployment descriptors
• Section 6 - Create the WAR file
• Section 7 - Deploy the WAR file
• Section 8 - Add portlet to the welcome page
• Conclusion
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into WebSphere on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers