Very simple ant-based portlet which extends GenericPortlet

Portlet Example

This example is Wikified from the example in the uPortal documentation.

Purpose: To demonstrate how to create a Portlet for uPortal 2.3./2.4..

For this example, we will be creating 3 files directly. Our root directory will be /example. The files we need are as follows:

/example/WEB-INF/classes/helloworld/HelloWorld.java
/example/WEB-INF/web.xml
/example/WEB-INF/portlet.xml

Please note: $TOMCAT_HOME refers to the root directory where Tomcat is installed in and $UPORTAL_HOME refers to uPortal's SRC root directory (E.G. if you download the quick-start, this directory would be <basedir>/uPortal_2-3-4-quick-start/uPortal_rel-2-3-4). This walkthrough also assumes you have ANT installed.

Create and compile the HelloWorld class

HelloWorld.java

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

public class HelloWorld extends GenericPortlet { 
   public void doView(RenderRequest request,RenderResponse response) 
      throws PortletException,IOException { 

      // Get our preferences
      PortletPreferences pref = request.getPreferences();

      // Get the value of "displaytext" from our preferences, if not available,
      // then use the second string passed to the function
      String displayText = pref.getValue("displaytext", "MISSING: display-text");
      // displays the string from our preferences

      response.setContentType(request.getResponseContentType()); 
      PrintWriter writer = response.getWriter(); 
      writer.write(displayText); 
   } 
}

Note: to compile the file, you will need the Portlet library in your classpath this should be found in $UPORTAL_HOME/lib/portlet-api-1.0.1.jar

This file needs to be compiled such that the class resides in the same directory as our source file (this was done for simplicity).

Create the web descriptor file

<?xml version="1.0" encoding="ISO-8859-1"?> 
<!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>
   <display-name>HelloWorld</display-name>
   <description>Hello World Portlet</description>

   <!-- The security role is something SUN says should be included, but causes
   problems with uPortal, so Ive commented it out.
   <security-role>
   <role-name>user>/role-name>
   </security-role>
   -->

</web-app>

Create the Portlet descriptor file

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" version="1.0"> 
   <portlet> 
      <portlet-name>HelloWorld</portlet-name> 
      <portlet-class>helloworld.HelloWorld</portlet-class> 
      <expiration-cache>0</expiration-cache> 
      <supports> 
         <mime-type>text/html</mime-type> 
         <portlet-mode>VIEW</portlet-mode> 
      </supports> 
      <supported-locale>en</supported-locale>
      <portlet-info> 
         <title>HelloWorld</title> 
         <keywords>Hello, world, test</keywords>
      </portlet-info>
      <portlet-preferences>
         <preference>
            <name>displaytext</name>
            <value>Hello, from your preferences</value>
         </preference>
      </portlet-preferences>
   </portlet>
</portlet-app>

This file is important - it specifies Portlet mapping to the class name as well initial parameters, various modes it supports, keywords, title, and more. Initial parameters are specified in the Portlet-preferences section they can also be specified from the portal itself. uPortal gives the ability to specify Portlet preferences when you publish the channels making it easier to deploy one class that takes a URL or something of the sort and displays a different view based on that. Preferences specified in uPortal supersede preferences in the portlet.xml file. This is a relatively minimal file, however with simply the class mapping. All Portlets need to have the view mode but are not required to implement anything else.

Create the Web Archive (WAR) file and deploy it

This is simply a JAR file with a different extension.

From the /example directory, type: jar cvf helloworld.war *

This will give you a WAR file which is used by uPortal and translated for use with the Pluto container.

From $UPORTAL_HOME type: ant deployPortletApp -DportletApp=/example/helloworld.war

You may need a script file (ant.sh or ant.bat) to get it to work properly (on Windows this worked fine, but on Linux I needed the script). uPortal has an ANT build target labeled deployPortletApp that causes the Portlet to be deployed into the proper location, have a couple files added to the structure, and the XML files translated to ones that Pluto likes. Assuming everything goes well, you should be able to look in your $TOMCAT_HOME/webapps directory and see a new directory named helloworld.

Finally, you must publish the Portlet. Start up uPortal, go to the Channel Manager, select publish a new channel and select Portlet as the type. Most of the parameters are relatively self-explanatory and can be filled in easily just make sure that the Portlet Definition ID is correct for our example this needs to be helloworld.HelloWorld. (context-path.portlet-name). After all the other parameters are done, just add the Portlet as you would any other channel.

More information may be found here:
Working with Portlets
A Sun document
A Sun whitepaper
JSR 168 Java Community Process page