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: * <p/>
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: * @param config a <code>PortletConfig</code> object
065: * containing the portlet
066: * configuration and initialization parameters
067: * @throws PortletException if an exception has occurred that
068: * interferes with the portlet normal
069: * operation.
070: * @throws UnavailableException if the portlet cannot perform the initialization at this time.
071: */
072:
073: public void init(PortletConfig config) throws PortletException {
074: this .config = config;
075: this .init();
076: }
077:
078: /**
079: * A convenience method which can be overridden so that there's no need
080: * to call <code>super.init(config)</code>.
081: * <p/>
082: * <p>Instead of overriding {@link #init(PortletConfig)}, simply override
083: * this method and it will be called by
084: * <code>GenericPortlet.init(PortletConfig config)</code>.
085: * The <code>PortletConfig</code> object can still be retrieved via {@link
086: * #getPortletConfig}.
087: *
088: * @throws PortletException if an exception has occurred that
089: * interferes with the portlet normal
090: * operation.
091: * @throws UnavailableException if the portlet is unavailable to perform init
092: */
093:
094: public void init() throws PortletException {
095: }
096:
097: /**
098: * Called by the portlet container to allow the portlet to process
099: * an action request. This method is called if the client request was
100: * originated by a URL created (by the portlet) with the
101: * <code>RenderResponse.createActionURL()</code> method.
102: * <p/>
103: * The default implementation throws an exception.
104: *
105: * @param request the action request
106: * @param response the action response
107: * @throws PortletException if the portlet cannot fulfilling the request
108: * @throws UnavailableException if the portlet is unavailable to process the action at this time
109: * @throws PortletSecurityException if the portlet cannot fullfill this request because of security reasons
110: * @throws java.io.IOException if the streaming causes an I/O problem
111: */
112: public void processAction(ActionRequest request,
113: ActionResponse response) throws PortletException,
114: java.io.IOException {
115: throw new PortletException(
116: "processAction method not implemented");
117: }
118:
119: /**
120: * The default implementation of this method sets the title
121: * using the <code>getTitle</code> method and invokes the
122: * <code>doDispatch</code> method.
123: *
124: * @param request the render request
125: * @param response the render response
126: * @throws PortletException if the portlet cannot fulfilling the request
127: * @throws UnavailableException if the portlet is unavailable to perform render at this time
128: * @throws PortletSecurityException if the portlet cannot fullfill this request because of security reasons
129: * @throws java.io.IOException if the streaming causes an I/O problem
130: */
131: public void render(RenderRequest request, RenderResponse response)
132: throws PortletException, java.io.IOException {
133: response.setTitle(getTitle(request));
134: doDispatch(request, response);
135: }
136:
137: /**
138: * Used by the render method to get the title.
139: * <p/>
140: * The default implementation gets the title from the ResourceBundle
141: * of the PortletConfig of the portlet. The title is retrieved
142: * using the 'javax.portlet.title' resource name.
143: * <p/>
144: * Portlets can overwrite this method to provide dynamic
145: * titles (e.g. based on locale, client, and session information).
146: * Examples are:
147: * <UL>
148: * <LI>language-dependant titles for multi-lingual portals
149: * <LI>shorter titles for WAP phones
150: * <LI>the number of messages in a mailbox portlet
151: * </UL>
152: *
153: * @return the portlet title for this window
154: */
155: protected java.lang.String getTitle(RenderRequest request) {
156: return config.getResourceBundle(request.getLocale()).getString(
157: "javax.portlet.title");
158: }
159:
160: /**
161: * The default implementation of this method routes the render request
162: * to a set of helper methods depending on the current portlet mode the
163: * portlet is currently in.
164: * These methods are:
165: * <ul>
166: * <li><code>doView</code> for handling <code>view</code> requests
167: * <li><code>doEdit</code> for handling <code>edit</code> requests
168: * <li><code>doHelp</code> for handling <code>help</code> requests
169: * </ul>
170: * <P>
171: * If the window state of this portlet is <code>minimized</code>, this
172: * method does not invoke any of the portlet mode rendering methods.
173: * <p/>
174: * For handling custom portlet modes the portlet should override this
175: * method.
176: *
177: * @param request the render request
178: * @param response the render response
179: * @throws PortletException if the portlet cannot fulfilling the request
180: * @throws UnavailableException if the portlet is unavailable to perform render at this time
181: * @throws PortletSecurityException if the portlet cannot fullfill this request because of security reasons
182: * @throws java.io.IOException if the streaming causes an I/O problem
183: * @see #doView(RenderRequest, RenderResponse)
184: * @see #doEdit(RenderRequest, RenderResponse)
185: * @see #doHelp(RenderRequest, RenderResponse)
186: */
187: protected void doDispatch(RenderRequest request,
188: RenderResponse response) throws PortletException,
189: java.io.IOException {
190: WindowState state = request.getWindowState();
191:
192: if (!state.equals(WindowState.MINIMIZED)) {
193: PortletMode mode = request.getPortletMode();
194: if (mode.equals(PortletMode.VIEW)) {
195: doView(request, response);
196: } else if (mode.equals(PortletMode.EDIT)) {
197: doEdit(request, response);
198: } else if (mode.equals(PortletMode.HELP)) {
199: doHelp(request, response);
200: } else {
201: throw new PortletException("unknown portlet mode: "
202: + mode);
203: }
204: }
205:
206: }
207:
208: /**
209: * Helper method to serve up the mandatory <code>view</code> mode.
210: * <p/>
211: * The default implementation throws an exception.
212: *
213: * @param request the portlet request
214: * @param response the render response
215: * @throws PortletException if the portlet cannot fulfilling the request
216: * @throws UnavailableException if the portlet is unavailable to perform render at this time
217: * @throws PortletSecurityException if the portlet cannot fullfill this request because of security reasons
218: * @throws java.io.IOException if the streaming causes an I/O problem
219: */
220:
221: protected void doView(RenderRequest request, RenderResponse response)
222: throws PortletException, java.io.IOException {
223: throw new PortletException("doView method not implemented");
224: }
225:
226: /**
227: * Helper method to serve up the <code>edit</code> mode.
228: * <p/>
229: * The default implementation throws an exception.
230: *
231: * @param request the portlet request
232: * @param response the render response
233: * @throws PortletException if the portlet cannot fulfilling the request
234: * @throws UnavailableException if the portlet is unavailable to perform render at this time
235: * @throws PortletSecurityException if the portlet cannot fullfill this request because of security reasons
236: * @throws java.io.IOException if the streaming causes an I/O problem
237: */
238:
239: protected void doEdit(RenderRequest request, RenderResponse response)
240: throws PortletException, java.io.IOException {
241: throw new PortletException("doEdit method not implemented");
242: }
243:
244: /**
245: * Helper method to serve up the <code>help</code> mode.
246: * <p/>
247: * The default implementation throws an exception.
248: *
249: * @param request the portlet request
250: * @param response the render response
251: * @throws PortletException if the portlet cannot fulfilling the request
252: * @throws UnavailableException if the portlet is unavailable to perform render at this time
253: * @throws PortletSecurityException if the portlet cannot fullfill this request because of security reasons
254: * @throws java.io.IOException if the streaming causes an I/O problem
255: */
256:
257: protected void doHelp(RenderRequest request, RenderResponse response)
258: throws PortletException, java.io.IOException {
259: throw new PortletException("doHelp method not implemented");
260:
261: }
262:
263: /**
264: * Returns the PortletConfig object of this portlet.
265: *
266: * @return the PortletConfig object of this portlet
267: */
268:
269: public PortletConfig getPortletConfig() {
270: return config;
271: }
272:
273: /**
274: * Called by the portlet container to indicate to a portlet that the portlet
275: * is being taken out of service.
276: * <p/>
277: * The default implementation does nothing.
278: */
279:
280: public void destroy() {
281: // do nothing
282: }
283:
284: //-------------------------------------------------------------------------
285: // implement PortletConfig
286: //-------------------------------------------------------------------------
287:
288: /**
289: * Returns the name of this portlet.
290: *
291: * @return the portlet name
292: * @see PortletConfig#getPortletName()
293: */
294:
295: public String getPortletName() {
296: return config.getPortletName();
297: }
298:
299: /**
300: * Returns the <code>PortletContext</code> of the portlet application
301: * the portlet is in.
302: *
303: * @return the portlet application context
304: */
305:
306: public PortletContext getPortletContext() {
307: return config.getPortletContext();
308: }
309:
310: /**
311: * Gets the resource bundle for the given locale based on the
312: * resource bundle defined in the deployment descriptor
313: * with <code>resource-bundle</code> tag or the inlined resources
314: * defined in the deployment descriptor.
315: *
316: * @return the resource bundle for the given locale
317: */
318:
319: public java.util.ResourceBundle getResourceBundle(
320: java.util.Locale locale) {
321: return config.getResourceBundle(locale);
322: }
323:
324: /**
325: * Returns a String containing the value of the named initialization parameter,
326: * or null if the parameter does not exist.
327: *
328: * @param name a <code>String</code> specifying the name
329: * of the initialization parameter
330: * @return a <code>String</code> containing the value
331: * of the initialization parameter
332: * @exception java.lang.IllegalArgumentException if name is <code>null</code>.
333: */
334:
335: public String getInitParameter(java.lang.String name) {
336: return config.getInitParameter(name);
337: }
338:
339: /**
340: * Returns the names of the portlet initialization parameters as an
341: * Enumeration of String objects, or an empty Enumeration if the
342: * portlet has no initialization parameters.
343: *
344: * @return an <code>Enumeration</code> of <code>String</code>
345: * objects containing the names of the portlet
346: * initialization parameters, or an empty Enumeration if the
347: * portlet has no initialization parameters.
348: */
349:
350: public java.util.Enumeration getInitParameterNames() {
351: return config.getInitParameterNames();
352: }
353: }
|