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: *
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: *
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: *
057: * @param config a <code>PortletConfig</code> object
058: * containing the portlet's
059: * configuration and initialization parameters
060: *
061: * @exception PortletException if an exception has occurred that
062: * interferes with the portlet's normal
063: * operation.
064: * @exception UnavailableException if the portlet cannot perform the initialization at this time.
065: *
066: *
067: */
068:
069: public void init(PortletConfig config) throws PortletException;
070:
071: /**
072: * Called by the portlet container to allow the portlet to process
073: * an action request. This method is called if the client request was
074: * originated by a URL created (by the portlet) with the
075: * <code>RenderResponse.createActionURL()</code> method.
076: * <p>
077: * Typically, in response to an action request, a portlet updates state
078: * based on the information sent in the action request parameters.
079: * In an action the portlet may:
080: * <ul>
081: * <li>issue a redirect
082: * <li>change its window state
083: * <li>change its portlet mode
084: * <li>modify its persistent state
085: * <li>set render parameters
086: * </ul>
087: * <p>
088: * A client request triggered by an action URL translates into one
089: * action request and many render requests, one per portlet in the portal page.
090: * The action processing must be finished before the render requests
091: * can be issued.
092: *
093: * @param request
094: * the action request
095: * @param response
096: * the action response
097: * @exception PortletException
098: * if the portlet has problems fulfilling the
099: * request
100: * @exception UnavailableException
101: * if the portlet is unavailable to process the action at this time
102: * @exception PortletSecurityException
103: * if the portlet cannot fullfill this request because of security reasons
104: * @exception IOException
105: * if the streaming causes an I/O problem
106: */
107: public void processAction(ActionRequest request,
108: ActionResponse response) throws PortletException,
109: java.io.IOException;
110:
111: /**
112: * Called by the portlet container to allow the portlet to generate
113: * the content of the response based on its current state.
114: *
115: * @param request
116: * the render request
117: * @param response
118: * the render response
119: *
120: * @exception PortletException
121: * if the portlet has problems fulfilling the
122: * rendering request
123: * @exception UnavailableException
124: * if the portlet is unavailable to perform render at this time
125: * @exception PortletSecurityException
126: * if the portlet cannot fullfill this request because of security reasons
127: * @exception java.io.IOException
128: * if the streaming causes an I/O problem
129: */
130:
131: public void render(RenderRequest request, RenderResponse response)
132: throws PortletException, java.io.IOException;
133:
134: /**
135: *
136: * Called by the portlet container to indicate to a portlet that the
137: * portlet is being taken out of service.
138: * <p>
139: * Before the portlet container calls the destroy method, it should
140: * allow any threads that are currently processing requests within
141: * the portlet object to complete execution. To avoid
142: * waiting forever, the portlet container can optionally wait for
143: * a predefined time before destroying the portlet object.
144: *
145: * <p>This method enables the portlet to do the following:
146: * <ul>
147: * <li>clean up any resources that it holds (for example, memory,
148: * file handles, threads)
149: * <li>make sure that any persistent state is
150: * synchronized with the portlet current state in memory.
151: * </ul>
152: */
153:
154: public void destroy();
155: }
|