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