|
Portlet API 2 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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:
init()
method.
service()
method are handled.
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 |
public void init(PortletConfig config) throws UnavailableException
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
PortletException
config
- the portlet configurationUnavailableException
- if an exception has occurrred that interferes
with the portlet's normal initializationpublic void destroy()
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).
public void beginSession(PortletSession session) throws PortletException
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.
session
- the portlet sessionpublic void endSession(PortletSession session)
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.
session
- the portlet sessionpublic void service(PortletRequest request, PortletResponse response) throws PortletException, IOException
request
- the portlet requestresponse
- the portlet responsePortletException
- if the portlet has trouble fulfilling the
rendering requestIOException
- if the streaming causes an I/O problem
|
Portlet API 2 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |