001: /**
002: * Copyright 2003 IBM Corporation and Sun Microsystems, Inc.
003: * All rights reserved.
004: * Use is subject to license terms.
005: */package javax.portlet;
006:
007: /**
008: * The <CODE>GenericPortlet</CODE> class provides a default implementation
009: * for the <CODE>Portlet</CODE> interface.
010: * <p>
011: * It provides an abstract class to be subclassed to create portlets. A
012: * subclass of <CODE>GenericPortlet</CODE> should override at least
013: * one method, usually one of the following:
014: * <ul>
015: * <li>processAction, to handle action requests</li>
016: * <li>doView, to handle render requests when in VIEW mode</li>
017: * <li>doEdit, to handle render requests when in EDIT mode</li>
018: * <li>doHelp, to handle render request when in HELP mode</li>
019: * <li>init and destroy, to manage resources that are held for the life of
020: * the servlet</li>
021: * </ul>
022: * <p>
023: * Normally there is no need to override the render or the doDispatch
024: * methods. Render handles render requests setting the title of the
025: * portlet in the response and invoking doDispatch. doDispatch dispatches
026: * the request to one of the doView, doEdit or doHelp method depending on
027: * the portlet mode indicated in the request.
028: * <p>
029: * Portlets typically run on multithreaded servers, so please note that a
030: * portlet must handle concurrent requests and be careful to synchronize
031: * access to shared resources. Shared resources include in-memory data
032: * such as instance or class variables and external objects such as
033: * files, database connections, and network connections.
034: */
035: public abstract class GenericPortlet implements Portlet, PortletConfig {
036:
037: private transient PortletConfig config;
038:
039: /**
040: * Does nothing.
041: */
042:
043: public GenericPortlet() {
044: }
045:
046: /**
047: * Called by the portlet container to indicate to a portlet that the
048: * portlet is being placed into service.
049: * <p>
050: * The default implementation just stores the <code>PortletConfig</code>
051: * object.
052: * <p>The portlet container calls the <code>init</code>
053: * method exactly once after instantiating the portlet.
054: * The <code>init</code> method must complete successfully
055: * before the portlet can receive any requests.
056: *
057: * <p>The portlet container cannot place the portlet into service
058: * if the <code>init</code> method does one of the following:
059: * <ol>
060: * <li>it throws a <code>PortletException</code>
061: * <li>it does not return within a time period defined by the Web server
062: * </ol>
063: *
064: *
065: * @param config a <code>PortletConfig</code> object
066: * containing the portlet
067: * configuration and initialization parameters
068: *
069: * @exception PortletException if an exception has occurred that
070: * interferes with the portlet normal
071: * operation.
072: * @exception UnavailableException if the portlet cannot perform the initialization at this time.
073: */
074:
075: public void init(PortletConfig config) throws PortletException {
076: this .config = config;
077: this .init();
078: }
079:
080: /**
081: *
082: * A convenience method which can be overridden so that there's no need
083: * to call <code>super.init(config)</code>.
084: *
085: * <p>Instead of overriding {@link #init(PortletConfig)}, simply override
086: * this method and it will be called by
087: * <code>GenericPortlet.init(PortletConfig config)</code>.
088: * The <code>PortletConfig</code> object can still be retrieved via {@link
089: * #getPortletConfig}.
090: *
091: * @exception PortletException if an exception has occurred that
092: * interferes with the portlet normal
093: * operation.
094: * @exception UnavailableException if the portlet is unavailable to perform init
095: */
096:
097: public void init() throws PortletException {
098: }
099:
100: /**
101: * Called by the portlet container to allow the portlet to process
102: * an action request. This method is called if the client request was
103: * originated by a URL created (by the portlet) with the
104: * <code>RenderResponse.createActionURL()</code> method.
105: * <p>
106: * The default implementation throws an exception.
107: *
108: * @param request
109: * the action request
110: * @param response
111: * the action response
112: * @exception PortletException
113: * if the portlet cannot fulfilling the request
114: * @exception UnavailableException
115: * if the portlet is unavailable to process the action at this time
116: * @exception PortletSecurityException
117: * if the portlet cannot fullfill this request because of security reasons
118: * @exception java.io.IOException
119: * if the streaming causes an I/O problem
120: */
121: public void processAction(ActionRequest request,
122: ActionResponse response) throws PortletException,
123: java.io.IOException {
124: throw new PortletException(
125: "processAction method not implemented");
126: }
127:
128: /**
129: * The default implementation of this method sets the title
130: * using the <code>getTitle</code> method and invokes the
131: * <code>doDispatch</code> method.
132: *
133: * @param request
134: * the render request
135: * @param response
136: * the render response
137: *
138: * @exception PortletException
139: * if the portlet cannot fulfilling the request
140: * @exception UnavailableException
141: * if the portlet is unavailable to perform render 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: */
148: public void render(RenderRequest request, RenderResponse response)
149: throws PortletException, java.io.IOException {
150: response.setTitle(getTitle(request));
151: doDispatch(request, response);
152: }
153:
154: /**
155: * Used by the render method to get the title.
156: * <p>
157: * The default implementation gets the title from the ResourceBundle
158: * of the PortletConfig of the portlet. The title is retrieved
159: * using the 'javax.portlet.title' resource name.
160: * <p>
161: * Portlets can overwrite this method to provide dynamic
162: * titles (e.g. based on locale, client, and session information).
163: * Examples are:
164: * <UL>
165: * <LI>language-dependant titles for multi-lingual portals
166: * <LI>shorter titles for WAP phones
167: * <LI>the number of messages in a mailbox portlet
168: * </UL>
169: *
170: * @return the portlet title for this window
171: */
172:
173: protected java.lang.String getTitle(RenderRequest request) {
174: String title = (String) request
175: .getAttribute("com.sun.portal.portlet.DPTITLE");
176: if (title != null && title.length() > 0) {
177: if (!title.equalsIgnoreCase("javax.portlet.title"))
178: return title;
179: }
180: return config.getResourceBundle(request.getLocale()).getString(
181: "javax.portlet.title");
182: }
183:
184: /**
185: * The default implementation of this method routes the render request
186: * to a set of helper methods depending on the current portlet mode the
187: * portlet is currently in.
188: * These methods are:
189: * <ul>
190: * <li><code>doView</code> for handling <code>view</code> requests
191: * <li><code>doEdit</code> for handling <code>edit</code> requests
192: * <li><code>doHelp</code> for handling <code>help</code> requests
193: * </ul>
194: * <P>
195: * If the window state of this portlet is <code>minimized</code>, this
196: * method does not invoke any of the portlet mode rendering methods.
197: * <p>
198: * For handling custom portlet modes the portlet should override this
199: * method.
200: *
201: * @param request
202: * the render request
203: * @param response
204: * the render response
205: *
206: * @exception PortletException
207: * if the portlet cannot fulfilling the request
208: * @exception UnavailableException
209: * if the portlet is unavailable to perform render at this time
210: * @exception PortletSecurityException
211: * if the portlet cannot fullfill this request because of security reasons
212: * @exception java.io.IOException
213: * if the streaming causes an I/O problem
214: *
215: * @see #doView(RenderRequest, RenderResponse)
216: * @see #doEdit(RenderRequest, RenderResponse)
217: * @see #doHelp(RenderRequest, RenderResponse)
218: */
219: protected void doDispatch(RenderRequest request,
220: RenderResponse response) throws PortletException,
221: java.io.IOException {
222: WindowState state = request.getWindowState();
223: PortletMode mode = request.getPortletMode();
224: if (mode.equals(PortletMode.HELP)) {
225: doHelp(request, response);
226: } else if (!state.equals(WindowState.MINIMIZED)) {
227: if (mode.equals(PortletMode.VIEW)) {
228: doView(request, response);
229: } else if (mode.equals(PortletMode.EDIT)) {
230: doEdit(request, response);
231: } else {
232: throw new PortletException("unknown portlet mode: "
233: + mode);
234: }
235: }
236: }
237:
238: /**
239: * Helper method to serve up the mandatory <code>view</code> mode.
240: * <p>
241: * The default implementation throws an exception.
242: *
243: * @param request
244: * the portlet request
245: * @param response
246: * the render response
247: *
248: * @exception PortletException
249: * if the portlet cannot fulfilling the request
250: * @exception UnavailableException
251: * if the portlet is unavailable to perform render at this
252: * time
253: * @exception PortletSecurityException
254: * if the portlet cannot fullfill this request because of
255: * security reasons
256: * @exception java.io.IOException
257: * if the streaming causes an I/O problem
258: *
259: */
260:
261: protected void doView(RenderRequest request, RenderResponse response)
262: throws PortletException, java.io.IOException {
263: throw new PortletException("doView method not implemented");
264: }
265:
266: /**
267: * Helper method to serve up the <code>edit</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 doEdit(RenderRequest request, RenderResponse response)
288: throws PortletException, java.io.IOException {
289: throw new PortletException("doEdit method not implemented");
290: }
291:
292: /**
293: * Helper method to serve up the <code>help</code> mode.
294: * <p>
295: * The default implementation throws an exception.
296: *
297: * @param request
298: * the portlet request
299: * @param response
300: * the render response
301: *
302: * @exception PortletException
303: * if the portlet cannot fulfilling the request
304: * @exception UnavailableException
305: * if the portlet is unavailable to perform render at this time
306: * @exception PortletSecurityException
307: * if the portlet cannot fullfill this request because of security reasons
308: * @exception java.io.IOException
309: * if the streaming causes an I/O problem
310: */
311:
312: protected void doHelp(RenderRequest request, RenderResponse response)
313: throws PortletException, java.io.IOException {
314: throw new PortletException("doHelp method not implemented");
315:
316: }
317:
318: /**
319: * Returns the PortletConfig object of this portlet.
320: *
321: * @return the PortletConfig object of this portlet
322: */
323:
324: public PortletConfig getPortletConfig() {
325: return config;
326: }
327:
328: /**
329: * Called by the portlet container to indicate to a portlet that the portlet
330: * is being taken out of service.
331: * <p>
332: * The default implementation does nothing.
333: *
334: */
335:
336: public void destroy() {
337: // do nothing
338: }
339:
340: //-------------------------------------------------------------------------
341: // implement PortletConfig
342: //-------------------------------------------------------------------------
343:
344: /**
345: * Returns the name of this portlet.
346: *
347: * @return the portlet name
348: *
349: * @see PortletConfig#getPortletName()
350: */
351:
352: public String getPortletName() {
353: return config.getPortletName();
354: }
355:
356: /**
357: * Returns the <code>PortletContext</code> of the portlet application
358: * the portlet is in.
359: *
360: * @return the portlet application context
361: */
362:
363: public PortletContext getPortletContext() {
364: return config.getPortletContext();
365: }
366:
367: /**
368: * Gets the resource bundle for the given locale based on the
369: * resource bundle defined in the deployment descriptor
370: * with <code>resource-bundle</code> tag or the inlined resources
371: * defined in the deployment descriptor.
372: *
373: * @return the resource bundle for the given locale
374: */
375:
376: public java.util.ResourceBundle getResourceBundle(
377: java.util.Locale locale) {
378: return config.getResourceBundle(locale);
379: }
380:
381: /**
382: * Returns a String containing the value of the named initialization parameter,
383: * or null if the parameter does not exist.
384: *
385: * @param name a <code>String</code> specifying the name
386: * of the initialization parameter
387: *
388: * @return a <code>String</code> containing the value
389: * of the initialization parameter
390: *
391: * @exception java.lang.IllegalArgumentException
392: * if name is <code>null</code>.
393: */
394:
395: public String getInitParameter(java.lang.String name) {
396: return config.getInitParameter(name);
397: }
398:
399: /**
400: * Returns the names of the portlet initialization parameters as an
401: * Enumeration of String objects, or an empty Enumeration if the
402: * portlet has no initialization parameters.
403: *
404: * @return an <code>Enumeration</code> of <code>String</code>
405: * objects containing the names of the portlet
406: * initialization parameters, or an empty Enumeration if the
407: * portlet has no initialization parameters.
408: */
409:
410: public java.util.Enumeration getInitParameterNames() {
411: return config.getInitParameterNames();
412: }
413: }
|