1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21 package javax.portlet;
22
23
24 /***
25 * The <CODE>Portlet</CODE> interface is used by the portlet container to
26 * invoke the portlets. Every portlet has to implement this interface,
27 * either by directly implementing it, or by using an existing class
28 * implementing the Portlet interface.
29 * <P>
30 * A portlet is a Java technology-based web component. It is managed by the portlet container and
31 * processes requests and generates dynamic content as response. Portlets are used by portals as
32 * pluggable user interface components.
33 * <p>
34 * The content generated by a portlet is called a fragment. A fragment is a piece of
35 * markup (e.g. HTML, XHTML, WML) adhering to certain rules and can be aggregated
36 * with other fragments into a complete document. The content of a portlet is normally
37 * aggregated with the content of other portlets into the portal page.
38 * <P>
39 * The portlet container instanciates portlets, manages their lifecycle
40 * and invoking them to process requests. The lifecycle consists of:
41 * <ul>
42 * <li>initializing the portlet using using the <code>init</code> method
43 * <li>request processsing
44 * <li>taking the portlet out of service using the <code>destroy</code> method
45 * </ul>
46 * <p>
47 * Request processing is divided into two types:
48 * <ul>
49 * <li>action requests handled through the <code>processAction</code> method,
50 * to perform actions targeted to the portlet
51 * <li>render requests handled through the <code>render</code> method,
52 * to perform the render operation
53 * </ul>
54 */
55 public interface Portlet
56 {
57
58
59
60 /***
61 * Called by the portlet container to indicate to a portlet that the
62 * portlet is being placed into service.
63 *
64 * <p>The portlet container calls the <code>init</code>
65 * method exactly once after instantiating the portlet.
66 * The <code>init</code> method must complete successfully
67 * before the portlet can receive any requests.
68 *
69 * <p>The portlet container cannot place the portlet into service
70 * if the <code>init</code> method
71 * <ol>
72 * <li>Throws a <code>PortletException</code>
73 * <li>Does not return within a time period defined by the portlet container.
74 * </ol>
75 *
76 *
77 * @param config a <code>PortletConfig</code> object
78 * containing the portlet's
79 * configuration and initialization parameters
80 *
81 * @exception PortletException if an exception has occurred that
82 * interferes with the portlet's normal
83 * operation.
84 * @exception UnavailableException if the portlet cannot perform the initialization at this time.
85 *
86 *
87 */
88
89 public void init(PortletConfig config) throws PortletException;
90
91
92
93
94 /***
95 * Called by the portlet container to allow the portlet to process
96 * an action request. This method is called if the client request was
97 * originated by a URL created (by the portlet) with the
98 * <code>RenderResponse.createActionURL()</code> method.
99 * <p>
100 * Typically, in response to an action request, a portlet updates state
101 * based on the information sent in the action request parameters.
102 * In an action the portlet may:
103 * <ul>
104 * <li>issue a redirect
105 * <li>change its window state
106 * <li>change its portlet mode
107 * <li>modify its persistent state
108 * <li>set render parameters
109 * </ul>
110 * <p>
111 * A client request triggered by an action URL translates into one
112 * action request and many render requests, one per portlet in the portal page.
113 * The action processing must be finished before the render requests
114 * can be issued.
115 *
116 * @param request
117 * the action request
118 * @param response
119 * the action response
120 * @exception PortletException
121 * if the portlet has problems fulfilling the
122 * request
123 * @exception UnavailableException
124 * if the portlet is unavailable to process the action at this time
125 * @exception PortletSecurityException
126 * if the portlet cannot fullfill this request because of security reasons
127 * @exception IOException
128 * if the streaming causes an I/O problem
129 */
130 public void processAction (ActionRequest request, ActionResponse response)
131 throws PortletException, java.io.IOException;
132
133
134
135 /***
136 * Called by the portlet container to allow the portlet to generate
137 * the content of the response based on its current state.
138 *
139 * @param request
140 * the render request
141 * @param response
142 * the render response
143 *
144 * @exception PortletException
145 * if the portlet has problems fulfilling the
146 * rendering request
147 * @exception UnavailableException
148 * if the portlet is unavailable to perform render at this time
149 * @exception PortletSecurityException
150 * if the portlet cannot fullfill this request because of security reasons
151 * @exception java.io.IOException
152 * if the streaming causes an I/O problem
153 */
154
155 public void render (RenderRequest request, RenderResponse response)
156 throws PortletException, java.io.IOException;
157
158
159 /***
160 *
161 * Called by the portlet container to indicate to a portlet that the
162 * portlet is being taken out of service.
163 * <p>
164 * Before the portlet container calls the destroy method, it should
165 * allow any threads that are currently processing requests within
166 * the portlet object to complete execution. To avoid
167 * waiting forever, the portlet container can optionally wait for
168 * a predefined time before destroying the portlet object.
169 *
170 * <p>This method enables the portlet to do the following:
171 * <ul>
172 * <li>clean up any resources that it holds (for example, memory,
173 * file handles, threads)
174 * <li>make sure that any persistent state is
175 * synchronized with the portlet current state in memory.
176 * </ul>
177 */
178
179 public void destroy();
180 }