Overview

Package

Class

Tree

Serialized

Deprecated

Index

Help

PREV class NEXT class

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.jetspeed.portlet
Class Portlet

java.lang.Object
  javax.servlet.GenericServlet
      javax.servlet.http.HttpServlet
          com.ibm.wps.pe.pc.legacy.cache.CacheablePortlet
              org.apache.jetspeed.portlet.Portlet

All Implemented Interfaces:

com.ibm.websphere.servlet.cache.CacheableServlet, PortletSessionListener, java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

Direct Known Subclasses:

PortletAdapter

public abstract class Portlet

extends CacheablePortlet

implements PortletSessionListener

The abstract Portlet is used by the portlet container to invoke the portlet. Every portlet has to implement this abstract class, either by deriving directly from it, or by using one of the abstract portlet implementations.

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 one portlet object instance per portlet configuration in the web deployment descriptor. There may be many PortletSettings objects parametersing the same portlet object according to the Flyweight pattern, provided on a per-request basis. A concrete parameterization of a portlet object is referred to as a concrete portlet. The settings of concrete portlets may change at any time caused by administrators modifying portlet settings, e.g. using the config mode of a portlet.

Additionally, user can have personal views of concrete portlets. Therefore, the transient portlet session and persistent concrete portlet data carries vital information for the portlet to create a personalized user experience. A concrete portlet in conjunction with portlet data creates a concrete portlet instance. This is similar to why a servlet may not store things depending on requests or sessions in instance variables. As a consequence, the portlet should not attempt to store any data that depends on portlet settings, portlet data or the portlet session or any other user-related information as instance or class variables. The general programming rules for servlets also apply to portlets - instance variables should only used when the intent is to share them between all the parallel threads that concurrently execute a portlet, and portlet code should avoid synchronization unless absolutely required.

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. A concrete portlet s initialized with the initConcrete() method for each PortletSettings.
3. Any calls from the portlet container to the service() method are handled.
4. The concrete portlet is taken out of service with the destroyConcrete() method.
5. The portlet is taken out of service, then destroyed with the destroy() method, then garbage collected and finalized.

The concrete portlet instance is created and destroyed with the login() and logout() methods, respectively. If a portlet provides personalized views these methods should be implemented.

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 out of service temporarily, 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.

Note on serialization: The Portlet class and all subclasses are not serializable. The Portlet class indirectly extends the javax.servlet.http.HttpServlet class and therefore inherits the Serializable interface from this class. All portlets therefore implement the Serializable interface, but nevertheless they must not be serialized. Attempting to serialize or deserialize a portlet will result in an UnsupportedOperationException.

Serialization cannot be supported because the lifecycle of a portlet is managed by the portal. A portlet that is deserialized again is not under the control of the portal and therefore its runtime properties are in an undefined state, so it is not possible to access the portlet.

Since:

4.1

See Also:

Serialized Form

Nested Class Summary
static class	Portlet.Mode The Mode class is a finite enumeration of the possible modes that a portlet can assume.
static class	Portlet.ModeModifier The ModeModifier class is a finite enumeration of the possible modifications a portlet can apply on modes.

Constructor Summary

Portlet()

