Portlet API concepts

The following figure shows different variations of a portlet as it is created, placed on a page, and accessed by users. Notice that the first two steps involve the use of persistent data, but for the third step, the data is available only for the duration of the session.

The portal administrator uses the administrative interface to deploy a new portlet application WAR file or install a copy of a portlet. Either action creates a concrete portlet, which is a portlet parameterized by a single PortletSettings object. There can be many concrete portlets for each portlet. PortletSettings are read/write accessible and persistent. The PortletSettings contains configuration parameters initially defined in portlet.xml.

The use of concrete portlets allows many instances of a portlet to run with different configurations, without creating extra portlet class instances. During the lifecycle of a single portlet, many concrete portlets can be created and destroyed. There is no object that explicitly represents the concrete portlet. The same concrete portlet can be shared across many users.

The portlet is placed on a page by a user or an administrator. This creates a concrete portlet instance, which is a concrete portlet parameterized by a single PortletData object. There can be many concrete portlet instances per concrete portlet. PortletData stores persistent information for a portlet that has been added to a page. For example, a user can edit a stock quotes portlet and save a list of stock symbols for the companies to track.

The scope of the PortletData depends on the scope of the page that the concrete portlet is on.

When a user accesses a page that contains a portlet, that creates a user portlet instance. When a user logs into the portal, the portal server creates a PortletSession for each of the user's portlets. A concrete portlet instance parameterized by a PortletSession is known as a user portlet instance. There can be many user portlet instances per concrete portlet instance.

A user portlet instance is a concrete portlet instance parameterized by a single PortletSession. There can be many user portlet instances per concrete portlet instance. The PortletSession stores transient information related to a single use of the portlet.

Portlet applications

Portlet applications provide the means to package a group of related portlets that share the same context. The context contains all resources, for example, images, properties files, and classes. All portlets must be packaged as part of a portlet application.

Concrete Portlet Application

A concrete portlet application is a portlet application parameterized with a single PortletApplicationSettings object. For each portlet application, there may be many concrete portlet applications. PortletApplicationSettings are read/write accessible and persistent. There is no object that explicitly represents the concrete portlet application.

style="border:1 solid #000000;margin:12;"> Two concrete <a href=

portlet applications derived from a single portlet application">

A concrete portlet application contains at least one concrete portlet from the portlet application, but it is not required to contain all of them.

Portlet applications provide no code on their own but form a logical group of portlets. Beside this more logical gain, portlets of the same portlet application can also exchange messages.

Portlet modes

Portlet modes allow a portlet to display a different user interface, depending on the task required of the portlet. A portlet has four modes of display, which are defined in the portlet.xml . The portlet container maintains the portlet mode in the Portlet.Mode object. The following modes are provided by the Portlet API:

Portlets declare support for these modes in portlet.xml. All portlets must support the VIEW mode. The Portlet API provides the PortletRequest.getMode() and PortletRequest.getPreviousMode() methods for the portlet to determine the current or previous mode.

The portlet skin provides icons in the title bar for users to interact with portlets on their portal pages. Clicking on one of these icons can change the portlet's mode or state. The following shows a blank title bar of a portlet in view mode.

This title bar displays the Edit, Help, Minimize, and Maximize icons. Clicking the pencil icon places the portlet in edit mode.

Portlet states

Portlet states allow users to change how the portlet window is displayed within the portal. Portlet states are maintained in the PortletWindow.State object with a boolean value. The Portlet API provides the PortletWindow.getWindowState() method to determine the portlet's current state. The following states can be invoked using icons in the title bar, in the same way that Windows applications are manipulated.

Solo state

A portlet can also be displayed in solo state, which hides the portal theme elements, such as a banner, page navigation, or tool bar. However, solo state cannot be invoked using an icon on the title bar. Also, unlike the other states, solo state is not declared in portlet.xml. A portlet enters solo state in the following ways:

From outside a portlet, using the <wps:URLGeneration portletWindowState=solo"/> tag.
From inside a portlet with the <portletAPI:createURI state="solo"/> tag or the createURI(PortletWindow.State SOLO) method.

The developer of the portal theme determines which elements are hidden in solo state using the <wps:if portletSolo=""/> tag. Portlets cannot enter solo state if the user has not logged in.

While in solo state, the minimize and maximize icons cannot alter the portlet's state. The portlet can exit solo state only by using the createReturnURI() method. While not required, it is suggested that all portlets use this method to ensure that users can exit from solo mode and return the normal portal interface.