org.apache.jetspeed.portlet
Interface Portlet

All Known Implementing Classes:

SaxPortlet

public interface Portlet

The Portlet interface is used by the portlet container to invoke the portlet. However, a portlet cannot directly implement the Portlet interface directly. Instead, it has to extend one of the abstract portlet implementations, which indicates to the the portlet container the type of content (eg. content stream or SAX events) that the portlet will generate.

A portlet is a small Java program that runs within a portlet container. Portlets receive and respond to requests from the portlet container. There is ever only object instance of each portlet class, yet each user should be able to a have personalized view of that portlet instance. Therefore, the portlet session carries vital information for the portlet to create a personalized user experience. Portlet instance plus session create a virtual instance of the portlet. This is similar to the way a servlet relates to its servlet container. As a consequence, the portlet should not attempt to store the portlet session or any other user-related information as instance or class variabled. In fact, instance variables of a portlet can be considered to have similar behaviour as class variables, because there is ever only one instance which is shared by multiple threads. Therefore, any instance information has to be either read-only (as is the case for the portlet configuration), or carefully protected by the synchronized keyword.

As part of running within the portlet container each portlet has a life-cycle. The corresponding methods are called in the following sequence:

1. The portlet is constructed, then initialized with the init() method.
2. Any calls from the portlet container to the service() method are handled.
3. The portlet is taken out of service, then destroyed with the destroy() method, then garbage collected and finalized.

The virtual instance is created and destroyed with the beginSession() and endSession()methods, respectively. If a portlet provides personalized views these methods should be implemented so that the initialized portlet session is returned and later destroyed.

The portlet container loads and instantiates the portlet class. This can happen during startup of the portal server or later, but no later then when the first request to the portlet has to be serviced. Also, if a portlet is taken temporarily out of service, for example while administrating it, the portlet container may finish the life-cycle before taking the portlet out of service. When the administration is done, the portlet will be newly initialized.

Inner Class Summary

static class

Portlet.Mode The Mode class is a finite enumeration of the possible modes that a portlet can assume.

Method Summary

void	beginSession(PortletSession session) Called by the portlet container to ask the portlet to initialize the given portlet session.
void	destroy() Called by the portlet container to indicate to this portlet that it is taken out of service.
void	endSession(PortletSession session) Called by the portlet container to indicate to a virtual instance of the portlet is being removed.
void	init(PortletConfig config) Called by the portlet container to indicate to this portlet that it is put into service.
void	service(PortletRequest request, PortletResponse response) Called by the portlet container to ask this portlet to generate its markup using the given request/response pair.

Method Detail

init

public void init(PortletConfig config)
          throws UnavailableException

Called by the portlet container to indicate to this portlet that it is put into service.

The portlet container calls the init() method for the whole life-cycle of the portlet. The init() method must complete successfully before virtual instances are created through the beginSession() method.

The portlet container cannot place the portlet into service if the init() method

1. Throws a PortletException
2. Does not return within a time period defined by the portlet container.

Parameters:

config - the portlet configuration

Throws:

UnavailableException - if an exception has occurrred that interferes with the portlet's normal initialization

destroy

public void destroy()

Called by the portlet container to indicate to this portlet that it is taken out of service. This method is only called once all threads within the portlet's service() method have exited or after a timeout period has passed. After the portlet container calls this method, it will not call the service() method again on this portlet.

This method gives the portlet an opportunity to clean up any resources that are being held (for example, memory, file handles, threads).

beginSession

public void beginSession(PortletSession session)
                  throws PortletException

Called by the portlet container to ask the portlet to initialize the given portlet session. If the user is not logged on, the given portlet session is null. Before attempting to initialize the session the portlet should check for this condition.

In addition to initializing the sessionThis method allows the portlet to initialize the virtual instance, for example, to register listeners or customize the portlet window. The portlet session which is passed as argued must not be stored by the portlet.

Parameters:

session - the portlet session

endSession

public void endSession(PortletSession session)

Called by the portlet container to indicate to a virtual instance of the portlet is being removed. The given portlet session may be null if the virtual instance did not create a session during its life-time.

This method gives the virtual instance of the portlet an opportunity to clean up any resources (for example, memory, file handles, threads), before it is removed. This may happen if the user logs off, or decides to remove this portlet from a page.

Parameters:

session - the portlet session

service

public void service(PortletRequest request,
                    PortletResponse response)
             throws PortletException,
                    IOException

Called by the portlet container to ask this portlet to generate its markup using the given request/response pair. Depending on the mode of the portlet and the requesting client device, the markup will be different. Also, the portlet can take language preferences and/or personalized settings into account.

Parameters:

request - the portlet request

response - the portlet response

Throws:

PortletException - if the portlet has trouble fulfilling the rendering request

IOException - if the streaming causes an I/O problem