Developing Portlets with Apache Pluto

Friday Oct 7th 2005 by David DeWolf

Discover the advantages of using Pluto (the reference implementation of the Java Portlet Specification (JSR-168) as a portlet development environment and the practical steps needed to set up such an environment.

The Java Portlet Specification (originally created through JSR-168) provides a standard for developing portal components with the Java programming language. This specification, originally released in October of 2003, is gaining popularity as not only a standard for traditional portals, but also as a framework for deploying 'plugins' for standard Web applications. Apache Pluto is the reference implementation of the Java Portlet Specification. In addition to implementing the container interface required by the specification, the Pluto project provides a simple portal (driver) and other utilities which can be used to develop standard Portlets.

This article provides a basic introduction to the Pluto Portal Driver. It will investigate the basic architecture of the portal driver and introduce the development utilities and techniques. This article discusses the Pluto Portal Driver version 1.1.

Portal Components and Apache Pluto

The Java Portlet Specification defines three major components of a portal system. The Portal itself provides personalization, single sign on, content aggregation, and other enterprise services. The specification does not specify which services must be implemented by the portal. This decision is left up to the discretion of the portal vendor.

Java Portlets provide content from disparate sources. This content is aggregated into a single presentation by the portal. Portlet developers wanting to create portlets that are deployable within a compliant portal implement interfaces defined by the Portlet API and adhere to the lifecycle restrictions defined by the Portlet Specification.

A Portlet Container manages the lifecycle of Java Portlets. Portlet containers instantiate, initialize, and invoke portlets in a manner defined by the specification. According to the specification, portals may implement their own container or embed an existing container. No matter what approach is taken, the container must ensure that Portlets are invoked in a manner compliant with the Java Portlet Specification's requirements.

Apache Pluto is a subproject of the Apache Portals Project. The Pluto project provides the container required by the specification. The project also provides a simple portal application (also referred to as the Pluto Portal Driver), and other utilities that can be used for portlet development. Additionally, the portal driver provides an example of how to embed the container within a portal.

The Pluto Portlet Container

The Pluto Portlet Container manages the lifecycle and invocation of specification compliant portlets. It is this component of Apache Pluto that is the official reference implementation of the Portlet Specification. A detailed discussion of the Portlet Container architecture is not required to utilize Pluto as a development or simple portal environment. It is also beyond the scope of this discussion.

The Pluto Portal

The Pluto Portal is a Web application that provides a basic portal implementation. The portal is not intended to be an enterprise portal implementation. The portal is intended for the following purposes:

  • To simplify portlet development by providing a lightweight portal.
  • To provide a simple example of how to embed and invoke the portlet container from within a portal.
  • To provide an embeddable framework that can embedded within a Web application to provide support for pluggable components that adhere to the portlet specification.

In reality, the Pluto Portal is developed as two components. The portal proper provides the Web resource that makes up the user interface of the portal. This webapp utilizes the Pluto portal driver libraries (developed as a separate—reusable—module) for portlet invocation and other services. Although the portal driver does not support many extraneous services, it does support basic templating and aggregation services.

The Pluto Portal Driver Libraries

The Pluto Portal Driver provides the necessary hooks for invoking portlets through the Pluto Portlet Container. These hooks are implemented as tag libraries that can be utilized in any JSP page. The driver also provides a rather simple controller servlet, a templating framework, and an aggregation framework.

In addition to these services, the driver includes a configuration service that is used to properly configure the pages and portlets tgat are displayed within the portal. The default implementation of this service utilizes a simple XML file for configuration. Currently, real-time configuration through the portal interface (with RDBMS storage) is under development.

Driver Configuration

The default driver services are configured through a simple XML file—pluto-portal-driver-config.xml. Basic properties, supported window states and portlet modes, deployed portlet applications, and page configuration are all configured through this configuration.

Element Description
portal-name The name of the portal implementation as returned by PortalContext.getPortalInfo()
portal-version The version of the portal implementation as returned by PortalContext.getPortalInfo()
container-name The name of the portlet container as required by the Pluto portlet container
supports Defines a collection of items supported by the portal
portlet-mode Defines a mode that is supported by the portal and returned by PortalContext.getSupportedPortletModes()
window-state Defines a state that is supported by the portal and returned by PortalContext.getSupportedWindowStates()
portlet-app Defines a deployed portlet application whose portlets are accessible through the portal application
context-path Specifies the context path of the enclosing portlet application
portlets Specifies a collection of portlets deployed within the enclosing portlet application
portlet Specifies a portlet. Attributes:
  • name—the name of the portlet
  • context—the portlet application context of the portlet
render-config Specifies page configuration information
  • default - the default page
page A page within the portal. Attributes:
  • name—the name of the page
  • uri—the rendering URI of the application

The driver libraries are developed as a separate module so that they can be leveraged within different projects. For example, the Pluto Portal Driver (version 1.0.1) is currently used as the plugin framework for Apache Geronimo, a J2EE compliant Application Server.

Portal Driver Tag Libraries

The Pluto Driver implements custom tag libraries as a means to invoke the portlet container and other portal services. These tag libraries make it easy for portlet developers to customize the portal without needing to know the portal and portlet API. All tags within the Pluto library accept both runtime expression values and expression language attributes.

Tag Library Description
pluto:portlet Used to include a specified portlet (including any portal decorations). This tag acts as a context for all other tags within the Pluto tag library. The tag accepts a single portletId attribute that identifies the portlet to be included.
pluto:title Renders the currently included portlet's title. This tag may only be used within the context of the portlet tag.
pluto:window Renders a window control URI. This tag allows the user to specify both a window state and a portlet mode to which the portal should modify the portlet whenever the rendered URI is invoked. This tag is valid only within the scope of a portlet tag invocation.
pluto:render Used to render the content of the encapsulating portlet. The render tag outputs only the content directly retrieved from the portlet container and does not include any decorations. The tag must invoked from within the context of a portlet tag.
The Pluto Driver Controller Servlet

org.apache.pluto.driver.PortalDriverServlet implements a simple controller that is the center piece of a the Pluto Portal Driver. The servlet translates HTTP requests into an invocation plan by matching the requested page and portlet invocations with the configuration components defined by the configuration service.

The Pluto Portal Resources

The Pluto Portal Web application provides a default user interface for portlet and portal development. The provided Web resources are described below.

Resource Description
WEB-INF/web.xml Provides the Web application configuration needed to utilize the portal driver.
WEB-INF/pluto-portal-driver-config.xml Provides the driver configuration as described above.
WEB-INF/pluto-portal-driver-services-config.xml Provides the portal services configuration. This configuration allows for the inclusion of custom services such as an RDBMS portlet registry.
WEB-INF/fragments/template.jsp The user interface component that provides the default look and feel for the portal.
WEB-INF/fragments/portlet-page.jsp The user interface component that provides the page layout for portal pages.
WEB-INF/fragments/portlet-skin.jsp The user interface component that provides the portlet decorations and layout for each portlet present on a page.

Pluto Utilities

In addition to the Container, Portal Driver, and Portal subprojects, Apache Pluto project has developed various utilities that can ease the development of portlets.

Reading and Writing Portlet Descriptors

Pluto's descriptors libraries are developed and published as separate modules to ease the development of code that must read and write the portlet descriptor (portlet.xml). The descriptor-api libraries provide domain objects representing the elements of the descriptor as well as standard service interfaces for reading and writing their contents. The descriptor-impl module provides a default implementation of the services. This implementation uses castor to read and write portlet.xml files.

The TestSuite

The Pluto TestSuite is a compliant portlet that exercises many of the functions of the Pluto Portal and Pluto Portlet Container. Specifically, the TestSuite aims to provide as many end to end portlet tests that exercise specification requirements as possible. The purpose of the TestSuite is two-fold. Primarily, it provides a visual means for verifying that Pluto is conforming to the specification. Secondarily, it is a great source of reference by portlet developers. Because the portlet aims to be as comprehensive as possible, it is likely that any questions a portlet developer may have concerning standard portlet tags or APIs would be implemented within the portlets.

The Pluto Utilities Subproject

The Pluto utilities subproject contains utilities for building and installing the Pluto portal. It also contains the tools needed to deploy Pluto. These utilities are addressed in detail in the following sections.

Developing and Testing Portlets with Pluto

Pluto 1.1 is currently under development. It provides many enhancements over its predecessor (1.0) that allow for simplified installation of the portal and deployment of portlets. However, it has not yet been officially released. The first binary (alpha) release of Pluto 1.1 is expected in Q4 of 2005. In the meantime, individuals may build Pluto 1.1 from source.

Checking Out the Pluto Source Code

All Apache Software is readily available in the ASF Subversion repository. The following steps can be followedto check out the Pluto 1.1 source code.

  • Install a Subversion Client.
  • Check out the Pluto 1.1 repository from the following URL.
    When using the command line interface client, this is done by executing:
    svn checkout <target-url> <local-directory>

Investigating and Building Pluto

Apache Maven is used as Pluto's project management and build tool. (Click here to learn more about Maven 2). You must have Maven 2 installed to build Pluto 1.1 from source and to use the utilities subproject.

In addition to some licensing information and build files, the source distribution of Pluto 1.1 contains several directories. Each of these is a module of the Pluto project. The following listing describes each of the modules:

  • maven-pluto-plugin—A maven plugin for Pluto. The plugin is used by the utilities subproject to install the Pluto portal and deploy portlets.
  • pluto-container—The Pluto Portlet Container libraries
  • pluto-deploy—Deployment libraries for the Pluto Portal Driver
  • pluto-descriptor-api—The domain model and services interfaces for the Pluto descriptor library.
  • pluto-descriptor-impl—The default implementation of the services interfaces of the Pluto descriptor library.
  • pluto-portal—The user interface components of the Pluto Portal.
  • pluto-portal-driver—The Pluto portal driver libraries.
  • pluto-site—The Pluto Web site and documentation.
  • pluto-testsuite—The Pluto Testsuite portlet application.
  • pluto-util—The Pluto Utilities.

All modules of Pluto are built by executing the install Maven2 lifecycle.

cd <pluto-home>
m2 install

This command will build a single artifact for each module and place it within the local Maven repository. Artifacts also may be found in <module-root>/target.

Installing Pluto into Tomcat

After building Pluto, it must be installed within a servlet container. The easiest way to do this is to use Apache Tomcat and the Pluto installation utility. For Tomcat installation instructions, see Tomcat Documentation. Once installed, Pluto can easily be installed by executing the following commands.

cd <pluto-home>/pluto-util
m2 pluto:install

Deploying Portlets

Deploying portlets is currently a two step process in Pluto 1.1. First, portlets must be assembled. Assembly takes a compliant portlet application and injects hooks so that it can be deployed within the Pluto portal and serviced by the Pluto Portlet Container. Portlet assembly can be accomplished by executing:

cd <pluto-home>/pluto-util
m2 pluto:assemble -Dmaven.deploy.deployment=<path-to-war>

Once Pluto has been installed, portlets are deployed by executing the following commands.

cd <pluto-home>/pluto-util
m2 pluto:deploy -Dmaven.deploy.deployment=<path-to-war>


To ease adoption of the Portlet Specification, Apache Pluto implements more than just the required Portlet container. Pluto is also includes a lightweight portal implementation which can be used for developing portlets or embedded within a complex web application. The Pluto utilities offer means for quickly installing the portal, assembling portlet applications and deploying them within the Pluto portal. While Pluto 1.1 is still in it's infancy, it is easy to use, simple to customize, ideal for a lightweight portlet development environment.

About the Author

David DeWolf has been developing web applications, portals and portlet applications for six years. He is a member of the Apache Portals Project Management Committee and an active commiter to Apache Pluto, the reference implementation of the Portlet Specification. David currently works at Digital Focus. Digital Focus provides software development, agile coaching, and IT consulting services to Fortune 1000 and medium-sized businesses. Contact David at

Mobile Site | Full Site
Copyright 2017 © QuinStreet Inc. All Rights Reserved