001: /*
002: * Copyright 2001 Sun Microsystems, Inc. All rights reserved.
003: * PROPRIETARY/CONFIDENTIAL. Use of this product is subject to license terms.
004: */
005:
006: package com.sun.portal.providers;
007:
008: import java.util.Map;
009: import java.net.URL;
010:
011: import javax.servlet.http.HttpServletRequest;
012: import javax.servlet.http.HttpServletResponse;
013:
014: /**
015: * <code>Provider</code> defines the interface for
016: * implementing the provider component of a channel.
017: *
018: * Desktop channels consist of two major pieces; a provider object
019: * and its runtime configuration.
020: * A provider is the programmatic entity responsible for generating
021: * channels on the desktop. There is not necessarily a one-to-one mapping
022: * between providers and channels; a single provider can generate one or
023: * more channels depending on how it is configured.
024: * <p>
025: * A provider must implement this interface. Clients of the provider
026: * interface call these
027: * methods to query information about or to cause an action in the provider.
028: * Such clients include but are not limited to the Desktop servlet and
029: * other channels (container channels).
030: * <p>
031: * There are essentially two types of methods in this interface;
032: * <ul>
033: * <li> methods that digest and compile markup. This includes
034: * getContent(), getEdit(), and processEdit().
035: * <li> methods that query information about the content provider. This
036: * includes all methods that begin with get-(minus the get- methods).
037: * </ul>
038: *
039: * The digest and compile type methods are passed in the HTTP request and
040: * response objects associated the HTTP request that caused the method to
041: * be called on the provider object.
042: *
043: * The semantics for the digest and compile methods are typically as
044: * follows: getContent() is used to return the channel's default view.
045: * The getEdit() method returns a form that allows the configuration of the
046: * channel to be modified (the "edit" view).
047: * Modifying this configuration will often but
048: * not necessarily affect the default channel view. The processEdit()
049: * method is typically used to process the form generated from the
050: * getEdit() method. Such uses of these methods is not required.
051: *
052: *
053: * Note: the request and response parameters are not the original
054: * objects that are
055: * passed by the web server to the desktop servlet. Rather, they are wrappers
056: * for those objects. There are certain methods on these objects that are
057: * not allowed from providers. These include:
058: * <p>
059: * HttpServletRequest
060: * <ul>
061: * <li> getSession(boolean)
062: * <li> isRequestedSessionIdFromCookie()
063: * <li> isRequestedSessionIdFromUrl()
064: * <li> isRequestedSessionIdValid()
065: * <li> getContentLength()
066: * <li> getInputStream()
067: * <li> getReader()
068: * </ul><p>
069: * HttpServletResponse
070: * <ul>
071: * <li> encodeRedirectUrl(String)
072: * <li> encodeUrl(String)
073: * <li> sendError(int)
074: * <li> sendError(int, String)
075: * <li> setStatus(int)
076: * <li> setStatus(int, String)
077: * <li> getOutputStream()
078: * <li> getWriter()
079: * <li> setContentLength(int)
080: * <li> setContentType(String)
081: * </ul>
082: * <p>
083: * If these methods are called, an UnsupportedOperationException is thrown.
084: * <p>
085: */
086:
087: public interface Provider {
088: /**
089: * Initializes the provider.
090: * <p>
091: * This method must be called by clients of the provider object
092: * when the provider object is created (after it is constructed, or
093: * before the object is used). This method should not be called more
094: * than once per object.
095: *
096: * @param name Unique name identifying this provider. This value
097: * should always be returned from <code>getName()</code>.
098: *
099: * @param req The HTTP request object corresponding to the HTTP request
100: * that caused this provider object to be created. This request may be
101: * used to extract session or user information that could be used to
102: * gain access to external resources.
103: *
104: * @exception ProviderException If there was an error initializing the
105: * provider. How this exception is handled is up to the client of the
106: * provider object.
107: *
108: * @see com.sun.portal.providers.Provider#getName
109: */
110: public void init(String name, HttpServletRequest req)
111: throws ProviderException;
112:
113: /**
114: * Gets the provider's objects default view.
115: * This method is called by the clients of the provider object
116: * to request the provider's default view.
117: * <p>
118: * This method may return null if the provider does not implement a default
119: * view. In this case, the provider should return false from its
120: * isPresentable() method.
121: *
122: * @return StringBuffer holding the content.
123: *
124: * @param request An HttpServletRequest that contains
125: * information related to this request for content.
126: *
127: * @param response An HttpServletResponse that allows the provider
128: * to influence the
129: * overall response for the desktop page (besides generating the content).
130: *
131: * @exception ProviderException If there was an error generating the
132: * content. How this exception is handled is up to the client of the
133: * provider object.
134: *
135: * @see com.sun.portal.providers.ProviderException
136: */
137: public StringBuffer getContent(HttpServletRequest request,
138: HttpServletResponse response) throws ProviderException;
139:
140: /**
141: * Gets the provider's default view (alternate form).
142: * <p>
143: * The adapters for the Provider class (ProfileProviderAdapter and
144: * ProviderAdapter) call this method by default from the other
145: * getContent method. This method preserves backward compatibility for
146: * older providers and it offers a simpler interface than the one
147: * that passes in the request and response.
148: *
149: * @return StringBuffer holding the html content.
150: *
151: * @param m A key-value mapping of HTTP parameters passed to the desktop
152: * by the requesting browser.
153: *
154: * @deprecated Using this method has negative performance implications.
155: * Use getContent(HttpServletRequest, HttpServletResponse) instead.
156: *
157: * @exception ProviderException If there was an error generating the
158: * content. how this exception is handled is up to the client of the
159: * provider object.
160: *
161: * @see com.sun.portal.providers.ProviderException
162: */
163: public StringBuffer getContent(Map m) throws ProviderException;
164:
165: /**
166: * Gets the edit view for the provider.
167: * <p>
168: * This method is called by the clients of the provider object
169: * to request the provider's edit view.
170: * <p>
171: * This method must generate either a complete document, or a subset,
172: * depending on the return value of <code>.getEditType()</code>.
173: * <p>
174: * A subset document should include all code that goes between
175: * the <code>FORM</code> tags. The exception is that the
176: * <i>submit</i> and <i>cancel</i> buttons should <i>not</i> be
177: * generated. A subset document is always submitted back to the
178: * desktop servlet, where control is passed to the provider's
179: * <code>processEdit()</code> method for processing the
180: * form data.
181: * <p>
182: * If a complete document is returned,
183: * there are several restrictions:
184: * <ul>
185: * <li>It must be a complete, valid form.
186: * <li>The form must have an encoding type of
187: * "application/x-www-form-urlencoded".
188: * <li>The form action must point back to the desktop servlet.
189: * Typically, this is "/ps/desktop".
190: * <li>The form must specify a valid action to the desktop servlet
191: * as defined in the DesktopSerlvet javadocs.
192: * </ul>
193: * <p><i>
194: * The above restrictions only apply if the form is to be submitted
195: * to the desktop servlet. If the form is submitted to a third-party
196: * CGI or servlet, the format will depend on what this entity is
197: * expecting.
198: * </i>
199: * <p>
200: * This method may return null if the provider does not implement an edit
201: * view. In this case, the provider should return false from its
202: * isEditable() method.
203: *
204: * @return StringBuffer holding the html edit form.
205: *
206: * @param request An HttpServletRequest that
207: * contains information related to this request for content.
208: *
209: * @param response An HttpServletResponse that
210: * allows the provider to influence the
211: * overall response for the desktop page (besides generating the content).
212: *
213: * @exception ProviderException If there was an error generating the
214: * edit form. How this exception is handled is up to the client of the
215: * provider object.
216: *
217: * @see com.sun.portal.providers.Provider#getContent
218: * @see com.sun.portal.providers.Provider#isEditable
219: * @see com.sun.portal.providers.Provider#processEdit
220: * @see com.sun.portal.providers.Provider#getEditType
221: * @see com.sun.portal.desktop.DesktopServlet
222: * @see com.sun.portal.providers.ProviderException
223: */
224: public StringBuffer getEdit(HttpServletRequest request,
225: HttpServletResponse response) throws ProviderException;
226:
227: /**
228: * Gets the edit view of the provider (alternate form).
229: * <p>
230: * The adapters for the Provider class (ProfileProviderAdapter and
231: * ProviderAdapter) call this method by default from the other
232: * getEdit() method. This method preserves backward compatibility for
233: * older providers and it offers a simpler interface than the one
234: * that passes in the request and response.
235: * <p>
236: * @return StringBuffer holding the html edit form.
237: *
238: * @param m A key-value mapping of HTTP parameters passed to the desktop
239: * by the requesting browser.
240: *
241: * @deprecated Using this method has negative performance implications.
242: * Use getEdit(HttpServletRequest, HttpServletResponse) instead.
243: *
244: * @exception ProviderException If there was an error generating the
245: * edit form. How this exception is handled is up to the client of the
246: * provider object.
247: */
248: public StringBuffer getEdit(Map m) throws ProviderException;
249:
250: /**
251: * Gets the edit form type of the provider.
252: * <p>
253: * This method returns, and therefore defines, the edit form type
254: * for provider.
255: *
256: * @return The edit type; either <code>EDIT_SUBSET</code> or
257: * <code>EDIT_COMPLETE</code>
258: *
259: * @exception UnknownEditTypeException If an unknown or undefined
260: * edit type is encountered.
261: *
262: * @see com.sun.portal.providers.Provider#getEdit
263: * @see com.sun.portal.providers.ProviderEditTypes
264: */
265: public int getEditType() throws UnknownEditTypeException;
266:
267: /**
268: * Processes a form for this provider.
269: * <p>
270: * This method is called to process form data associated with the
271: * provider. Typically, this method is called to process the edit page
272: * generated from the getEdit() method. Usually, the client calling
273: * this method on a provider object is the desktop servlet.
274: * <p>
275: * Form data, passed into this method in the request, has been decoded into
276: * Unicode.
277: * <p>
278: * When the desktop servlet receives a request where the action is
279: * "process", it looks at the
280: * parameters to identify which provider will handle the action, through
281: * this method. The request passed in contains the parameters.
282: * <p>
283: * After calling this method, the desktop servlet will re-direct to the URL
284: * returned from this method. Therefore, the result of a provider post
285: * can be any desktop serlvet action, or the content of an arbitrary URL.
286: * For more information on constructing desktop serlvet URLs, see
287: * <code>DesktopSerlvet</code>.
288: *
289: * @return The URL that the iPS desktop will re-direct to. A value
290: * of null should indicate to the client that it should return to its
291: * default view.
292: *
293: * @param request An HttpServletRequest that contains
294: * information related to this
295: * request for content.
296: *
297: * @param response An HttpServletResponse that allows the
298: * provider to influence the
299: * overall response for the desktop page (besides generating the content).
300: *
301: * @exception ProviderException If there was an error processing
302: * the edit form. How this exception is handled is up to the client of the
303: * provider object.
304: *
305: * @return The URL that the iPS desktop will re-direct to. A value
306: * of null should indicate to the client that it should return to its
307: * default view.
308: *
309: * @see com.sun.portal.providers.Provider#getEdit
310: * @see com.sun.portal.providers.Provider#isEditable
311: * @see com.sun.portal.providers.InvalidEditFormDataException
312: * @see com.sun.portal.desktop.DesktopServlet
313: */
314: public URL processEdit(HttpServletRequest request,
315: HttpServletResponse response) throws ProviderException;
316:
317: /**
318: * Processes the edit form for this provider (alternate form).
319: * <p>
320: * The adapters for the Provider class (ProfileProviderAdapter and
321: * ProviderAdapter) call this method by default from the other
322: * processEdit method. This method preserves backward compatibility for
323: * older providers and it offers a simpler interface than the one
324: * that passes in the request and response.
325: *
326: * @deprecated Using this method has negative performance implications.
327: * Use processEdit(HttpServletRequest, HttpServletResponse) instead.
328: *
329: * @param m A key-value mapping of HTTP parameters passed to the desktop
330: * by the requesting browser
331: * as returned by the ServletRequest.parsePostData() method.
332: * Maps string keys to an array of strings values.
333: * For example, to access a parameter named "foo" in the map,
334: * do the following:
335: <pre>
336: String bob = (String[])m.get("foo")[0];
337: </pre>
338: * @return The URL that the iPS desktop will re-direct to. A value
339: * of null should indicate to the client that it should return to its
340: * default view.
341: *
342: * @see com.sun.portal.providers.Provider#getEdit
343: * @see com.sun.portal.providers.Provider#isEditable
344: * @see com.sun.portal.providers.InvalidEditFormDataException
345: * @see com.sun.portal.desktop.DesktopServlet
346: */
347: public URL processEdit(Map m) throws ProviderException;
348:
349: /**
350: * This method determines if the provider has an edit view.
351: *
352: * @return <code>true</code> or <code>false</code>, indicating if the
353: * provider has an edit view.
354: * @see com.sun.portal.providers.Provider#getEdit
355: * @see com.sun.portal.providers.Provider#processEdit
356: */
357: public boolean isEditable() throws ProviderException;
358:
359: /**
360: * Determines if the provider is presentable based on the client device type.
361: *
362: * @param request An HttpServletRequest that contains
363: * the request the client made of the provider.
364: *
365: * @return <code>true</code> or <code>false</code>, indicating if the
366: * provider is presentable to the user's client device.
367: */
368: public boolean isPresentable(HttpServletRequest req);
369:
370: /**
371: * Determines if the provider is presentable based on the client device type.
372: *
373: * @deprecated Replaced by isPresentable(HttpServletRequest)
374: *
375: * @return <code>true</code> or <code>false</code>, indicating if the
376: * provider is presentable to the user's client device.
377: */
378: public boolean isPresentable();
379:
380: /**
381: * Gets the title of this provider.
382: *
383: * @return The title of this provider.
384: */
385: public String getTitle() throws ProviderException;
386:
387: /**
388: * Gets the name of this provider.
389: * <p>
390: * The name returned from this method must match the name of the provider
391: * that it was initialized with.
392: *
393: * @return The name of this provider.
394: */
395: public String getName();
396:
397: /**
398: * Gets the description of this provider.
399: *
400: * @return The description of this provider.
401: * @see com.sun.portal.providers.Provider#init
402: */
403: public String getDescription() throws ProviderException;
404:
405: /**
406: * Gets the help URL for this provider.
407: * <p>
408: * The returned help URL can be either fully-qualified URL string
409: * or a relative path. When it is relative path, the desktop software
410: * will prepend the server request string, plus the document root,
411: * plus the user locale to it to resolve the full URL.
412: * @return A URL pointing to the help page for the provider. A return
413: * value of null should signify that this provider does not have a
414: * help page.
415: *
416: */
417: public URL getHelp(HttpServletRequest req) throws ProviderException;
418:
419: /**
420: * Gets the refresh time for this provider, in seconds.
421: * <p>
422: * Clients of the provider object should use this value to determine
423: * if they should fetch a fresh default view for the provider.<br><br>
424: * If the return value from this method is X, they may choose to
425: * not fetch fresh content (and use a cached copy instead) if less than
426: * X seconds has elapsed since the last time content was fetched.
427: * <p>
428: * If provider content is expected to change very infrequently, this
429: * method can return some value so that the provider's content
430: * is not fetched every time the front page is drawn, thereby
431: * saving significant processing time.
432: * <p>
433: * Clients may choose not to use this value.
434: *
435: * @return >0, refresh time in number of seconds that a container should
436: * wait before expiring a content cache.
437: * 0, container should never cache channel's content.
438: * -1, container may cache channel's content indefinitely.
439: */
440: public long getRefreshTime() throws ProviderException;
441:
442: /**
443: * Gets the width of this provider.
444: * <p>
445: * Clients of the provider object may call this method, allowing the channel
446: * to suggest how much / what type of screen real estate it requires.
447: * The return value of this method is only a suggestion,
448: * clients are free to interpret the return value or ignore it all together.
449: *
450: * @return The width of this provider, either <code>WIDTH_THICK</code>
451: * or <code>WIDTH_THIN</code> or <code>WIDTH_FULL_TOP</code>
452: * or <code>WIDTH_FULL_BOTTOM</code>.
453: * @see com.sun.portal.providers.ProviderWidths#WIDTH_THIN
454: * @see com.sun.portal.providers.ProviderWidths#WIDTH_THICK
455: * @see com.sun.portal.providers.ProviderWidths#WIDTH_FULL_TOP
456: * @see com.sun.portal.providers.ProviderWidths#WIDTH_FULL_BOTTOM
457: * @exception ProviderException When there was an exception getting the width
458: */
459: public int getWidth() throws ProviderException;
460:
461: }
|