Method Summary
void	destroy()
abstract void	destroy(PortletConfig config) Called by the portlet container to indicate to this portlet that it is taken out of service.
abstract void	destroyConcrete(PortletSettings settings) Called by the portlet container to indicate that the concrete portlet is taken out of service.
protected void	doGet(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
protected void	doPost(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
protected void	doPut(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
java.lang.String	getId(javax.servlet.http.HttpServletRequest request) This method is used by the WebSphere Dynacache to generate a cache ID.
java.lang.String	getInitParameter(java.lang.String name)
java.util.Enumeration	getInitParameterNames()
protected long	getLastModified(javax.servlet.http.HttpServletRequest req)
abstract long	getLastModified(PortletRequest request) Returns the time the response of the Portlet object was last modified, in milliseconds since midnight January 1, 1970 GMT.
abstract PortletConfig	getPortletConfig() Returns the PortletConfig object of the portlet
protected PortletSettings	getPortletSettings() Deprecated. since 5.1, use PortletRequest.getPortletSettings instead. A single instance of a portlet may reference multiple concrete portlets; without a reference to a portlet request, it is not always possible to determine the correct concrete portlet
javax.servlet.ServletContext	getServletContext()
java.lang.String	getServletInfo()
abstract void	init(PortletConfig config) Called by the portlet container to indicate to this portlet that it is put into service.
void	init(javax.servlet.ServletConfig config)
abstract void	initConcrete(PortletSettings settings) Called by the portlet container to indicate that the concrete portlet is put into service.
abstract void	login(PortletRequest request) Called by the portlet container before the service() method of this portlet is invoked for the first time in the context of a new user session.
abstract void	logout(PortletSession session) Called by the portlet container when a user session terminates (by user logout or timeout) for which the login() method has been called before.
abstract 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.
void	service(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response)

Methods inherited from class com.ibm.wps.pe.pc.legacy.cache.CacheablePortlet

getSharingPolicy, service

Methods inherited from class javax.servlet.http.HttpServlet

doDelete, doHead, doOptions, doTrace

Methods inherited from class javax.servlet.GenericServlet

getServletConfig, getServletName, init, log, log

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Portlet

public Portlet()

Method Detail

init

public abstract 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 concrete portlets are created through the initConcrete() method.

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

1. throws UnavailableException
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 abstract void destroy(PortletConfig config)

Called by the portlet container to indicate to this portlet that it is taken out of service. This method is called when the destroyConcrete() method has been called on all concrete portlets that have been active, i.e. for which initConcrete() has been called before.

After the portlet container calls this method, it will not call the service() method or any listener methods 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).

initConcrete

public abstract void initConcrete(PortletSettings settings)
                           throws UnavailableException

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

The portlet container calls the initConcrete() method before the service() method or any listener method is invoked for the portlet. The initConcrete() method must complete successfully before concrete portlet instances can be created through the login() method.

The portlet container cannot place the portlet into service if the initConcrete() method fails.

Parameters:

settings - The portlet settings

Throws:

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

destroyConcrete

public abstract void destroyConcrete(PortletSettings settings)

Called by the portlet container to indicate that the concrete portlet 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 or any listener methods 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).

Parameters:

settings - the portlet settings

service

public abstract void service(PortletRequest request,
                             PortletResponse response)
                      throws org.apache.jetspeed.portlet.PortletException,
                             java.io.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

java.io.IOException - if the streaming causes an I/O problem

getLastModified

public abstract long getLastModified(PortletRequest request)

Returns the time the response of the Portlet object was last modified, in milliseconds since midnight January 1, 1970 GMT. If the time is unknown, this method returns a negative number (the default).

Portlets that can quickly determine their last modification time should override this method. This makes browser and proxy caches work more effectively, reducing the load on server and network resources.

Specified by:

getLastModified in class CacheablePortlet

Parameters:

request - the PortletRequest object that is sent to the portlet

Returns:

a long integer specifying the time the response of the Portlet object was last modified, in milliseconds since midnight, January 1, 1970 GMT, or -1 if the time is not known

getPortletConfig

public abstract PortletConfig getPortletConfig()

Returns the PortletConfig object of the portlet

Returns:

the PortletConfig object

login

public abstract void login(PortletRequest request)
                    throws org.apache.jetspeed.portlet.PortletException

Description copied from interface: PortletSessionListener

Called by the portlet container before the service() method of this portlet is invoked for the first time in the context of a new user session. This method will called at most once for any user session in the portal.

This method can be implemented by the portlet to initialize a personalized user experience. In addition to initializing the session this method allows the portlet to initialize the concrete portlet instance, for example, to store attributes in the session.

Specified by:

login in interface PortletSessionListener

Parameters:

request - the portlet request

Throws:

org.apache.jetspeed.portlet.PortletException

logout

public abstract void logout(PortletSession session)
                     throws org.apache.jetspeed.portlet.PortletException

Description copied from interface: PortletSessionListener

Called by the portlet container when a user session terminates (by user logout or timeout) for which the login() method has been called before. After this method has been called, the service() method of the portlet will nor be invoked again within the context of the same user session.

This method gives the concrete portlet instance an opportunity to clean up any resources (for example, memory, file handles, threads), before it is removed.

Specified by:

logout in interface PortletSessionListener

Parameters:

session - the portlet session

Throws:

org.apache.jetspeed.portlet.PortletException

getPortletSettings

protected PortletSettings getPortletSettings()

Deprecated. since 5.1, use PortletRequest.getPortletSettings instead. A single instance of a portlet may reference multiple concrete portlets; without a reference to a portlet request, it is not always possible to determine the correct concrete portlet

Returns the PortletSettings object of the concrete portlet.

Returns:

the PortletSettings object, or NULL if no PortletSettings object is available.

getInitParameter

public final java.lang.String getInitParameter(java.lang.String name)

Specified by:

getInitParameter in interface javax.servlet.ServletConfig

getInitParameterNames

public final java.util.Enumeration getInitParameterNames()

Specified by:

getInitParameterNames in interface javax.servlet.ServletConfig

getServletContext

public javax.servlet.ServletContext getServletContext()

Specified by:

getServletContext in interface javax.servlet.ServletConfig

getLastModified

protected long getLastModified(javax.servlet.http.HttpServletRequest req)

getServletInfo

public java.lang.String getServletInfo()

Specified by:

getServletInfo in interface javax.servlet.Servlet

service

public final void service(javax.servlet.ServletRequest request,
                          javax.servlet.ServletResponse response)
                   throws javax.servlet.ServletException,
                          java.io.IOException

Specified by:

service in interface javax.servlet.Servlet

Throws:

javax.servlet.ServletException

java.io.IOException

doGet

protected void doGet(javax.servlet.http.HttpServletRequest req,
                     javax.servlet.http.HttpServletResponse resp)
              throws javax.servlet.ServletException,
                     java.io.IOException

Throws:

javax.servlet.ServletException

java.io.IOException

doPost

protected void doPost(javax.servlet.http.HttpServletRequest req,
                      javax.servlet.http.HttpServletResponse resp)
               throws javax.servlet.ServletException,
                      java.io.IOException

Throws:

javax.servlet.ServletException

java.io.IOException

doPut

protected void doPut(javax.servlet.http.HttpServletRequest req,
                     javax.servlet.http.HttpServletResponse resp)
              throws javax.servlet.ServletException,
                     java.io.IOException

Throws:

javax.servlet.ServletException

java.io.IOException

init

public void init(javax.servlet.ServletConfig config)
          throws javax.servlet.ServletException

Specified by:

init in interface javax.servlet.Servlet

Throws:

javax.servlet.ServletException

destroy

public void destroy()

Specified by:

destroy in interface javax.servlet.Servlet

getId

public java.lang.String getId(javax.servlet.http.HttpServletRequest request)

Description copied from class: CacheablePortlet

This method is used by the WebSphere Dynacache to generate a cache ID. It must not be overridden by portlets.

Specified by:

getId in interface com.ibm.websphere.servlet.cache.CacheableServlet

Specified by:

getId in class CacheablePortlet

Parameters:

request - The HTTP request object.

Returns:

The cache id. A null indicates that the portlet should not be cached.