001: /**
002: * Copyright 2003 IBM Corporation and Sun Microsystems, Inc.
003: * All rights reserved.
004: * Use is subject to license terms.
005: */package javax.portlet;
006:
007: /**
008: * The <CODE>Portlet</CODE> interface is used by the portlet container to
009: * invoke the portlets. Every portlet has to implement this interface,
010: * either by directly implementing it, or by using an existing class
011: * implementing the Portlet interface.
012: * <P>
013: * A portlet is a Java technology-based web component. It is managed by the portlet container and
014: * processes requests and generates dynamic content as response. Portlets are used by portals as
015: * pluggable user interface components.
016: * <p/>
017: * The content generated by a portlet is called a fragment. A fragment is a piece of
018: * markup (e.g. HTML, XHTML, WML) adhering to certain rules and can be aggregated
019: * with other fragments into a complete document. The content of a portlet is normally
020: * aggregated with the content of other portlets into the portal page.
021: * <P>
022: * The portlet container instanciates portlets, manages their lifecycle
023: * and invoking them to process requests. The lifecycle consists of:
024: * <ul>
025: * <li>initializing the portlet using using the <code>init</code> method
026: * <li>request processsing
027: * <li>taking the portlet out of service using the <code>destroy</code> method
028: * </ul>
029: * <p/>
030: * Request processing is divided into two types:
031: * <ul>
032: * <li>action requests handled through the <code>processAction</code> method,
033: * to perform actions targeted to the portlet
034: * <li>render requests handled through the <code>render</code> method,
035: * to perform the render operation
036: * </ul>
037: */
038: public interface Portlet {
039:
040: /**
041: * Called by the portlet container to indicate to a portlet that the
042: * portlet is being placed into service.
043: * <p/>
044: * <p>The portlet container calls the <code>init</code>
045: * method exactly once after instantiating the portlet.
046: * The <code>init</code> method must complete successfully
047: * before the portlet can receive any requests.
048: * <p/>
049: * <p>The portlet container cannot place the portlet into service
050: * if the <code>init</code> method
051: * <ol>
052: * <li>Throws a <code>PortletException</code>
053: * <li>Does not return within a time period defined by the portlet container.
054: * </ol>
055: *
056: * @param config a <code>PortletConfig</code> object
057: * containing the portlet's
058: * configuration and initialization parameters
059: * @throws PortletException if an exception has occurred that
060: * interferes with the portlet's normal
061: * operation.
062: * @throws UnavailableException if the portlet cannot perform the initialization at this time.
063: */
064:
065: public void init(PortletConfig config) throws PortletException;
066:
067: /**
068: * Called by the portlet container to allow the portlet to process
069: * an action request. This method is called if the client request was
070: * originated by a URL created (by the portlet) with the
071: * <code>RenderResponse.createActionURL()</code> method.
072: * <p/>
073: * Typically, in response to an action request, a portlet updates state
074: * based on the information sent in the action request parameters.
075: * In an action the portlet may:
076: * <ul>
077: * <li>issue a redirect
078: * <li>change its window state
079: * <li>change its portlet mode
080: * <li>modify its persistent state
081: * <li>set render parameters
082: * </ul>
083: * <p/>
084: * A client request triggered by an action URL translates into one
085: * action request and many render requests, one per portlet in the portal page.
086: * The action processing must be finished before the render requests
087: * can be issued.
088: *
089: * @param request the action request
090: * @param response the action response
091: * @throws PortletException if the portlet has problems fulfilling the
092: * request
093: * @throws UnavailableException if the portlet is unavailable to process the action at this time
094: * @throws PortletSecurityException if the portlet cannot fullfill this request because of security reasons
095: * @throws java.io.IOException if the streaming causes an I/O problem
096: */
097: public void processAction(ActionRequest request,
098: ActionResponse response) throws PortletException,
099: java.io.IOException;
100:
101: /**
102: * Called by the portlet container to allow the portlet to generate
103: * the content of the response based on its current state.
104: *
105: * @param request the render request
106: * @param response the render response
107: * @throws PortletException if the portlet has problems fulfilling the
108: * rendering request
109: * @throws UnavailableException if the portlet is unavailable to perform render at this time
110: * @throws PortletSecurityException if the portlet cannot fullfill this request because of security reasons
111: * @throws java.io.IOException if the streaming causes an I/O problem
112: */
113:
114: public void render(RenderRequest request, RenderResponse response)
115: throws PortletException, java.io.IOException;
116:
117: /**
118: * Called by the portlet container to indicate to a portlet that the
119: * portlet is being taken out of service.
120: * <p/>
121: * Before the portlet container calls the destroy method, it should
122: * allow any threads that are currently processing requests within
123: * the portlet object to complete execution. To avoid
124: * waiting forever, the portlet container can optionally wait for
125: * a predefined time before destroying the portlet object.
126: * <p/>
127: * <p>This method enables the portlet to do the following:
128: * <ul>
129: * <li>clean up any resources that it holds (for example, memory,
130: * file handles, threads)
131: * <li>make sure that any persistent state is
132: * synchronized with the portlet current state in memory.
133: * </ul>
134: */
135:
136: public void destroy();
137: }
|