January 23, 2021
Hot Topics:

An Introduction to Java Enterprise Portals and Portlet Development

  • By Vlad Kofman
  • Send Email »
  • More Articles »

Developing a Portlet

To begin, create a standard Java project. The first step in making it a portlet project is to create a portlet.xml file, which is a deployment descriptor that specifies what portlets are available for the container and which class should be used to instantiate them. However, the specification does not define how a portal registers and recognizes portlets.

Author's Note: For the examples in this article, I used the Java Spring framework, which provides some helpful utilities and container beans, to simplify some of the Portlet API plumbing. I also used the Eclipse IDE to set up the portlet project. However, any portlet developed according to the JSR 168 or JSR 286 specifications should be able to run on any compliant container, so you don't have to use the same technology to code and build the examples.

Figure 5 shows the structure for the sample portlet project.

Figure 5. Portlet Project Structure:
The figure shows the structure of the sample portlet project.

The portlet.xml file for the sample project defines a single portlet:

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns=
        <title>Quick Search</title>

The preceding portlet.xml file specifies the contextConfigLocation as an initial parameter for the Spring class.

Listing 1 shows the sample Spring contextConfigLocation file:

The next step is to write some Java source to act as a controller, view, and handler for the portlet. The view is a JSP page, while the controller and handler are Java classes. For samples of these artifacts, please see the downloadable source, which contains a portlet skeleton project for this article.

The controller, with the handler class's help, fetches data from some data source, such as a web service, database, or feed. You can implement the mechanism to pass this data to the view via the command pattern, where commandObject is the carrier of information throughout the user portlet session.

For example, the following code is a skeleton that illustrates Portlet API methods to get data and return it to the view layer:

protected ModelAndView handleRenderRequestInternal(
   RenderRequest request, RenderResponse response) throws Exception 
   logger.info ("Inside Controller handleRenderRequestInternal");      
   Map<String, CommandObject> model = new 
     HashMap<String, CommandObject>();   
   CommandObject commandObject = 
   if (commandObject == null){
      commandObject = new CommandObject();
   // logic to get the data and put it in the commandObject 
   // should be here...
   String view = getFormView();
   model.put("commandObject", commandObject);
   ModelAndView mav = new ModelAndView(view, model);
   return mav;  
public void onSubmitAction (final ActionRequest request, 
  final ActionResponse response, final Object command,
  final BindException bindException) throws Exception 
   logger.info ("Inside onSubmitAction");
   // Set the form bean into session so that it will be available 
   CommandObject commandObject = (CommandObject)command;
   logger.info("Command Object :"+ToStringBuilder.reflectionToString(
   request.getPortletSession ().setAttribute ("command_obj", 

From the JSP, you can retrieve the data as follows:

<form:form action="${formAction}" name="quickProcess" 
   method="post" commandName="commandObject">    
  <form:hidden path="p" id="p" />
  <c:if test="${commandObject.someList != null}">
    <c:forEach items="${commandObject.someList}" 
      var="listItem" varStatus="loop">              
      <c:out value="${listItem.name}"/><br>            

Figure 6. Adding a Portlet in Vignette:
In Vignette Portal Server, you can list portlets to add them.

Note that the portlet does not specify how it should be laid out on the screen, whether it can be resized, or what width and height it should have. The portlet container controls all these external properties.

To make the Portlet project work, you need to build and deploy it. In the build step, create a standard java war file (typically using Ant or Maven). In the deploy step place the war file on the application server that also hosts the portlet container application. When the portlet is configured and registered in the portlet container, the portlet.xml file is used to discover what portlets are available and what they are called. For example, in Vignette Portal server you can create a new portlet by searching for it and adding it to the site (see Figure 6 and Figure 7).

Figure 7. Searching for Portlets in Vignette:
You can also search for portlets you want to add to a site.

Figure 8. Setting Portlet Layout in Vignette:
Here's an administrative page that lets you configure portlet layout in Vignette.

After adding the portlets are to portlet container, you can (depending on the platform) set up their placement, layout, and properties. For instance, you can set a default width and location, and specify that the portlet cannot be minimized or moved, etc.

Figure 8 shows a Vignette example page with three configured portlets. When a user logs into the portal this is the default placement that will be used.

Figure 9 shows a few default layouts you can choose in the eXo JBoss portlet container. Of course, you are not required to use these, but it's convenient to have out-of-the-box page grid layouts that you can assign with just a few mouse clicks.

Figure 9. Default Layouts:
The eXo JBoss portlet container provides several default layouts that you can select.

The latest portlet containers make it easy to change the look and feel of a portal site by changing the layout, skins, or UI scheme of the portlets—all from a convenient administrative dashboard.

At this point, you've seen the rudiments of how web portals and portlet containers work as well as an example of developing a portlet using the latest Java specification and deployment techniques. The creation of the concrete specification facilitated proliferation of the portlet containers in the web development area, from both open source and commercial vendors. This in turn, made it easy for Java web developers to reuse portlet code, concentrate on business logic, and provide robust out or the box features for the end-users without writing much portal code. It will be interesting to see what new developments will appear in the Java portal space in coming years. To follow up, you may find these reference links useful:


Listing 1. QuickSearchDefinition.xml: This is the Spring contextConfigLocation file.
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  <bean id="quickEntitySearchController" 
    <property name="sessionForm"><value>true</value></property> 

    <!-- Keep command object throughout session -->
    <property name="commandName" value="commandObject"/>
    <property name="commandClass" 
    <property name="formView"><value>quick.search</value></property>
    <property name="successView"><value>quick.search</value></property>
    <property name="bindOnNewForm"><value>true</value></property>     
    <property name="quickServiceClient" ref="quickServiceClient"/>
  <bean id="portletModeParameterHandlerMapping" class="
    <property name="order" value="10"/>
    <property name="interceptors">
        <ref bean="parameterMappingInterceptor" />

    <property name="portletModeParameterMap">
        <entry key="view">
            <entry key="basePageAction">
              <ref bean="quickSearchController"/>
  <bean id="portletModeHandlerMapping" class=
    <property name="interceptors">
        <ref bean="parameterMappingInterceptor" />
    <property name="portletModeMap">
        <entry key="view"><ref bean="quickSearchController"/></entry>

About the Author

Vlad Kofman is currently working on enterprise-scale projects for major Wall Street firms. He has also worked on defense contracts for the U.S. government. His main interests are web-related programming methodologies, UI patterns, and SOA.

Page 2 of 2

This article was originally published on November 2, 2009

Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Thanks for your registration, follow us on our social networks to keep up-to-date