Advanced Portlet APIs

-Rahul Gupta

This section covers more advanced topics of the Portlet API, such as accessing user information, calling portal's context, localization, and caching.

User information
                Some portlets may want to personalize the produced markup depending on personal user information. Such information is called user profile information and contains details such as a user's name, address, email, and so on. For example, employing a user's profile, a weather portlet can present the weather for the city the current user lives in.
                   The Portlet API supports access to user profile information via the request attribute USER_INFO as a map. The Portlet Specification recommends using the P3P (Platform for Privacy Preferences) user attribute names. A portlet can define in the deployment descriptor which user information attributes it would like to access via this map in the request. The portal can then either map these attributes at deployment time to the attributes in its user datastore or ignore them if they are not supported.
                The user information is always about the user triggering the current action and may differ from the J2EE principal, as the portlet could be called as a remote portlet. If the portlet is called as remote (a WSRP producer), the J2EE principal represents the calling WSRP consumer and not the user triggering the request.

Portal Context
To let portlets adapt to the portal that calls them, the Portlet API provides the PortalContext, which can be retrieved from the request. This portal context provides information such as the portal vendor, the portal version, and specific portal properties. The information allows the portlet to use specific vendor extensions when being called by a portal that supports these extensions and, when being called by other portals, to return to some simpler default behavior. As the portal context is attached to the request, it may change from request to request. This can be the case in the remote scenario, where one portlet (WSRP provider) may be called from different portals (WSRP consumers).

Localization
                          The Portlet Specification provides localization on two levels: deployment descriptor and portlet. On the deployment descriptor level, all settings intended to be viewed or changed by the Web server administrator (portlet description, init parameters, display name, and so on) consist of an xml:lang attribute, like the Servlet 2.4 deployment descriptor. The xml:lang tag provides the same tag with descriptions in different languages (e.g., a display name in English, German, and Japanese).
On the portlet level, the specification sets a resource bundle class in the deployment descriptor that contains the portlet title's localized versions, the short title for graphically restricted devices, and keywords describing the portlets' functionalities. In addition to this information, the specification also recommends a notation for localizing the preference attribute display names, values, and descriptions. The portlet can access the resource bundle via the PortletContext's getResourceBundle() method.

Caching
               JSR 168 defines support for expiration-based caching, both declaratively and programmatically. In the deployment descriptor, the portlet response's expiration time can be defined per portlet. During runtime, the portlet can set an expiration time for the render response using the EXPIRATION_CACHE property.
Any request targeted to this portlet automatically expires the cached content. This means that when a user clicks on this portlet's action or render link, the portlet gets called independently of the remaining cache expiration time.  

Extensibility
                    The Portlet Specification has several mechanisms that allow portal vendors to include their specific extensions. This section explains the most important mechanisms: vendor-specific properties, custom portlet modes, and custom window states. As explained in the "Portal Context" section, the portlet can obtain information about a portal's supported extensions via the portal context.
Properties
                  Properties communicate vendor-specific settings between the portlet and portlet container, and between the portlet and the portal.
These properties show up in several places in JSR 168. The portlet can read String properties with getProperty() from:
• ActionRequest, to receive properties that are action-request specific
• RenderRequest, to receive properties that are render-request specific
• PortalContext, to receive properties that are portal specific and do not change for different requests
The portlet can write String properties with setProperty() to:
• ActionResponse, to set properties in response to an action request
• RenderResponse, to set properties in response to a render request

Custom portlet modes and window states
                                If a portlet application uses additional portlet modes or window states than the ones defined by the Portlet Specification, the portlet application can declare them in the deployment descriptor. At deployment time, the defined custom portlet modes and window states are either mapped to vendor-specific portlet modes and window states the current portal supports, or ignored. A portlet can use only portlet modes or window states supported by the portal running the portlet. The portlet can use the PortalContext's getSupportedPortletModes() and getSupportedWindowStates() methods to retrieve the portlet modes and window states the portal supports.
The portlet can define custom portlet modes and window states in the deployment descriptor by using the custom-portlet-mode and custom-window-state tags.

Packaging and deployment
                 A portlet application's resources, portlets, and deployment descriptors are packaged together in one Web application archive (war file). In contrast to servlet-only Web applications, portlet applications consist of two deployment descriptors: one to specify the Web application resources (web.xml) and one to specify the portlet resources (portlet.xml). All Web resources that are not portlets must be specified in the web.xml deployment descriptor. All portlets and portlet-related settings must be specified in an additional file called portlet.xml. There are three exceptions to this rule, which are all defined in the web.xml, as they are valid for the whole Web application:
1. The portlet application description
2. The portlet application name
3. The portlet application security role mapping
                                    As result of the two deployment descriptor files, portlet application deployment is a two-step deployment that deploys the Web application into the application server and the portlets into the portal server.
                                 A portlet.xml file always describes only one specific portlet application. To create a copy of a portlet application with slightly different settings, a new portlet application must be created.

Figures 1 and 2 depict the portlet.xml file's complete schema definition.
Figure 1 shows the settings that can be applied on the application level,

Figure 2 depicts the settings on the portlet level.