Introduction

I've often been asked the question: "What is the simplest portlet one can create from scratch for WebSphere Portal Version 5?" 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 V5. You start with some Java code, compile it, and then package it. Then, you create the deployment descriptors needed for telling the application server and the portal about the portlet. Finally, you package it all together and deploy the new portlet into the portal.

Back to top

Creating the directory structure

To start off, 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

Creating the Java

The sample directory is where you put the 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 need to type (or copy and paste) into the HelloWorld.java file:

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

Back to top

Compiling the code

After you have created the source file, you are ready to compile the Java code. The script below could be used in a batch file to compile the portlet. You start by defining some environment variables, such as where your Java home is. It's usually a good idea to compile this using the JDK provided with the WebSphere Application Server because that is the environment in which you will run the application. You also set your 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, you build a variable called CP for our compilation classpath. The CP variable could be built on a single line, but the listing below breakes it up to show the various JAR files required. Then, you invoke the Java compiler and compile the code. The listing assumes you 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%\dynacache.jar 
set CP=%CP%;C:\WebSphere\PortalServer\shared\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. Some common errors are:

• Typos - mistyped class names, paths, variable names
• File name - the file name and the class name must match. In this 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

Creating the JAR file

After the Java source is compiled, you need to create a JAR file in the WEB-INF\lib directory. Again, the examples assumes you are in the helloWorld directory. These statements could be included as part of a batch file, if you created one in the Compile the code section. 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

Creating the deployment descriptors

Now, you 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, 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.3//EN" 
  "http://java.sun.com/dtd/web-app_2_3.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 bold. 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 blue.

<?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" major-version="1"
        minor-version="0"> 
     <portlet-app-name>HelloWorld0Portlet</portlet-app-name> 
     <portlet href="WEB-INF/web.xml#Servlet_1"id="Portlet_1" major-version="1"
        minor-version="0"> 
      <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> 
        <title-short></title-short> 
        <description></description> 
        <keywords></keywords> 
      </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 are 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

Creating the WAR file

Finally, you are ready to create the WAR file for distribution. You use the standard jar command to build the WAR file. 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

Deploying the WAR file

1. Login to the portal as the portal administrator (wpsadmin).
2. Select the Administration link in the upper right hand corner of the default theme.
   Figure 1. The administration link
   
   
3. Select the Portlets page on the left and the Install portlet.
   
   Figure 2. Install portlets administration page
   
   
4. Click .
5. Find the location of WAR file, select it, and click .
   
   Figure 3. 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 4. 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 at the error messages you're presented with on the install page. You can usually figure out the problem from there. These messages are also 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 Create deployment descriptors 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

Adding the portlet to a page

1. Select Portal User Interface page on the left.
2. Click the Manage Pages portlet.
   Figure 5. Manage pages portlet
   
   
3. Then select the My Portal page.
4. Click .
5. Enter a title for the new page.
6. Click .
7. Click when you see .
8. Click the edit page icon, , next to your new page.
9. Click .
10. Search for: Hello, click .
11. Select the Hello World portlet and click .
    
    Figure 6. Search for portlets
    
    
12. Click to finish the page layout.
    Figure 7. Edit layout
    
    
13. Click the My Portal link in the upper right and then select the page that you created.
    Figure 8. 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

• WebSphere Portal product documentation
  
  
• WebSphere Portal zone
  
  

About the author

Ron Lynn (a.k.a. tcat) is a Senior software engineer at IBM's Santa Teresa Lab. Ron has worked on portal projects since before they were called portals. He enjoys learning new technologies and playing with his ever growing family.

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Creating the directory structure
• Creating the Java
• Compiling the code
• Creating the JAR file
• Creating the deployment descriptors
• Creating the WAR file
• Deploying the WAR file
• Adding the portlet to a 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

Cloud computing for developers

Virtual workshop: Learn how to build a cloud infrastructure and develop/deploy cloud-based applications. (6-8 Apr 2010)

Special offers