Portal and Portlet Configuration

185
CHAPTER 7
Portal and Portlet
Configuration
T
HE PORTLET
API
DEFINES
several interfaces for working with preferences and set-
tings for the portal, the portlet application, and the current user of the portlet.
Portlets access information about the portal that they are currently running in
through the
PortalContext
object. The configuration settings for the application
are available from the
PortletConfig
class. The portlet accesses and persists indi-
vidual settings and preferences transparently with the
PortletPreferences
object.
In a typical portlet application, each user has preferences or configuration
information that should be stored. You can use portlet preferences instead of
creating a database table and code for each user. The portal may use a database
or another form of storage to store the preferences, but the portlet does not need
to know the details. Portlets that use proprietary portal features will have to
determine whether the portal supports them with the portal context. You can use
the
PortletConfig
class to determine any deployment-specific data for the applica-
tion. Another information source is the
PortletContext

class, which we covered
in Chapter 4. This class provides context-wide initialization parameters.
In this chapter, we are going to demonstrate how to use the portal context
and portlet configuration and preferences to access configuration information
from a portlet.
Using the PortalContext to Retrieve Information
About the Portal
You retrieve information about the portal with the
PortalContext
object. In the cur-
rent version of the portlet API, all of the portal information is read-only, so it is not
possible to create nonproprietary administrative or management portlets just yet.
Vendors could provide their own interfaces to set portal configuration data, or they
could just bundle their own administrative portlets. Less-sophisticated portals will
probably rely on administrators changing text or XML configuration files manually.
The portal’s internal configuration store is not directly accessible through the
portlet API.
Portlets use the
PortalContext
object to determine which features beyond the
portlet specification the portal supports. For instance, you may be able to develop
a portlet that supports a custom mode for portlets if it is available, but otherwise
2840ch07.qxd 7/13/04 12:44 PM Page 185
Download at Boykma.Com
Chapter 7
186
defaults to making that content available through a link from the default VIEW
mode.
All portlets have access to the
PortalContext

for the portal they are run-
ning in. The
PortalContext
object is made available to a portlet through the
getPortalContext()
method on the
PortletRequest
object:
public PortalContext getPortalContext()
Portlets access portal properties, supported modes, supported window states,
and the name and version number of the portal software through the portal
context.
Portal Properties
Each portal has a collection of portal properties, which contain information about
the portal. Each portal vendor decides which portal properties to implement.
Developers should not confuse portal properties with request properties. Each
property is a name/value pair of
String
objects. The portal provides an
Enumeration
of all available property names:
public Enumeration getPropertyNames()
The portlet retrieves the value for a property using the
getProperty()
method:
public String getProperty(String name)
The getProperty() method returns null if there is no property with that name,
and it throws an IllegalArgumentException if the
name
argument passed in is null.

Here is an example that will display all of the available portal properties in
a portlet. The portlet API does not provide a way to let you modify these properties
yet, so this portlet would only be useful for diagnostics:
package com.portalbook.portlets;
import java.io.IOException;
import java.io.Writer;
import java.util.Enumeration;
import javax.portlet.GenericPortlet;
import javax.portlet.PortalContext;
import javax.portlet.PortletException;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;
public class PortletConfigPortlet extends GenericPortlet
{
2840ch07.qxd 7/13/04 12:44 PM Page 186
Download at Boykma.Com
Portal and Portlet Configuration
187
protected void doView(RenderRequest request, RenderResponse response)
throws PortletException, IOException
{
response.setContentType("text/html");
Writer writer = response.getWriter();
writer.write("<H2>Available Portal Properties</H2>");
//get the Portal Context
PortalContext portalContext = request.getPortalContext();
//get the available portlet propertyNames
Enumeration availablePropNames = portalContext.getPropertyNames();
//check to see if there are more than zero property names
if (!availablePropNames.hasMoreElements())

{
writer.write("There are no portal properties defined.<BR>");
}
//iterate through the property names, and output them
while (availablePropNames.hasMoreElements())
{
String name = (String) availablePropNames.nextElement();
if (name != null)
{
String value = portalContext.getProperty(name);
if (value != null)
{
writer.write(
"The value of property " + name +
" is " + value + "<BR>");
}
else
{
writer.write(
"There is not a property value defined for " +
name + "<BR>");
}
}
}
}
}
2840ch07.qxd 7/13/04 12:44 PM Page 187
Download at Boykma.Com
Chapter 7
188

