View Javadoc

1   /*
2    * Copyright 2003,2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  /*
17   * This source code implements specifications defined by the Java
18   * Community Process. In order to remain compliant with the specification
19   * DO NOT add / change / or delete method signatures!
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 }