Core objects
The following objects are most often used by a portlet:
Each of these objects is an extension of its counterpart in the Servlet API.
PortletRequest
The PortletRequest object is passed to the portlet through the login(), beginPage(), endPage() and service() methods, providing the portlet with request-specific data and the opportunity to access further important information as listed below.
- Attributes
- Attributes are name/value pairs associated with a request. Attributes are available only for the scope of the request. The portlet can get, set, and remove attributes during one request.
- Parameters
- Parameters are name/value pairs sent by the client in the URI query string as part of a request. Often the parameters are posted from a form. Parameters are available for the scope of a specific request. The portlet can get but not set parameters from a request.
- Client
- The Client object encapsulates request-dependent information about the user agent of a specific request. Information from the Client includes the manufacturer of the user agent or the type of markup that the client supports. The Client is extracted from the PortletRequest using the getClient() method. The following information can be obtained from the Client:
- User agent
- Portlet can get the String sent by the user agent to identify itself to the portal.
- Markup name
- Portlet can get the String that indicates the markup language that the client supports, for example, "wml".
- MIME type
- Portlet can get the String that indicates the MIME types supported by the client (for example: text/vnd.wap.wml). If the portlet supports multiple types of devices, it should get the markup name rather than the MIME type. The following table shows MIME types and their corresponding markup types. Retrieving MIME type does not distinguish between HTML and cHTML markup.
MIME types Markup types Text/html html Text/vnd.wap.wml wml Text/html chtml - Capabilities
- The Capability object contains more detailed information than the markup type about what the client can support, such as the level of HTML, JavaScript, or WML tables.
- User data
- The PortletData object represents data for a concrete portlet instance that is saved to persistent store. For example, a user can set a portlet e-mail application to check for new mail every 30 minutes. This preference is stored for the instance in the PortletData object.
- Session
- The PortletSession represents user-specific, transient data for more than one request. In contrast with the request, which does not retain data after the request is completely processed, session attributes can be remembered/saved over more than one request.
- Portlet settings
- The PortletSettings object represents the configuration for a concrete portlet that is saved to persistent store. For example, an administrator can set to which host and port a Stock portlet should connect to get live data. This preference is stored for the concrete portlet in the PortletSettings object.
- Mode
- Portlet.Mode provides the current or previous mode of the portlet.
- PortletWindow
- The PortletWindow object represents the state of the current portlet window. The portlet can access this object to determine if the portlet is currently maximized, minimized, or rendered in its normal view.
- ModeModifier
- This object can be used in a portlet action to set the portlet mode to its current, previous, or requested mode before the portlet is rendered. For example, a portlet in edit mode could process a user action and return the portlet to edit mode for more input before returning to view mode.
PortletResponse
The response object encapsulates information to be returned from the server to the client. PortletResponse is passed via the beginPage(), endPage() and service() methods and can be used by the portlet to return portlet output using a Java PrintWriter. The response also includes methods for creating the PortletURI object or qualifying portlet markup with the portlet's namespace.
Use one of the following methods to create the PortletURI:
- createURI()
- Creates a PortletURI object pointing to the calling portlet with the current mode
- createURI(PortletWindow.State state)
- Creates a PortletURI object pointing to the calling portlet with the current mode and given portlet window state. A portlet can use this method to enter solo state.
- createReturnURI()
- Creates a portletURI pointing at the caller of the portlet. For example, createReturnURI() can be used to create a back button in an edit mode. This method must be used for a portlet to exit solo state.
Each portlet runs in its own unique namespace. The encodeNamespace() method is used by portlets to bring attributes in the portlet output to avoid name clashes with other portlets. Attributes can include parameter names, global variables, or JavaScript function names.
PortletURI
The PortletURI object contains a URI pointing to the portlet instance and can be further extended by adding portlet-specific parameters and by attaching actions.
Actions are portlet-specific activities that need to be performed as result of the incoming request, but before the service() method of the portlet is called. For example, when a user is entering data in the portlet's edit mode and clicks a Save button, the portlet needs to process the posted data before the next markup is generated. This can be achieved by adding a Save action to the URI that represents the Save button.
The complete URI can be converted to a string which is ready for embedding into markup.
PortletSession
The PortletSession holds user-specific data for the concrete portlet instance of the portlet creating a portlet user instance. Concrete portlet instances differ from each other only by the data stored in their PortletData. Portlet user instances differ from each other only by the transient data stored in their PortletSession. Any persistent data must be stored using PortletData. Information stored in a portlet's instance variables is shared between all concrete portlet instances and even between all concrete portlets - with read and write access. Make sure you do not use instance attributes for user-specific data.
On the other hand, you have to be cautious about what the portlet adds to the session, especially if the portlet ever runs in a cluster environment where the session is being serialized to a shared database. Everything being stored in the session must be serializable, too.
Like the HttpSession, a PortletSession is not available on an anonymous page. However, in cases where an administrator places a portlet on an unauthenticated page, such as the Welcome page shipped with WebSphere Portal, the portlet should provide code to handle it. See Accessing the portlet session when the user is not authenticated for more information.
During login, a PortletSession is automatically created for each portlet on a page. To get a PortletSession, the getSession() method (available from the PortletRequest) has to be used. The method returns the current session or, if there is no current session and the given parameter "create" is true, it creates one and returns it.
Related information
Parent topic
IBM Portlet API