Window States
Each portal vendor could support additional window states beyond the standard
three (maximized, minimized, normal) defined by the portlet API.
Your portlets check the portal’s defined window states through the
PortalContext
object by using the
getSupportedWindowStates()
method. This method will return an
Enumeration
of
WindowState
objects. If your portlet is going to support a proprietary
window state, check to see if the portal supports the window state with this method.
If possible, supply another way to access the functionality for portability.
public Enumeration getSupportedWindowStates()
For more on window states with portlets, see Chapter 4.
Portlet Modes
As with window states, portal vendors could have proprietary portlet modes
that go beyond the three standard portlet modes from the portlet API (EDIT,
HELP, VIEW).
A portlet also checks for supported portlet modes using the
getSupportedPortletModes()
method on the
PortalContext
object. This
method returns an
Enumeration
of
PortletMode
objects, one for each supported

portlet mode. As you would with window states, check this method for the
supported portlet modes of the portal vendor if you are going to use a non-
standard portlet mode:
public Enumeration getSupportedPortletModes()
If a portal supports a proprietary mode that corresponds to one of the func-
tions of your portlet, add support for this portlet mode in the
render()
method
of your base portlet. To support portals that do not have this mode, you can add
a navigation link to the appropriate screens of your portlet that will provide your
users with the same functionality but in the VIEW portlet mode. You could remove
this link inside portals that support a graphical user interface (GUI) mechanism
for switching to this portlet mode.
For more on portlet modes, see Chapter 4.
Portal Information
Portlets obtain the portal’s vendor name and version number of the software from
the
getPortalInfo()
method on the
PortalConfig
object:
2840ch07.qxd 7/13/04 12:44 PM Page 188
Download at Boykma.Com
Portal and Portlet Configuration
189
public String getPortalInfo()
The portal information will be similar to this: Jetspeed/2.0. The name of the
portal server software and the version number are required. The portal may
include optional information after the server name and version number, and
any optional portal information will be enclosed in parentheses.

The following example portlet will display the portal’s information to the user
in the VIEW portlet mode:
package com.portalbook.portlets;
import java.io.IOException;
import java.io.Writer;
import javax.portlet.GenericPortlet;
import javax.portlet.PortalContext;
import javax.portlet.PortletException;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;
public class PortalInfoPortlet extends GenericPortlet
{
protected void doView(RenderRequest request, RenderResponse response)
throws PortletException, IOException
{
response.setContentType("text/html");
Writer writer = response.getWriter();
writer.write("<H2>Portal Information</H2>");
//get the Portal Context
PortalContext portalContext = request.getPortalContext();
//get the available portal information
String portalInfo = portalContext.getPortalInfo();
writer.write("The portal this portlet is running under is: ");
writer.write(portalInfo);
}
}
2840ch07.qxd 7/13/04 12:44 PM Page 189
Download at Boykma.Com
Chapter 7
190

Using the PortletConfig Object
The portlet uses the
PortletConfig
object to access configuration information from
the portlet.xml deployment descriptor. Your portlets should retrieve any information
they need during the initialization stage in the portlet life cycle through the
init()
method on the
Portlet
interface. The
init()
method for a portlet takes a
PortletConfig
object as its argument:
public void init(PortletConfig portletConfig) throws PortletException
Portlets that extend
GenericPortlet
will implement the
PortletConfig
interface,
which allows the portlet to access its configuration data directly. The
GenericPortlet
keeps the
PortletConfig
object it is passed by the portlet container; this
PortletConfig
object is accessible through the
getPortletConfig()
method on
GenericPortlet

:
public PortletConfig getPortletConfig()
It is unlikely that you will be using this method much, however, since the
GenericPortlet
implements the
PortletConfig
interface by calling out to the cor-
responding methods on its configuration object.
The portlet configuration consists of initialization parameters and portlet
information, which could either be stored directly in the portlet.xml deployment
descriptor or in a specified resource bundle.
The portlet’s context is also accessed through the
getPortletContext()
method
on the
PortletConfig
object. You use the portlet context to access resources, log-
ging, and context attributes:
public PortletContext getPortletContext()
Because we covered the portlet context in Chapter 4, we are not going to cover
the same material in this chapter. Some functionality on the portlet context, such
as context attributes and the portlet API version, is relevant to portlet configuration.
For instance, the
getServerInfo()
method on the
PortletContext
interface returns
the portlet container’s name and version number. You could use this in case some
portlet containers are released with bugs that need workarounds.
Initialization Parameters

Initialization parameters specify configuration data for the portlet. You use them to
provide default values for file paths, connection data, or other deployment-specific
details. One point to note is that these are initialization parameters for all of the
2840ch07.qxd 7/13/04 12:44 PM Page 190
Download at Boykma.Com
Portal and Portlet Configuration
191
users of the portlet. User-specific configuration should be done with portlet
preferences, which we discuss at the end of this chapter.
The initialization parameters are stored in the portlet.xml deployment
descriptor. Each portlet could have zero or more initialization parameters. Each
parameter consists of a name, a value, and an optional description. String objects
represent both the name and the value.
Each
<init-param>
element in the portlet deployment descriptor represents
one initialization parameter. The
<init-param>
elements are children of the
<portlet>
element. The initialization parameters section of a portlet deployment descriptor
follows:
<portlet-app>
<portlet>
...
<init-param>
<name>connectionPort</name>
<value>9001</value>
</init-param>
<init-param>

