GenericPortlet


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  /**
12   * The <CODE>GenericPortlet</CODE> class provides a default implementation
13   * for the <CODE>Portlet</CODE> interface.
14   * <p>
15   * It provides an abstract class to be subclassed to create portlets. A 
16   * subclass of <CODE>GenericPortlet</CODE> should override at least
17   * one method, usually one of the following:
18   * <ul>
19   * <li>processAction, to handle action requests</li>
20   * <li>doView, to handle render requests when in VIEW mode</li>
21   * <li>doEdit, to handle render requests when in EDIT mode</li>
22   * <li>doHelp, to handle render request when in HELP mode</li>
23   * <li>init and destroy, to manage resources that are held for the life of 
24   * the servlet</li>
25   * </ul>
26   * <p>
27   * Normally there is no need to override the render or the doDispatch 
28   * methods. Render handles render requests setting the title of the 
29   * portlet in the response and invoking doDispatch. doDispatch dispatches 
30   * the request to one of the doView, doEdit or doHelp method depending on 
31   * the portlet mode indicated in the request.
32   * <p>
33   * Portlets typically run on multithreaded servers, so please note that a 
34   * portlet must handle concurrent requests and be careful to synchronize 
35   * access to shared resources.  Shared resources include in-memory data 
36   * such as  instance or class variables and external objects  such as 
37   * files, database connections, and network  connections.
38   */
39  public abstract class GenericPortlet implements Portlet, PortletConfig
40  {
41  
42    private transient PortletConfig config;
43  
44    /**
45     * Does nothing.
46     */
47  
48    public GenericPortlet()
49    {
50    }
51  
52  
53    /**
54     * Called by the portlet container to indicate to a portlet that the 
55     * portlet is being placed into service.
56     * <p>
57     * The default implementation just stores the <code>PortletConfig</code>
58     * object.
59     * <p>The portlet container calls the <code>init</code>
60     * method exactly once after instantiating the portlet.
61     * The <code>init</code> method must complete successfully
62     * before the portlet can receive any requests.
63     *
64     * <p>The portlet container cannot place the portlet into service
65     * if the <code>init</code> method does one of the following:
66     * <ol>
67     * <li>it throws a <code>PortletException</code>
68     * <li>it does not return within a time period defined by the Web server
69     * </ol>
70     *
71     *
72     * @param config          a <code>PortletConfig</code> object 
73     *                    containing the portlet
74     *                    configuration and initialization parameters
75     *
76     * @exception PortletException    if an exception has occurred that
77     *                    interferes with the portlet normal
78     *                    operation.
79     * @exception UnavailableException    if the portlet cannot perform the initialization at this time.
80     */
81  
82    public void init (PortletConfig config) throws PortletException
83    {
84      this.config = config;
85      this.init();
86    }
87  
88    
89    /**
90     *
91     * A convenience method which can be overridden so that there's no need
92     * to call <code>super.init(config)</code>.
93     *
94     * <p>Instead of overriding {@link #init(PortletConfig)}, simply override
95     * this method and it will be called by
96     * <code>GenericPortlet.init(PortletConfig config)</code>.
97     * The <code>PortletConfig</code> object can still be retrieved via {@link
98     * #getPortletConfig}. 
99     *
100    * @exception PortletException    if an exception has occurred that
101    *                    interferes with the portlet normal
102    *                    operation.
103    * @exception UnavailableException    if the portlet is unavailable to perform init
104    */
105     
106   public void init() throws PortletException
107   {
108   }
109 
110 
111   /**
112    * Called by the portlet container to allow the portlet to process
113    * an action request. This method is called if the client request was
114    * originated by a URL created (by the portlet) with the 
115    * <code>RenderResponse.createActionURL()</code> method.
116    * <p>
117    * The default implementation throws an exception.
118    *
119    * @param request
120    *                 the action request
121    * @param response
122    *                 the action response
123    * @exception PortletException
124    *                   if the portlet cannot fulfilling the request
125    * @exception  UnavailableException   
126    *                   if the portlet is unavailable to process the action at this time
127    * @exception  PortletSecurityException  
128    *                   if the portlet cannot fullfill this request because of security reasons
129    * @exception  java.io.IOException
130    *                   if the streaming causes an I/O problem
131    */
132   public void processAction (ActionRequest request, ActionResponse response) 
133     throws PortletException, java.io.IOException   {
134     throw new PortletException("processAction method not implemented");
135   }
136 
137 
138   /**
139    * The default implementation of this method sets the title 
140    * using the <code>getTitle</code> method and invokes the
141    * <code>doDispatch</code> method.
142    * 
143    * @param request
144    *                 the render request
145    * @param response
146    *                 the render response
147    *
148    * @exception PortletException
149    *                   if the portlet cannot fulfilling the request
150    * @exception  UnavailableException   
151    *                   if the portlet is unavailable to perform render at this time
152    * @exception  PortletSecurityException  
153    *                   if the portlet cannot fullfill this request because of security reasons
154    * @exception java.io.IOException
155    *                   if the streaming causes an I/O problem
156    *
157    */
158   public void render (RenderRequest request,
159               RenderResponse response)
160     throws PortletException, java.io.IOException  
161   {
162     response.setTitle(getTitle(request));
163     doDispatch(request, response);
164   }
165 
166   /**
167    * Used by the render method to get the title.
168    * <p>
169    * The default implementation gets the title from the ResourceBundle
170    * of the PortletConfig of the portlet. The title is retrieved
171    * using the 'javax.portlet.title' resource name.
172    * <p>
173    * Portlets can overwrite this method to provide dynamic
174    * titles (e.g. based on locale, client, and session information).
175    * Examples are:
176    * <UL>
177    * <LI>language-dependant titles for multi-lingual portals
178    * <LI>shorter titles for WAP phones
179    * <LI>the number of messages in a mailbox portlet
180    * </UL>
181    * 
182    * @return the portlet title for this window
183    */
184 
185   protected java.lang.String   getTitle(RenderRequest request) {
186     return config.getResourceBundle(request.getLocale()).getString("javax.portlet.title");
187   }
188 
189 
190   /**
191    * The default implementation of this method routes the render request
192    * to a set of helper methods depending on the current portlet mode the
193    * portlet is currently in.
194    * These methods are:
195    * <ul>
196    * <li><code>doView</code> for handling <code>view</code> requests
197    * <li><code>doEdit</code> for handling <code>edit</code> requests
198    * <li><code>doHelp</code> for handling <code>help</code> requests
199    * </ul>
200    * <P>
201    * If the window state of this portlet is <code>minimized</code>, this
202    * method does not invoke any of the portlet mode rendering methods.
203    * <p>
204    * For handling custom portlet modes the portlet should override this
205    * method.
206    *
207    * @param request
208    *                 the render request
209    * @param response
210    *                 the render response
211    *
212    * @exception PortletException
213    *                   if the portlet cannot fulfilling the request
214    * @exception  UnavailableException   
215    *                   if the portlet is unavailable to perform render at this time
216    * @exception  PortletSecurityException  
217    *                   if the portlet cannot fullfill this request because of security reasons
218    * @exception java.io.IOException
219    *                   if the streaming causes an I/O problem
220    *
221    * @see #doView(RenderRequest, RenderResponse)
222    * @see #doEdit(RenderRequest, RenderResponse)
223    * @see #doHelp(RenderRequest, RenderResponse)
224    */
225   protected void doDispatch (RenderRequest request,
226               RenderResponse response) throws PortletException,java.io.IOException  
227   {
228     WindowState state = request.getWindowState();
229     
230     if ( ! state.equals(WindowState.MINIMIZED)) {
231       PortletMode mode = request.getPortletMode();
232       if (mode.equals(PortletMode.VIEW)) {
233     doView (request, response);
234       }
235       else if (mode.equals(PortletMode.EDIT)) {
236     doEdit (request, response);
237       }
238       else if (mode.equals(PortletMode.HELP)) {
239     doHelp (request, response);
240       }
241       else {
242     throw new PortletException("unknown portlet mode: " + mode);
243       }
244     }
245 
246   }
247 
248 
249   /**
250    * Helper method to serve up the mandatory <code>view</code> mode.
251    * <p>
252    * The default implementation throws an exception.
253    *
254    * @param    request
255    *           the portlet request
256    * @param    response
257    *           the render response
258    *
259    * @exception PortletException
260    *                   if the portlet cannot fulfilling the request
261    * @exception  UnavailableException   
262    *                   if the portlet is unavailable to perform render at this time
263    * @exception  PortletSecurityException  
264    *                   if the portlet cannot fullfill this request because of security reasons
265    * @exception java.io.IOException
266    *                   if the streaming causes an I/O problem
267    *
268    */
269 
270   protected void doView (RenderRequest request,
271               RenderResponse response)
272     throws PortletException, java.io.IOException  
273   {
274     throw new PortletException("doView method not implemented");
275   }
276 
277 
278   /**
279    * Helper method to serve up the <code>edit</code> mode.
280    * <p>
281    * The default implementation throws an exception.
282    *
283    * @param    request
284    *           the portlet request
285    * @param    response
286    *           the render response
287    *
288    * @exception PortletException
289    *                   if the portlet cannot fulfilling the request
290    * @exception  UnavailableException   
291    *                   if the portlet is unavailable to perform render at this time
292    * @exception  PortletSecurityException  
293    *                   if the portlet cannot fullfill this request because of security reasons
294    * @exception java.io.IOException
295    *                   if the streaming causes an I/O problem
296    *
297    */
298 
299   protected void doEdit (RenderRequest request,
300               RenderResponse response)
301     throws PortletException, java.io.IOException  
302   {
303     throw new PortletException("doEdit method not implemented");
304   }
305 
306   /**
307    * Helper method to serve up the <code>help</code> mode.
308    * <p>
309    * The default implementation throws an exception.
310    *
311    * @param    request
312    *           the portlet request
313    * @param    response
314    *           the render response
315    *
316    * @exception PortletException
317    *                   if the portlet cannot fulfilling the request
318    * @exception  UnavailableException   
319    *                   if the portlet is unavailable to perform render at this time
320    * @exception  PortletSecurityException  
321    *                   if the portlet cannot fullfill this request because of security reasons
322    * @exception java.io.IOException
323    *                   if the streaming causes an I/O problem
324    */
325 
326   protected void doHelp (RenderRequest request,
327               RenderResponse response)
328     throws PortletException, java.io.IOException  
329   {
330     throw new PortletException("doHelp method not implemented");
331 
332   }
333 
334 
335 
336   /**
337    * Returns the PortletConfig object of this portlet.
338    *
339    * @return   the PortletConfig object of this portlet
340    */
341 
342   public PortletConfig getPortletConfig ()
343   {
344     return config;
345   }
346 
347   
348   /**
349    * Called by the portlet container to indicate to a portlet that the portlet 
350    * is being taken out of service.
351    * <p>
352    * The default implementation does nothing.
353    *
354    */
355   
356   public void destroy ()
357   {
358     // do nothing
359   }
360 
361   //-------------------------------------------------------------------------
362   // implement PortletConfig
363   //-------------------------------------------------------------------------
364 
365 
366   /**
367    * Returns the name of this portlet.
368    * 
369    * @return the portlet name
370    * 
371    * @see PortletConfig#getPortletName()
372    */
373 
374   public String   getPortletName ()
375   {
376     return config.getPortletName();
377   }
378 
379 
380   /**
381    * Returns the <code>PortletContext</code> of the portlet application 
382    * the portlet is in.
383    *
384    * @return   the portlet application context
385    */
386 
387   public PortletContext getPortletContext ()
388   {
389     return config.getPortletContext();
390   }
391 
392 
393 
394   /**
395    * Gets the resource bundle for the given locale based on the
396    * resource bundle defined in the deployment descriptor
397    * with <code>resource-bundle</code> tag or the inlined resources
398    * defined in the deployment descriptor.
399    * 
400    * @return   the resource bundle for the given locale
401    */
402 
403   public java.util.ResourceBundle   getResourceBundle(java.util.Locale   locale)
404   {
405     return config.getResourceBundle(locale);
406   }
407 
408   
409   /**
410    * Returns a String containing the value of the named initialization parameter, 
411    * or null if the parameter does not exist.
412    *
413    * @param name    a <code>String</code> specifying the name
414    *            of the initialization parameter
415    *
416    * @return        a <code>String</code> containing the value 
417    *            of the initialization parameter
418    *
419    * @exception java.lang.IllegalArgumentException  
420    *                      if name is <code>null</code>.
421    */
422 
423   public String   getInitParameter(java.lang.String   name)
424   {
425     return config.getInitParameter(name);
426   }
427 
428 
429   /**
430    * Returns the names of the portlet initialization parameters as an 
431    * Enumeration of String objects, or an empty Enumeration if the 
432    * portlet has no initialization parameters.    
433    * 
434    * @return        an <code>Enumeration</code> of <code>String</code> 
435    *            objects containing the names of the portlet 
436    *            initialization parameters, or an empty Enumeration if the 
437    *                    portlet has no initialization parameters. 
438    */
439 
440   public java.util.Enumeration   getInitParameterNames()
441   {
442     return config.getInitParameterNames();
443   }
444 }
445
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags