Understanding Portals and Portlets: Part One
Related Links: Understanding Portals and Portlets: Part Two
It used to be difficult if you wanted to create a Web-based site that offered users the ability to access various systems from a single page. Systems were too severely disjointed and required a huge investment of time and work in order to bring them together in a single Web page.
Although there are many efforts taking place in the Java arena to provide systems integration, none have made the same impact as portals.
Understanding the JSR 168 Specification
For portal software manufacturers, this JSR provides the details on how a portal should be developed, what interfaces and objects need to exist, the communication process and sequence that should occur, security, and much more. For the portlet developer, it provides the interfaces that need to be implemented and used, the lifetime and scope of the portlets, and other related details.
There is yet a third perspective in this whole story, that of the end user. The end user views a portal as a collection of portlets presented on a single portal page, produced from requests made to a portal site (see Figure 1).
As an example, if you surf over to http://my.yahoo.com, you can register to have a personalized page that presents you with the content you sign up for, all from a single portal page. As shown in Figure 2, the page provided me with a Message Center Portlet, an RSS Headlines Portlet, a Scoreboard Portlet, and several other portlets that I had signed up for.
Before continuing, let's make sure you understand the concepts and terms.
* Portals: An HTTP-based site hosted with special portal
software that allows the aggregation of several different back-end systems,
processes, or sites brought together through a single portal page. Portals may
provide additional services such as single sign-on security, customization,
personalization, and back-end administrative/declarative application
Figure 3 depicts the relationship among the entities specified above.
Since a portlet provides the rendering code for its portlet window, it's responsible for providing the implementation. However, most portlets will dispatch and rely on a JSP to provide the actual rendering code. Figure 4 shows the sequence as it applies to a portal page that has just received an action in one portlet. That portlet, along with the other portlets on the page, must also render themselves.
Servlets and Portlets
Portlets aren't directly tied to a particular URL. Instead, they use methods such as createActionURL() or createRenderURL() to construct a URL that is needed to allow a client to fire actions to retrieve renderings from the currently executing portlet. On the client side, clients aren't allowed to interact directly with a portlet. The requests or submissions are tunneled through the portal server. The URL has all the information that the portlet container needs to determine which portlet must be called and what type of functionality should be executed.
Two other very important differences are elaborately pronounced in the user interface. Anyone viewing a portal page for the first time will notice that they contain special adornments that can be utilized by users to minimize, normalize, or maximize the portlet window. Users also use the decorations to enter the Edit mode or View mode of the portlet (see Figure 5). Finally, portlets can exist on the same page multiple times. Most of the time, the user is given the ability to control which portlets show up on a particular portal page. This is known as personalization.
Although portlets can access both servlets or independent JSPs directly by including their output within the portlet's rendered output, the direct output of a servlet or an independent JSP should not be channeled back to a portal page unless the content is stripped of all of the offending HTML tags mentioned above. Dispatching is handled through a special object known as a PortletRequestDispatcher. Besides passing control directly to another portlet, servlet, or JSP, the portlet may choose to simply include the output from the entity, without losing the ability to provide further output appended to the end, essentially becoming an aggregator.
The Life of a Portlet
Within the deployment file that accompanies the portlet distribution file, the author can place initialization parameters, which can be pulled out by the portlet instances at runtime via the configuration object. This object can be pulled out by calling the GenericPortlet's getPortletConfig() method, which returns a PortletConfig object. Using this object, the author can access the initialization parameters by calling the object's getInitParameter() for each parameter that the portlet is interested in.
Portlets can also place titles and other pieces of information in accordance with the XML Schema into the deployment file. In addition, any displayable information can be kept in a resource bundle associated with the deployment descriptor file and be accessible at runtime. The values can be language-specific to assist in internationalizing the portlet.
Each time the client performs an action on a portlet, the portlet is invoked by the container via its processAction() method. When the portlet container finds it necessary to retrieve a viewing of the portlet, it calls the render() method. This method determines the type of view that should be rendered and calls one of three other methods: doHelp(), doView(), or doEdit(). These three methods should be overridden by the portlet author if the author expects to receive calls for any of these methods. The calling of these methods is controlled by the portlet author through the portlet deployment descriptors file (portlet.xml).
When the portlet container calls the action method of the portlet, there are two objects passed to it: first ActionRequest and, second, ActionResponse. Using the ActionRequest, the portlet can access the parameters of the request, the window state, the portlet mode, the portlet context, the session object, and the portlet preferences data.
The same two objects are sent to the render method of the portlet, except with slightly different names: RenderRequest and RenderResponse. Keep in mind that if you wish the parameters to become available in the render method or the resulting JSP, you'll need to move it there yourself using the ActionResponse.renderParameters() method, passing it the result of calling ActionRequest.getParameterMap(). You can later fetch the parameters from within the render method using RenderRequest.getParameter().
Remember the relationship between the URL used to invoke the portlet and the actual method that is called within the portlet. If you expect that an interaction from the user will result in a call to the portlet's processAction() method, you should call createActionURL() to have that type of URL created. For render requests, call createRenderURL().
When the portlet has completed its job, the container will call the portlet's destroy() method.
Preferences can be modified during the processAction()method and inspected during any of the render methods. Preferences are altered or viewed through the PortletPreferences object. The interface provides methods to retrieve, change, or store preferences. Since preferences can be read-only, there is also a method to check if a preference can be modified.
Changes to preferences aren't committed until the store() method is called. It may only be called during the processAction() method.
Preferences are initially defined within the portlet's deployment file and given a default value. In addition, developers may assign a validator object, which implements the PreferencesValidator interface. This object's implementation can verify that values assigned to preferences are legitimate. Otherwise, the validator can throw a ValidatorException. Developers are encouraged to include information in the exception regarding the preferences that failed.
Portlet Modes and Window States
In Edit mode, the portlet should present the user with the ability to customize whatever features are customizable for the portlet. For our stock portfolio portlet example, the portlet might present the ability to adjust the stocks in the portfolio, changing the colors to show up and/or down activity or changing the background color for the portlet.
The Help mode should display either a full description of how the portlet can be used (explaining both the View and Edit modes) or context-sensitive help explaining selected features of the portlet.
If the portlet wishes to determine which mode it's currently in when called, it can do so by calling the ActionRequest or RenderRequest objects' getPortletMode() method.
Portlets should specify their desire to handle any of the portlet modes by including the modes within the deployment descriptor's <supports> element.
The render() method will fall back to one of the three methods - doView(), doEdit(), and doHelp() - in order to have the portlet provide the implementation, depending on what portlet mode is currently in use. Most portal pages will provide the functionality that enables the users to choose which mode they wish to enter. This can be done by adornments placed on the title bar of the portlet.
The Window states allow the port-let to know the user's aspiration to have the portlet minimize its window, maximize its window, or normalize the window (bringing it from minimized or maximized mode). The portlet should always check what Window mode it's in before rendering data.
Portal Context and Session
Portlets can store session data associated with the user's active session. There are several ways in which a server process can store data for later use within the session. These include:
* HTTP cookies
The portlet specification provides the developer with an interface named PortletSession that hides the implementation details, providing a simple interface for managing the various data pieces in a session utilizing the above-mentioned methods. The portlet session is guaranteed to be the same session across all portlets that result from requests made by the user.
The portlet container can choose to use the requested portlet cache if resources permit; otherwise, it can shut down caching altogether. If the portlet container chooses to use caching, any request from the client to simply render content causes the portlet container to first check if the content has expired and, if it hasn't, returns the contents without calling any of the portlet's render methods. Otherwise, the methods are called once again, and the content is cached for later requests.
Putting the Pieces Together
The actual semantics for achieving this will differ from one portal vendor to another. For example, some vendors will provide an administrative tool that can be accessed to build the portal site, bringing together the portlets by allowing administrators/developers to search for the type of portlets they wish to offer users, and then providing the plumbing to make this all happen.
The end result of all the administrative effort will be a portal page deployment file or perhaps some kind of registry (which can even be handled via an LDAP system) to produce the resulting site. The portal then utilizes the information stored in these data stores to produce the site at runtime. The data stores might have information such as:
* The name of the portal class and its logical name
The portal may also maintain information about the individual pages, such as:
* Which portlets are included in what pages
These are just some of the pieces of information that a portal may potentially store as the site is administered.
Handle Your Threads
What Does the Future Hold?
* Filters: Similar to servlet filters - in fact, some vendors
have already implemented this optional feature using the same type of method
offered by servlets.
Next month, I'll be back to show you how to build an Image Viewer Portlet that will allow you to select images from the Web site you wish to view. In the process, you'll become acquainted with many of JSR 168's features, and also learn how to deploy portlets to Pluto.
Copyright ©1994-2005 SYS-CON Publications, Inc.
Questions or problems regarding this web site should be directed to firstname.lastname@example.org.
Copyright © 2008 Art Beckman. All rights reserved.
Last Modified: March 9, 2008