What is a Portlet?
"Portlets are web
components--like servlets--specifically designed to be aggregated in the
context of a composite page. Usually, many portlets are invoked to in the
single request of a portal page. Each portlet produces a fragment of markup
that is combined with the markup of other portlets, all within the portal page
markup.
The Portlet specification
defines a portlet as a "Java-technology-based web component,
managed by a portlet container that processes requests and generates dynamic
content.
Portlets are
individual classes that process requests from a user and return content for
display inside a portal.
A portlet is a class
that implements the javax.portlet.Portlet
interface and is packaged and deployed as a .war file inside of a portlet
container.
Portlets
provide some additional functionalities:
1. Persistent
storage for preferences: Portlets
provide a PortletPreferences object for storing user preferences. These
preferences are stored in a persistent data store, so they will be available
across server restarts. As a developer, you don't have to worry about the
actual implementation of how it is stored.
2. Request
processing: Portlets provide much more refined
request handling. A portlet may get a request when user takes some action on it
(a state called action phase), or because the user took action on some
other portlet and the page needs to be refreshed. A portal server provides
different callback methods for handling both situations.
3. Portlet
modes: Portlets use a concept of mode
to indicate what user is doing. When using a mail application, you may be using
it for reading, composing, or checking mail messages--this is the expected
functionality of a mail application. Portlets normally provide this in VIEW
mode. But there are other activities, like specifying a refresh time or
(re-)setting the username and password. These activities allow the user to
configure the behavior of the application, so they come under EDIT mode. Help
functionality of the mail application comes under HELP mode.
If
you think about it, you will find none of these represents new functionality.
Instead, most of these are common business requirements. The only thing the
portlet specification is doing is providing you one layer of abstraction, so
that it will be useful for all stake holders end users, developers and
administrators.
As
a developer, I put all my business logic related to VIEW mode in a method
called doView(), and I put business logic related to the configuration of my
application in a doEdit() method, with help-related logic in a doHelp() method.
This
makes it simple for an administrator to control access in the portlet
application, because all he has to do is change access rights of the portlet to
dictate what things a user is allowed to do. For example, a user of a mail
application is supposed to specify his username and password in EDIT mode, so
it makes sense for him to have access to EDIT mode.
But
consider the case where I am the administrator of an intranet site and my
company bought a third-party portlet application that displays news updates.
This application allows a user to specify the URL from where it can retrieve
updates. I want to use this application for displaying internal company news to
users. Another requirement is that I don't want users to use this application
for tracking any other news source. So as the administrator, I can specify the
URL of an internal news update site for all users, and take out their edit
privileges by changing the deployment descriptor of this portlet application.
Using
portlets makes my website much more appealing to the end user because she will
get a similar UI for all her portlet applications. If she wants to read help
information about any of the applications, she can click the help button. She
will also know that clicking on an edit button will take her to a configure
screen for that application. Standardizing the user interface will make your
portlet application more appealing.
4. Window
state: The window state determines how
much space should be given to content generated by a portlet on a portal page.
If you click on the maximize button, the portlet will take up the entire screen
and it will become the only portlet that will be available to the user. In
minimized state, the portlet will be displayed as only a title bar. As a
developer, you should customize your content based on the space available to
you.
5.
User
information: Commonly, portlets provide content
personalized to the user making the request. To do this effectively, they may
require access to user attributes such as name, email, phone, etc. The Portlet
API provides the concept of user attributes for this. A developer can
access these attributes in a standard way, and it is the responsibility of the
administrator to map these attributes to an actual user information repository
(usually an LDAP server).
What is a Portal?
In order to
understand what a portlet is, it is very necessary to understand what a portal
is. According to the Portlet Specification, "a portal is a web application
that commonly provides personalization, single sign on, content aggregation
from different sources, and hosts the presentation layer of information
systems. Aggregation is the act of integrating content from different sources
within a web page."
Portal functionality can be divided into
three main parts:
1. Portlet
container:
A portlet container is very similar to a servlet container, in that every
portlet is deployed inside a portlet container that controls the life cycle of
the portlet and provides it with necessary resources and information about its
environment. A portlet container is responsible for initializing and destroying
portlets and also for passing user requests to it and collecting responses.
2. Content aggregator: As defined in
the Portlet Specification, one of the main jobs of a portal is to aggregate
content generated by various portlet applications. We will talk more about this
in the "How a Portal
Page is Created"
section.
3. Common
services:
One of the main strengths of a portal server is the set of common services that
it provides. Services are not part of the portlet specification, but commercial
portal implementations provide a rich set of common services to distinguish
themselves from their competitors. A few common services that you can hope to
find in most implementations are:
o Single sign on: Allows you to get access to all other applications once you log into
the portal server, meaning you don't have to log into every application
separately. For example, once I log in to my intranet site, I should get access
to my mail application, IM messaging application, and other intranet
applications, without having to log into each of these applications separately.
A
portal server will provide you with a secured credentials store. What
you do is to go to the mail application and specify your user name and password
once. This information will be stored in the credentials store in encrypted
form. From the next time onwards, when you log into your intranet site, the
portal server will read your credentials from the store and log into your mail
server on your behalf. The same goes for other applications.
o Personalization: The basic implementation of personalization service
allows a user to customize her page in two ways. First, the user can decide
what colors she wants for title bars and what icons she wants for controls.
Second, the user can decide which portlets she wants on her page. For example,
if I'm a big sports fan, I will probably replace the stock and news update
portlets with a portlet that lets me track my favorite team.
There
are also a few advanced commercial implementations of personalization services
that allow you to decide which applications should be displayed to user based
on criteria such as his income or interests. In this case, you can create some
business rules like "Show the premium products portlet to any user with X
amount of income" and "Show the discount deals portlet to users with
Y amount of income."
Portlet Application
Portlet applications are standard
J2EE web applications that include portlet classes and the portlet.xml portlet deployment
descriptor.
Portlet Container
- The
lifecycle of a portlet is managed by the portlet container. A portlet
container runs portlets and provides them with the required runtime
environment. A portlet container contains portlets and manages their
lifecycle. It also provides persistent storage for portlet preferences. A
portlet container receives requests from the portal to execute requests on
the portlets hosted by it.
- A
portlet container is not responsible for aggregating the content
produced by the portlets. It is the responsibility of the portal to handle
the aggregation
- A
portal and a portlet container can be built together as a single component
of an application suite or as two separate components of a portal
application.
- The
portlet container is an extension of the servlet container. As such, a
portlet container can be built on top of an existing servlet container or
it may implement all the functionality of a servlet container. Regardless
of how a portlet container is implemented, its runtime environment is
assumed to support at least Servlet Specification 2.4.
Portal Page Creation
·
A client (e.g., a web browser) makes
an HTTP request to the portal
·
The request is received by the
portal
·
The portal determines if the request
contains an action targeted to any of the portlets associated with the portal
page
·
If there is an action targeted to a
portlet, the portal requests the portlet container to invoke the portlet to
process the action.
·
A portal invokes portlets, through
the portlet container, to obtain content fragments that can be included in the
resulting portal page
·
The portal aggregates the output of
the portlets in the portal page and sends the portal page back to the client
Elements of a Portal Page
- A portlet generates markup fragments.
- A
portal may add a title, control buttons and other decorations to the markup fragment generated by the
portlet, this new fragment is called a portlet window.
- Then the portal may aggregate
portlet windows into a complete document, the portal page.
Portlet lifecycle
The Portlet interface is the main abstraction of the
Portlet API. All portlets implement this interface either directly or, more
commonly, by extending a class that implements the interface
The Portlet API includes a GenericPortlet class that
implements the Portlet, EventPortlet and ResourceServingPortlet interface and
provides default functionality. Developers should typically extend, directly or
indirectly, the GenericPortlet class to implement their portlets.
1.
Init
void init(PortletConfig config) throws PortletException
Called
by the portlet container to indicate to a portlet that the portlet is being
placed into service.
The
portlet container calls the init
method exactly once after instantiating the portlet. The init
method must complete successfully before the portlet can receive any requests.
The
portlet container cannot place the portlet into service if the init
method
1.
Throws
a PortletException
2.
Does
not return within a time period defined by the portlet container.
Parameters:
config
- a PortletConfig object
containing the portlet's configuration and initialization parameters
Throws:
PortletException
- if an exception has occurred that interferes with the portlet's normal
operation.
2.
Render
void render(RenderRequest request,RenderResponse response)
throws PortletException, java.io.IOException
Called
by the portlet container to allow the portlet to generate the content of the
response based on its current state.
Parameters:
request
- the render request
response
- the render response
Throws:
java.io.IOException
- if the streaming causes an I/O problem
3.
processAction
void processAction(ActionRequest request, ActionResponse response)
throws PortletException,java.io.IOException
Called
by the portlet container to allow the portlet to process an action request.
This method is called if the client request was originated by a URL created (by
the portlet) with the RenderResponse.createActionURL()
method.
Typically,
in response to an action request, a portlet updates state based on the
information sent in the action request parameters. In an action the portlet
may:
·
issue
a redirect
·
change
its window state
·
change
its portlet mode
·
modify
its persistent state
·
set
render parameters
A
client request triggered by an action URL translates into one action request
and many render requests, one per portlet in the portal page. The action
processing must be finished before the render requests can be issued.
Parameters:
request
- the action request
response
- the action response
Throws:
java.io.IOException
- if the streaming causes an I/O problem
4.
destroy
void destroy()
Called
by the portlet container to indicate to a portlet that the portlet is being
taken out of service.
Before
the portlet container calls the destroy method, it should allow any threads
that are currently processing requests within the portlet object to complete
execution. To avoid waiting forever, the portlet container can optionally wait
for a predefined time before destroying the portlet object.
This
method enables the portlet to do the following:
- Clean
up any resources that it holds (for example, memory, file handles, threads)
- Make
sure that any persistent state is synchronized with the portlet current state
in memory.
Portlet Window
- A window state is an indicator of
the amount of portal page space that will be assigned to the content
generated by a portlet via the render method.
- The Portlet Specification
defines three window states, NORMAL, MAXIMIZED and MINIMIZED. The
WindowState class defines constants for these window states.
- The NORMAL window state
indicates that a portlet may be sharing the page with other portlets. It
may also indicate that the target device has limited display capabilities.
Therefore, a portlet should restrict the size of its rendered output in
this window state.
- The
MAXIMIZED window state is an indication that a portlet may be the only
portlet being rendered in the portal page, or that the portlet has more
space compared to other portlets in the portal page. A portlet may
generate richer content when its window state is MAXIMIZED.
- When a
portlet is in MINIMIZED window state, the portlet should only render
minimal output or no output at all.
By
default, normal window state is displayed when portlet is called.
In this example, i have mentioned three window
state. In process action method(called by edit mode) ,we can change portlet
mode and window state.
Sample Code:
Portlet.xml
<portlet-app>
<portlet>
<portlet-name>ninethExample</portlet-name>
<display-name
xml:lang="en">ninethExample</display-name>
<display-name>ninethExample</display-name>
<portlet-class>com.anand.ninethexample.NinethExamplePortlet</portlet-class>
<init-param>
<name>wps.markup</name>
<value>html</value>
</init-param>
<expiration-cache>0</expiration-cache>
<supports>
<mime-type>text/html</mime-type>
<portlet-mode>view</portlet-mode>
<portlet-mode>edit</portlet-mode>
<window-state>normal</window-state>
<window-state>minimized</window-state>
<window-state>maximized</window-state>
</supports>
<supported-locale>en</supported-locale>
<portlet-info>
<title>ninethExample</title>
<short-title>ninethExample</short-title>
<keywords>ninethExample</keywords>
</portlet-info>
</portlet>
<default-namespace>http://ninethExample/</default-namespace>
</portlet-app>
NinethExamplePortlet
package com.anand.ninethexample;
import java.io.*;
import javax.portlet.*;
public class NinethExamplePortlet extends GenericPortlet {
public static final String JSP_FOLDER =
"/_ninethExample/jsp/"; // JSP folder name
public static final String
VIEW_JSP =
"NinethExamplePortletView";
// JSP file name to be rendered on the view mode
public static final String
EDIT_JSP =
"NinethExamplePortletEdit";
// JSP file name to be rendered on the edit mode
public void init() throws PortletException{
super.init();
}
public void doView(RenderRequest request, RenderResponse
response) throws PortletException, IOException {
// Set the MIME type for the render
response
response.setContentType(request.getResponseContentType());
PortletRequestDispatcher rd =
getPortletContext().getRequestDispatcher(getJspFilePath(request, VIEW_JSP));
rd.include(request,response);
}
public void doEdit(RenderRequest request, RenderResponse
response) throws PortletException, IOException {
// Set the MIME type for the render
response
response.setContentType(request.getResponseContentType());
PortletRequestDispatcher rd =
getPortletContext().getRequestDispatcher(getJspFilePath(request, EDIT_JSP));
rd.include(request,response);
}
public void processAction(ActionRequest request,
ActionResponse response) throws PortletException, java.io.IOException {
response.setPortletMode(PortletMode.VIEW);
response.setWindowState(WindowState.MAXIMIZED);
}
Important Classes and Interface
Portlet (Interface)
public Interface Portlet
The Portlet interface is used by the
portlet container to invoke the portlets. Every portlet has to implement this
interface, either by directly implementing it, or by using an existing class
implementing the Portlet interface.
A
portlet is a Java technology-based web component. It is managed by the portlet
container and processes requests and generates dynamic content as response.
Portlets are used by portals as pluggable user interface components.
The
content generated by a portlet is called a fragment. A fragment is a piece of
markup (e.g. HTML, XHTML, WML) adhering to certain rules and can be aggregated
with other fragments into a complete document. The content of a portlet is
normally aggregated with the content of other portlets into the portal page.
The
portlet container instantiates portlets, manages their lifecycle and invoking
them to process requests. The lifecycle consists of:
- initializing the portlet using
using the init method
- request processsing
- taking the portlet out of
service using the destroy method
Request
processing is divided into two types:
- action requests handled through
the processAction method, to perform actions targeted to the portlet
- render requests handled through
the render method, to perform the render operation
GenericPortlet (Abstract Class)
public abstract class GenericPortlet
extends java.lang.Object
The
GenericPortlet class provides a default implementation for the Portlet
interface.
It
provides an abstract class to be subclassed to create portlets. A subclass of
GenericPortlet should either use one of the following annotations:
- @ProcessAction
- @ProcessEvent
- @RenderMode
or override at least one method,
usually one of the following:
- processAction, to handle action
requests
- doView, to handle render
requests when in VIEW mode
- doEdit, to handle render
requests when in EDIT mode
- doHelp, to handle render
request when in HELP mode
- init and destroy, to manage
resources that are held for the life of the servlet
Normally
there is no need to override the render or the doDispatch methods. Render
handles render requests setting the title of the portlet in the response and
invoking doDispatch. doDispatch dispatches the request to one of the doView, doEdit
or doHelp method depending on the portlet mode indicated in the request.
Portlets
typically run on multithreaded servers, so please note that a portlet must
handle concurrent requests and be careful to synchronize access to shared
resources. Shared resources include in-memory data such as instance or class
variables and external objects such as files, database connections, and network
connections.
PortletConfig (Interface)
public interface PortletConfig
The
PortletConfig interface provides the portlet with its configuration. The
configuration holds information about the portlet that is valid for all users.
The configuration is retrieved from the portlet definition in the deployment
descriptor. The portlet can only read the configuration data.
The
configuration information contains the portlet name, the portlet initialization
parameters, the portlet resource bundle and the portlet application context.
Method Summary
|
java.util.Map<java.lang.String,java.lang.String[]>
|
|
java.lang.String
|
|
java.lang.String
|
getInitParameter(java.lang.String name)
Returns a String
containing the value of the named initialization parameter, or null if the
parameter does not exist.
|
java.util.Enumeration<java.lang.String>
|
getInitParameterNames()
Returns the names
of the portlet initialization parameters as an Enumeration of String objects,
or an empty Enumeration if the portlet has no initialization parameters.
|
|
|
getPortletContext()
Returns the
PortletContext of the portlet application the portlet is in.
|
java.lang.String
|
|
java.util.Enumeration<javax.xml.namespace.QName>
|
getProcessingEventQNames()
Returns the
QNames of the processing events supported by the portlet as an Enumeration of
QName objects, or an empty Enumeration if the portlet has not defined any
processing events.
|
java.util.Enumeration<java.lang.String>
|
getPublicRenderParameterNames()
Returns the names
of the public render parameters supported by the portlet as an Enumeration of
String objects, or an empty Enumeration if the portlet has not defined public
render parameters.
|
java.util.Enumeration<javax.xml.namespace.QName>
|
getPublishingEventQNames()
Returns the
QNames of the publishing events supported by the portlet as an Enumeration of
QName objects, or an empty Enumeration if the portlet has not defined any
publishing events.
|
java.util.ResourceBundle
|
getResourceBundle(java.util.Locale locale)
Gets the resource
bundle for the given locale based on the resource bundle defined in the
deployment descriptor with resource-bundle tag or the inlined resources
defined in the deployment descriptor.
|
java.util.Enumeration<java.util.Locale>
|
getSupportedLocales()
Returns the
locales supported by the portlet as an Enumeration of Locale objects, or an
empty Enumeration if the portlet has not defined any supported locales.
|
PortletContext (Interface)
public interface PortletContext
The PortletContext
interface defines a portlet view of the portlet container. The PortletContext
also makes resources available to the portlet. Using the context, a portlet can
access the portlet log, and obtain URL references to resources.
There is one
context per "portlet application" per Java Virtual Machine. (A
"portlet application" is a collection of portlets, servlets, and
content installed under a specific subset of the server URL namespace, such as /catalog.
They are possibly installed via a .war
file.) As a web application, a portlet application also has a servlet context.
The portlet context leverages most of its functionality from the servlet
context of the portlet application.
Attributes stored
in the context are global for all users and all components in the
portlet application.
In the case of a
web application marked "distributed" in its deployment descriptor,
there will be one context instance for each virtual machine. In this situation,
the context cannot be used as a location to share global information (because
the information is not truly global). Use an external resource, such as a
database to achieve sharing on a global scope.
PortletPreferences (Interface)
public interface PortletPreferences
The PortletPreferences
interface allows the portlet to store configuration data. It is not the purpose
of this interface to replace general purpose databases.
There are two
different types of preferences:
- modifiable
preferences - these preferences can be changed by the portlet in any
standard portlet mode (
EDIT,
HELP, VIEW). Per default every preference is modifiable.
- read-only
preferences - these preferences cannot be changed by the portlet in any
standard portlet mode, but may be changed by administrative modes.
Preferences are read-only, if these are defined in the deployment
descriptor with
read-only set to true, or if the portlet container restricts
write access.
Changes are
persisted when the store method is
called. The store method can
only be invoked within the scope of a processAction
call. Changes that are not persisted are discarded when the processAction
or render method ends.
Method Summary
|
java.util.Map<java.lang.String,
java.lang.String[]>
|
getMap()
Returns a Map of
the preferences.
|
java.util.Enumeration<java.lang.String>
|
getNames()
Returns all of
the keys that have an associated value, or an empty Enumeration if no keys
are available.
|
java.lang.String
|
getValue(java.lang.String key,
java.lang.String def)
Returns the first
String value associated with the specified key of this preference.
|
java.lang.String[]
|
getValues(java.lang.String key,
java.lang.String[] def)
Returns the
String array value associated with the specified key in this preference.
|
boolean
|
isReadOnly(java.lang.String key)
Returns true, if
the value of this key is defined as read-only and thus cannot be modified by
the user.
|
void
|
reset(java.lang.String key)
Resets or removes
the value associated with the specified key.
|
void
|
setValue(java.lang.String key,
java.lang.String value)
Associates the
specified String value with the specified key in this preference.
|
void
|
setValues(java.lang.String key,
java.lang.String[] values)
Associates the
specified String array value with the specified key in this preference.
|
void
|
store()
Commits all
changes made to the preferences via the set methods in the persistent store.
|
EventPortlet (Interface)
public interface EventPortlet
The
EventPortlet interface allows portlets receiving events.
Events
are part of the action processing and must be finished before the rendering
phase can start. Portlets can receive events issued by other portlets or
portlet container defined events.
Portlets
should declare the events it would like to receive via the
supported-processing-event tag and events published via the
supported-publishing-event tag in the portlet deployment descriptor.
The
event model is a loosely coupled model where the wiring between published and
receiving events is done at the portal / portlet container level.
ActionRequest
(Interface)
The
ActionRequest represents the request sent to the portlet to handle an action.
It extends the ClientDataRequest interface and provides action request
information to portlets.
The
portlet container creates an ActionRequest object and passes it as argument to
the portlet's processAction method.
ActionResponse (Interface)
public interface ActionResponse extends StateAwareResponse
The
ActionResponse
interface represents the portlet response to an action request. It extends the
StateAwareResponse
interface to provide specific action response functionality to portlets.
The portlet container creates an
ActionResponse
object and passes it as argument to the portlet's
processAction
method.
RenderRequest (Interface)
public interface RenderRequest extends PortletRequest
The RenderRequest
represents the request sent to the portlet to handle a render. It extends the
PortletRequest interface to provide render request information to portlets.
The portlet container creates a RenderRequest
object and passes it as argument to the portlet's render
method.
RenderResponse (Interface)
public interface RenderResponse
extends MimeResponse
The
RenderResponse
defines an object to assist a portlet in sending a response to the portal. It
extends the
MimeResponse
interface to provide specific render response functionality to portlets.
The portlet container creates a
RenderResponse
object and passes it as argument to the portlet's
render
method.
PortletURL (Interface)
public interface PortletURL extends BaseURL
The PortletURL
interface represents a URL that reference the portlet itself.
A PortletURL is
created through the RenderResponse or ResourceResponse.
Parameters, a portlet mode, a window state and a security level can be added to
PortletURL objects.
There are two
types of PortletURLs:
- Action
URLs, they are created with
createActionURL,
and trigger an action request followed by a render request.
- Render
URLs, they are created with
createRenderURL,
and trigger a render request.
The string
representation of a PortletURL does not need to be a valid URL at the time the
portlet is generating its content. It may contain special tokens that will be
converted to a valid URL, by the portal, before the content is returned to the
client.
|
|
|
|
getPortletMode()
Returns the
currently set portlet mode on this PortletURL.
|
|
|
getWindowState()
Returns the
currently set window state on this PortletURL.
|
void
|
|
void
|
setPortletMode(PortletMode portletMode)
Indicates the
portlet mode the portlet must be in, if this portlet URL triggers a request.
|
void
|
setWindowState(WindowState windowState)
Indicates the
window state the portlet should be in, if this portlet URL triggers a
request.
|
PortletRequestDispatcher (Interface)
public interface PortletRequestDispatcher
The PortletRequestDispatcher
interface defines an object that receives requests from the client and sends
them to the specified resources (such as a servlet, HTML file, or JSP file) on
the server. The portlet container creates the PortletRequestDispatcher
object, which is used as a wrapper around a server resource located at a
particular path or given by a particular name.
Method Summary
|
void
|
|
void
|
|
void
|
|
PortletSession (Interface)
public interface PortletSession
The PortletSession
interface provides a way to identify a user across more than one request and to
store transient information about that user.
A PortletSession
is created per user client per portlet application.
A portlet can bind
an object attribute into a PortletSession
by name. The PortletSession
interface defines two scopes for storing objects:
APPLICATION_SCOPE PORTLET_SCOPE
All
objects stored in the session using the APPLICATION_SCOPE
must be available to all the portlets, servlets and JSPs that belongs to the
same portlet application and that handles a request identified as being a part
of the same session. Objects stored in the session using the PORTLET_SCOPE must be
available to the portlet during requests for the same portlet window that the
objects where stored from. Attributes stored in the PORTLET_SCOPE are not
protected from other web components of the portlet application. They are just
conveniently namespaced.
The portlet
session is based on the HttpSession.
Therefore all HttpSession
listeners do apply to the portlet session and attributes set in the portlet
session are visible in the HttpSession
and vice versa.
