Level: Intermediate Ron Lynn (tcat@us.ibm.com), Portal TechnoGuppy, IBM Santa Teresa Labs
11 Jun 2002 This article takes you through the steps to create and deploy a simple portlet on WebSphere Portal Version 4.1.
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.
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 gohelloWorld\WEB-INF - where the
deployment descriptors livehelloWorld\WEB-INF\lib - where the JAR
file will go
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!");
}
} |
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.
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
|
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.
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
|
Section 7 - Deploy the WAR file
- Login to the portal as the portal administrator -- wpsadmin.
- Select the Portal Administration page group.
- Select the Portlets page and the Install Portlets
portlet. It should be selected for you.
Figure 1. Install Portlets administration
page
- Click
 .
- Find the location of WAR file, select it, and click
 .
Figure 2. File selection dialog
- Click
 . This could
take some time, so wait for it to finish.
- Verify Portlet is HelloWorld. Click
 . Again, wait
for it to complete.
Figure 3. Portlet install verification screen
- 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.
Section 8 - Add portlet to the welcome page
- Select the Work with Pages page group.
- On the Edit Layout and Content page, under Page
Group, select the Home page group.
- Then select the Welcome page.
Figure 4. Edit layout and content screen
- Click
 .
- Search on Name Contains:
Hello, click  .
- Click
beside HelloWorld portlet, click  .
Figure 5. Search for portlets
- Highlight HelloWorld, click the add portlet icon (
 ).
Figure 6. Add portlet to page screen
- Click
 to
reactivate the page.
- 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
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
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.
|
Rate this page
| 
