Portlet


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