<name>connectionServer</name>
<value>127.0.0.1</value>
</init-param>
...
</portlet>
</portlet-app>
A portlet accesses its initialization parameters through the
PortletConfig
object. The
getInitParameter(String name)
method takes the name of the initial-
ization parameter as its argument, and returns the value of the initialization
parameter as a
String
object. If the parameter does not exist in the deployment
descriptor, the method will return a null value. If the name passed in as an argu-
ment is null, the method will throw an
IllegalArgumentException
.
public String getInitParameter(String name)
Your portlets should be aware of the names of the initialization parameters
that they expect, but portlets can also retrieve the names of all of their initializa-
tion parameters. The
getInitParameterNames()
method on the
PortletConfig
object
returns an
Enumeration
object that contains string values for each of the names

of the initialization parameters. If no initialization parameters are defined, the
Enumeration
will be empty.
public Enumeration getInitParameterNames()
2840ch07.qxd 7/13/04 12:44 PM Page 191
Download at Boykma.Com
Chapter 7
192
Getting the Resource Bundle of Portlet Metadata
Each portlet has a set of metadata associated with it to provide the title of the port-
let, a shorter title for truncated displays, and keywords to describe the portlet in an
administration tool. You will probably not need to get the resource bundle directly
in your portlets—this information is most useful for the portal itself when it displays
the portal in the aggregated page or when it presents a catalog of portlets for the
user to choose from.
Either the metadata is specified directly in the deployment descriptor, or it
could be specified in a resource bundle. There could be more than one resource
bundle, and the portlet container will load the appropriate one based on the
specified locale. If you need to support a multiple-language deployment, use
resource bundles. The portlet container uses the standard rules for finding
a resource bundle based on locale.
The
<portlet-info>
XML element is used to hold metadata defined in the
portlet.xml deployment descriptor. Each
<portlet>
element may have one or none
<portlet-info>
elements as children. The
<portlet-info>

element has three children:
<title>
,
<short-title>
, and
<keywords>
. Each of these three elements should contain
the text for the value of the metadata. Here is an example excerpt of a portlet.xml
deployment descriptor with the
<portlet-info>
element:
<portlet-app>
<portlet>
...
<portlet-info>
<title>Patent Classification Browser</title>
<short-title>Classification</short-title>
<keywords>Taxonomy,Legal,Patents</keywords>
</portlet-info>
...
</portlet>
</portlet-app>
Instead of specifying the metadata in the portlet.xml deployment descriptor,
it is possible to create a resource bundle to store the information. This works well
for internationalization. The
<resource-bundle>
element in the portlet.xml deploy-
ment descriptor should contain the name of the resource bundle, for example:
<resource-bundle>com.portalbook.portlets.PatentPortlet</resource-bundle>
The portlet accesses a resource bundle from the

getResourceBundle(Locale locale)
method on the
PortletConfig
interface. For the portlet’s purposes, it does not
matter whether the information was specified in the portlet deployment descriptor
or the resource bundle. If the information is not found in the specified resource
bundle, the portal container will use the values defined in the portlet deployment
2840ch07.qxd 7/13/04 12:44 PM Page 192
Download at Boykma.Com
Portal and Portlet Configuration
193
descriptor. If there is no resource bundle, the portlet container will create one
from the inline portlet information values.
public java.util.ResourceBundle getResourceBundle(java.util.Locale locale)
There are three standard pieces of metadata in the first version of the portlet
specification: title, short title, and keywords. Expect more to be added in the
future as the specification evolves. The resource bundle keys and a description
are listed here:
• javax.portlet.title: The title to be displayed in the portlet’s title bar and
other places in the portal GUI.
• javax.portlet.short-title: This is a shorter version of the title for use on
truncated displays.
• javax.portlet.keywords: The keywords are a comma-separated list of words
or phrases that describe the portlet. The keywords can be used in a portlet
catalog so the user can find the appropriate portlet.
Here is an example showing the use of the resource bundle from a portlet:
package com.portalbook.portlets;
import java.io.IOException;
import java.io.Writer;
import java.util.Locale;

import java.util.ResourceBundle;
import javax.portlet.GenericPortlet;
import javax.portlet.PortletException;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;
public class ResourceBundlePortlet extends GenericPortlet
{
protected void doView(RenderRequest request, RenderResponse response)
throws PortletException, IOException
{
response.setContentType("text/html");
Writer writer = response.getWriter();
writer.write("<H2>Resource Bundle Values</H2>");
2840ch07.qxd 7/13/04 12:44 PM Page 193
Download at Boykma.Com