Listeners
The Portlet API provides listeners, which can add more functionality for a portlet. To enable the listener's functionality, one of the following interfaces must be implemented by the portlet.
- PortletSessionListener
- PortletPageListener
- PortletTitleListener
- PortletSettingsAttributesListener
- PortletApplicationSettingsAttributesListener
PortletSessionListener
In addition to the concrete portlet instance, which exists for each portlet occurrence on a page, a portlet may have an even finer granularity. The PortletSessionListener allows a portlet to recognize the life cycle of a user portlet instance:
- login()
After a user logs in to a portal, each portlet creates a session for the user. The combination of the concrete portlet instance and the user session creates the user portlet instance. The start of a user instance is signaled by the portal calling the login() method at the portlet. This method allows the portlet to initialize the user's session instance of the portlet, for example, to store attributes in the session.
- logout()
When the user ends the session with the portal, the portal server calls the logout() method to inform the portlet that the user's session instance is terminating. The portlet should then clean up any resources for the portlet user instance. This could include cleaning up, if necesary, the authentication state of the user or cookies that might have been placed on the browser by the portlet. At a minimum, any state on the backend application should be cleaned up or marked as terminated to prevent any remaining cookies on a subsequent request from being used.
PortletPageListener
A portlet has no control or awareness of the order in which the output from all of the portlets on the page is written. The PortletPageListener allows a portlet to insert markup at the beginning and ending of a page.
- beginPage()
At the beginning of each page and before any service() method of any portlet on the page is called, the beginPage() method is called for each portlet residing on the page. Like the service() method, the beginPage() method for each portlet on the page is not called in a guaranteed order and can even be called in a different order for each request. The output of beginPage() is inserted into the page aggregation area prior to the rendering of portlets on the page.
This method allows a portlet to output Javascript that is visible to all portlet's service() methods or even to set cookies or headers. This method cannot be used to add output to the <HEAD> section of the portal page or redirect the portal page. Instead, the output written in the beginPage() is added as the very first entry after the <BODY> tag.
- endPage()
At the end of each page, and after all service() methods of all portlets on the page are called, the endPage() method is called for each portlet residing on the page. Like the service() method, the endPage() method is not called in a guaranteed order and can even be called in a different order for each request. For example, the portlet can insert Javascript to the end of the page that needs to occur after all other elements of the page have been written.
These methods are called if the <wps:pageRender/> tag includes the attributes includeBeginPage="yes" and includeEndPage="yes". The <wps:pageRender/> tag can be found in the file Home.jsp in the /screens directory.
Listener life cycle
When implementing PortletSesssionListener and PortletPageListener, the following methods are called on the portlet during its life cycle.
- init()The non-concrete portlet is initialized with PortletConfig.
- initConcrete()The concrete portlet is initialized with PortletSettings.
- login()The user portlet instance is initialized with PortletSession.
- beginPage()The portlet may render output at the beginning of each page for each request.
- service()The portlet may render output in the portlet window for each request.
- endPage()The portlet may render output at the end of each page for each request.
- logout()The user portlet instance is destroyed.
- destroyConcrete()The concrete portlet is destroyed.
- destroy()The non-concrete portlet is destroyed.
PortletTitleListener
The PortletTitleListener interface is used to allow the portlet title, as it is displayed in the title bar, to be changed based on a condition (for example, the type of device used to access the portal) or user input (for example, a preference that the user sets on the edit page). If the Listener is not implemented, the portlet displays the title specified on the <title> element (under <language>) of the portlet deployment descriptor.
PortletSettingsAttributesListener
This interface listens for changes to the attributes of the PortletSettings, like when an administrator configures a concrete portlet.
PortletApplicationSettingsAttributesListener
This interface listens for changes to the attributes of the PortletApplicationSettings, like when an administrator configures a concrete portlet application.
See also