0001: /*
0002: * Copyright 2002 Sun Microsystems, Inc. All
0003: * rights reserved. Use of this product is subject
0004: * to license terms. Federal Acquisitions:
0005: * Commercial Software -- Government Users
0006: * Subject to Standard License Terms and
0007: * Conditions.
0008: *
0009: * Sun, Sun Microsystems, the Sun logo, and Sun ONE
0010: * are trademarks or registered trademarks of Sun Microsystems,
0011: * Inc. in the United States and other countries.
0012: */
0013: package com.sun.portal.providers.context;
0014:
0015: import java.io.File;
0016:
0017: import java.util.Iterator;
0018: import java.util.Map;
0019: import java.util.List;
0020: import java.util.Hashtable;
0021: import java.util.Locale;
0022: import java.util.Set;
0023:
0024: import java.net.URL;
0025: import java.net.MalformedURLException;
0026:
0027: import com.sun.portal.providers.ProviderEditTypes;
0028: import com.sun.portal.providers.ProviderWidths;
0029:
0030: import com.sun.portal.desktop.template.TagSwapper;
0031:
0032: import javax.servlet.http.HttpServletRequest;
0033: import javax.servlet.ServletConfig;
0034: import javax.servlet.ServletContext;
0035:
0036: /**
0037: * An environment for provider execution. More formally,
0038: * this class provides information pertaining to the container that
0039: * a provider object executes within. Such information may be specific to
0040: * the user, to the web container, or be global (shared between multiple
0041: * users). This interface does not define what information falls into
0042: * each of these categories; this is left up to the implementation. For
0043: * example, it is up to the implementation whether a user's locale
0044: * (see <code>getLocaleString()</code>
0045: * and <code>getLocale()</code>) is specific to the user
0046: * or is a global for all users.
0047: * <br><br>
0048: * At runtime, a single provider context object is shared between
0049: * all channels in the system. Methods in this interface that target
0050: * a specific channel require the channel name to be passed in as
0051: * a parameter to the method (see <code>get*Property()</code>).
0052: * <br><br>
0053: * Any container channel that wishes to make a provider context available to
0054: * its contained leaf channels must do so using an agreed-upon contract between
0055: * the container and the leaf channels. Any channels that
0056: * extends <code>ProviderAdapter</code> falls
0057: * into this category. See the <code>ProviderAdapter</code>
0058: * Javadocs for details.
0059: * <br><br>
0060: * A provider context forms the layer between the services used by the
0061: * provider and the provider code. A provider context isolates provider code
0062: * from specific service interfaces and implementations.
0063: * <br><br>
0064: * All methods in this interface may throw errors. Errors are thrown when
0065: * a serious problem arises such that a reasonable application either should
0066: * not try, or there is no clear way to resolve. The actual object thrown
0067: * will be a subclass of <code>Error</code>. This error may be caught,
0068: * if it can be handled reasonably in the application.
0069: * Applications that wish to try and
0070: * resolve such errors may catch <code>Error</code>.
0071: * The <code>get*Property()</code> and <code>set*Property()</code> methods
0072: * deserve special mention. It is considered a serious error when
0073: * an application attempts to get or set a property that does not exist.
0074: * Again, an error is thrown from these methods if the property does not exist.
0075: * The set of properties that an application uses is a
0076: * contract between the persistent store providing the properties and the
0077: * application. To avoid application errors,
0078: * the <code>exists*Property()</code> methods can be used to check for the
0079: * existence of a property. Additionally, the <code>get*Property()</code>
0080: * method versions that accept a default value may be used.
0081: * <br><br>
0082: * There is a 1-1 mapping between a session and a ProviderContext object.
0083: * Typically, there is a unique session for every client accessing the Desktop.
0084: * However, there are exceptions to this. When accessed in authless mode,
0085: * multiple clients access the same ProviderContext object and therefore
0086: * the same session.
0087: * A subset of methods in
0088: * this interface access session functionality.
0089: * These include <code>getSessionProperty(), setSessionProperty(),
0090: * getSessionID(),</code> and <code>getUserID()</code>.
0091: * The <code>getSessionProperty()</code> and <code>setSessionProperty()
0092: * </code> methods get and set properties per session,
0093: * or per ProviderContext object.
0094: * A session property is shared between all clients using the session.
0095: * In the case of authless, a session property is shared for all
0096: * authless clients.
0097: * In some cases it is desirable to set properties such that there is a
0098: * 1-1 mapping between client and property. An example of this is a
0099: * selected tab name. In the case of authless, it would not do to
0100: * have the selected tab name shared between all authless clients
0101: * because this would cause all authless clients to have the same
0102: * selected tab. To set / get properties per accessing client, use the
0103: * <code>setClientProperty()</code> and <code>getClientProperty()</code>
0104: * methods.
0105: * <br><br>
0106: * <code>ProviderContext</code>
0107: * is a generic interface, the documentation here describes
0108: * it in this light. There are implementation classes as well.
0109: * To make use of this interface, it is necessary to expose aspects of the
0110: * implementation.
0111: * While the implementation classes are private,
0112: * their semantics are documented.
0113: * Please see the iPS product documentation for details.
0114: *
0115: * @see com.sun.portal.providers.ProviderAdapter
0116: * @see com.sun.portal.providers.context.ContainerProviderContext
0117: */
0118:
0119: public interface ProviderContext {
0120:
0121: /**
0122: * Initialize this provider context.
0123: *
0124: * The request object must contain the service specific data to allow
0125: * the underlying implementation to be initialized. This data might be
0126: * cookies, HTTP headers, etc.
0127: * The details of how the request object is used is
0128: * specific to the implementation of this interface.
0129: *
0130: * @param req Request object containing service specific data.
0131: */
0132: public void init(HttpServletRequest req);
0133:
0134: /**
0135: * Causes Provider Context to throw away any cached data. This
0136: * method informs the Provider Context that the system has changed
0137: * state in a such a way that cached data (if any) should be considered
0138: * stale.
0139: * <br>
0140: * This method should be used with caution because of the obvious
0141: * performance implications. If a Provider Context caches data,
0142: * it is most likely doing so as a performance optimization.
0143: * Calling this method causes such optimizations to be negated,
0144: * until the Provider Context can re-cache the data.
0145: * <br>
0146: * For an exaple of when it makes sense to call this method,
0147: * consider the following: the Provider Context implementation
0148: * is driven by a single large chunk of data that is
0149: * read from an LDAP server. The raw data is passed to the
0150: * Provider Context by the Desktop. To be useful,
0151: * the Provider Context must parse the raw data into an
0152: * internal representation. Parsing the raw data is
0153: * expensive, so the Provider Context caches the
0154: * internal representation and does not re-generate
0155: * it every request. However, the Provider Context
0156: * must throw away the internal representation if the
0157: * raw data changes. The Desktop notifies the
0158: * Provider Context when the raw data changes
0159: * by calling refresh. This informs the Provider
0160: * Context that is must throw away the internal
0161: * representation and re-generate.
0162: */
0163: public void refresh();
0164:
0165: /**
0166: * Flags channel content as changed. Clients should use this method
0167: * to inform the Provider Context that the content for a channel
0168: * has been updated and any cached content for the channel
0169: * should be considered stale.
0170: * <br>
0171: * This method should be used with caution because of the obvious
0172: * performance implications. Content caching is done for channels
0173: * as an optimization to prevent potentially expensive calls
0174: * to get content. This method forces fresh content
0175: * to be fetched for the named channel upon the next request.
0176: * <br>
0177: * For an example of when it makes sense to use this method,
0178: * consider the case where a channel's content is affected
0179: * (only) when it's edit page is processed. For desktop
0180: * reloads, the content for the channel can be cached
0181: * indefinetly, because we know the only thing that can cause
0182: * the content to be changed is processing of its
0183: * edit page.
0184: * When the edit page is processed, we call this method
0185: * to cause any cached content for this channel to be
0186: * discarded, so the content will be regenerated based on
0187: * the processed edit page.
0188: *
0189: * @param String the channel name who's content has changed.
0190: */
0191: public void contentChanged(String channelName);
0192:
0193: /**
0194: * Flags content for all channels as changed. Clients should
0195: * use this method to inform the Provider Context that the
0196: * content for all channels has been updated and any cached
0197: * content for the channels should be considered stale.
0198: * <br>
0199: * This method should be used with caution because of the obvious
0200: * performance implications. Content caching is done for channels
0201: * as an optimization to prevent potentially expensive calls
0202: * to get content. This method forces fresh content
0203: * to be fetched from all channels.
0204: * <br>
0205: * For an example of when it makes sense to use this method,
0206: * consider the case where the locale has changed. A new
0207: * locale value means that any cached content is specific
0208: * to the old locale value. Each channel must generate new
0209: * content based on the new locale value.
0210: *
0211: */
0212: public void allContentChanged();
0213:
0214: //
0215: // service
0216: //
0217:
0218: /**
0219: * Get the Desktop URL. The Desktop URL is the absolute URL used
0220: * to access the Desktop application. For example:
0221: * <code>http://SERVER:PORT/ps/desktop</code>.
0222: *
0223: * The request object parameter is included to facilitate implementations.
0224: * It may be used to build the Desktop URL by supplying the
0225: * server, port, and protocol of the request. It is not required
0226: * that the request object be utilizied to generate the Desktop URL.
0227: *
0228: * @param req Request object containing the protocol, server, port, etc.
0229: * information required to build the Desktop URL. If the implementation
0230: * does not use the request object, this parameter may be null.
0231: * @return String representation of the URL.
0232: *
0233: */
0234: public String getDesktopURL(HttpServletRequest req);
0235:
0236: /**
0237: * Get the Desktop URL. The Desktop URL is the absolute URL used
0238: * to access the Desktop application. For example:
0239: * <code>http://SERVER:PORT/ps/desktop/pathinfo?query</code>.
0240: *
0241: * The request object parameter is included to facilitate implementations.
0242: * It may be used to build the Desktop URL by supplying the
0243: * server, port, and protocol of the request. It is not required
0244: * that the request object be utilizied to generate the Desktop URL.
0245: *
0246: * The pathInfo Map passed in as an argument will be encoded and appended
0247: * as a pathInfo to the desktopURL. The key/value pairs in the pathInfo Map
0248: * can be accessed by calling <code>req.getParameter()</code>.
0249: * path info parameters are overriden by query string params, which are
0250: * overriden by post parameters.
0251: *
0252: * query Map passed in as an argument will be appended as query string to the
0253: * desktopURL.
0254: *
0255: * This method is equivalent to calling <code>getDesktopURL()</code> if
0256: * pathInfo and query are null.
0257: *
0258: * @param req Request object containing the protocol, server, port, etc.
0259: * information required to build the Desktop URL. If the implementation
0260: * does not use the request object, this parameter may be null.
0261: * @param pathInfo Map.
0262: * @param query Map. queryString key/value pairs to be appended to URL.
0263: * @return String representation of the URL.
0264: *
0265: * @see #getDesktopURL(HttpServletRequest req)
0266: */
0267: public String getDesktopURL(HttpServletRequest req, Map query,
0268: Map pathInfo);
0269:
0270: /**
0271: * Get the Desktop URL. The Desktop URL is the absolute URL used
0272: * to access the Desktop application. For example:
0273: * <code>http://SERVER:PORT/ps/desktop/pathinfo?query</code>.
0274: *
0275: * This method internally calls <code>escape</code> to escape the desktop
0276: * url using a client specific encoder if escape flag is true.
0277: *
0278: * This method is equivalent to calling <code>getDesktopURL(req, query, pathInfo)
0279: * </code> if escape flag is false.
0280: *
0281: * @param req Request object containing the protocol, server, port, etc.
0282: * information required to build the Desktop URL. If the implementation
0283: * does not use the request object, this parameter may be null.
0284: * @param pathInfo Map.
0285: * @param query Map. queryString key/value pairs to be appended to URL.
0286: * @param escape Boolean. flag specifying whether to escape the url string
0287: * specific to the client using a client specific encoder.
0288: * @return String representation of the URL.
0289: *
0290: * @see #getDesktopURL(HttpServletRequest req, Map query, Map pathInfo)
0291: * @see #escape(String unescaped)
0292: */
0293: public String getDesktopURL(HttpServletRequest req, Map query,
0294: Map pathInfo, boolean escape);
0295:
0296: /**
0297: * Get the Desktop URL. The Desktop URL is the absolute URL used
0298: * to access the Desktop application. For example:
0299: * <code>http://SERVER:PORT/ps/desktop?queryString</code>.
0300: *
0301: * query String passed in as an argument will be appended as query string to the
0302: * desktopURL.
0303: *
0304: * This method is equivalent to calling <code>getDesktopURL()</code> if
0305: * query is null and escape flag false.
0306: *
0307: * @param req Request object containing the protocol, server, port, etc.
0308: * information required to build the Desktop URL. If the implementation
0309: * does not use the request object, this parameter may be null.
0310: * @param query String. queryString to be appended to URL.
0311: * @param escape Boolean. flag specifying whether to escape the url string
0312: * specific to the client using a client specific encoder.
0313: * @return String representation of the URL.
0314: *
0315: * @see #getDesktopURL(HttpServletRequest req)
0316: * @see #escape(String unescaped)
0317: */
0318: public String getDesktopURL(HttpServletRequest req, String query,
0319: boolean escape);
0320:
0321: /**
0322: * Get the string form of the locale.
0323: *
0324: * The various locale suffixes are combined together using the
0325: * underscore character ("_") as:<br>
0326: * LANG_COUNTRY_VARIANT
0327: * <br><br>
0328: * If a particular suffix is not present, then it is ommited from the string.
0329: * An example for a language setting of "en", and country setting of "US"
0330: * is "en_US".
0331: *
0332: * @return String representation of the locale.
0333: */
0334: public String getLocaleString();
0335:
0336: /**
0337: * Get the locale.
0338: *
0339: * @return Java <code>Locale</code>
0340: * object representation of the locale.
0341: * @see java.util.Locale
0342: */
0343: public Locale getLocale();
0344:
0345: /**
0346: * Get the Desktop type.
0347: *
0348: * The Desktop type, or also known as template type, is a string that
0349: * is one of several indexes used to lookup Desktop templates and JSP
0350: * files. The Desktop type is typically used to group such Desktop
0351: * customization files to provide different themes.
0352: *
0353: * @return Desktop type as a string.
0354: */
0355: public String getDesktopType();
0356:
0357: /**
0358: * Get the logout URL.
0359: *
0360: * The result of making a connection to the logout URL is typcically
0361: * the termination of the user's session. What actually happens is
0362: * dependent on the application receiving the URL connection.
0363: * <br><br>
0364: * Providers may use this value to generate links that allow the user
0365: * to end their session.
0366: *
0367: * @return Logout URL as a string.
0368: */
0369: public String getLogoutURL();
0370:
0371: /**
0372: * Get the login URL.
0373: *
0374: * Providers may use this value to generate links to the login url.
0375: * The URL returned from this method is encoded.
0376: *
0377: * @return Login URL as a string.
0378: */
0379: public String getLoginURL();
0380:
0381: /**
0382: * Get a string attribute.
0383: *
0384: * "Attributes" are settings that are not
0385: * channel-specific. An example of an attribute might be the user's
0386: * first and last name. Channel-specific settings are called
0387: * "properties".
0388: * Properties can be retrieved by calling the
0389: * <code>get*Property()</code> methods.
0390: * Whether
0391: * a particular value is considered a property or an attribute depends
0392: * on the underlying implementation of <code>ProviderContext</code>.
0393: *
0394: * @param name Attribute name.
0395: * @return Attribute value as a string. If attribute is
0396: * not not found, null is returned.
0397: */
0398: public String getStringAttribute(String name);
0399:
0400: /**
0401: * Get a localised string attribute if available.
0402: *
0403: * "Attributes" are settings that are not
0404: * channel-specific. An example of an attribute might be the user's
0405: * first and last name. This API will check if localized sub attribute
0406: * is available for any given locale. If the sub attribute(ex:cn;lang-ja) is available,
0407: * the value of sub attribute is returned. If the sub-attribute is NULL,
0408: * it will fetch the value of the attribute.Also note that this API performs fallback
0409: *mechanism to find out the localised value. Hence the value returned by
0410: * <code>getStringAttribute("cn", Locale.Japanese)</code> is not necessarily the value
0411: *of the attribute cn;lang-ja, it might be the value of attribte "cn"
0412: *
0413: * Channel-specific settings are called
0414: * "properties".
0415: * Properties can be retrieved by calling the
0416: * <code>get*Property()</code> methods.
0417: * Whether
0418: * a particular value is considered a property or an attribute depends
0419: * on the underlying implementation of <code>ProviderContext</code>.
0420: *
0421: * @param name Attribute name.
0422: * @return Attribute value as a string. If attribute is
0423: * not not found, null is returned.
0424: */
0425: public String getStringAttribute(String name, Locale locale);
0426:
0427: /**
0428: * Sets a string attribute.
0429: *
0430: * "Attributes" are settings that are not
0431: * channel-specific. An example of an attribute might be the user's
0432: * first and last name. Channel-specific settings are called
0433: * "properties".
0434: * Properties can be set by calling the
0435: * <code>set*Property()</code> methods.
0436: * Whether
0437: * a particular value is considered a property or an attribute depends
0438: * on the underlying implementation of <code>ProviderContext</code>.
0439: *
0440: * @param name Attribute name.
0441: * @param name Attribute value.
0442: */
0443: public void setStringAttribute(String name, String val);
0444:
0445: /**
0446: * Encodes a URL.
0447: *
0448: * Rewrite the URL to include the session id.
0449: *
0450: * @param url The URL to be encoded.
0451: */
0452: public String encodeURL(String url);
0453:
0454: //
0455: // servlet request
0456: //
0457:
0458: /**
0459: * Get the request server.
0460: *
0461: * This is a replacement for
0462: * <code>HttpUtils.getRequestURL()</code> because the version of
0463: * that method does not use the
0464: * Host HTTP header field to reconstruct the URL.
0465: * The difference in this
0466: * version is that it grabs the servername:port
0467: * from the Host header if it is
0468: * there.
0469: *
0470: * @param req HTTP request object to grab the server information from.
0471: * @return Buffer containing the request server.
0472: * @see javax.servlet.http.HttpUtils#getRequestURL(HttpServletRequest)
0473: */
0474: public StringBuffer getRequestServer(HttpServletRequest req);
0475:
0476: //
0477: // client
0478: //
0479:
0480: /**
0481: * Get a client type property for the user's client type.
0482: *
0483: * @param key Property key.
0484: * @return Property value.
0485: * @see #getClientType()
0486: */
0487: public String getClientTypeProperty(String key);
0488:
0489: /**
0490: * Get a client type property for the given client type.
0491: *
0492: * @param clientType Client type to get the property from.
0493: * @param key Property key.
0494: * @return Property value.
0495: */
0496: public String getClientTypeProperty(String clientType, String key);
0497:
0498: /**
0499: * Get a set of client type properties for the given client type.
0500: *
0501: * @param clientType Client type to get the property keys from.
0502: * @param key Property key.
0503: * @return Set of property values.
0504: */
0505: public Set getClientTypeProperties(String clientType, String key);
0506:
0507: /**
0508: * Get the default client type.
0509: *
0510: * @return Default client type.
0511: */
0512: public String getDefaultClientType();
0513:
0514: /**
0515: * Get the client type. There is no requirement as to how the client
0516: * type is determined. It may be hardcoded, derived from the session,
0517: * or otherwise.
0518: *
0519: * @return Client type.
0520: */
0521: public String getClientType();
0522:
0523: /**
0524: * Get the character set.
0525: *
0526: * The character set is used for decoding input and encoding output.
0527: *
0528: * @return Character set.
0529: */
0530: public String getCharset();
0531:
0532: /**
0533: * Get the client path.
0534: *
0535: * The client path is one of several components used to lookup Desktop
0536: * templates and JSPs. This allows the lookup to be client-specific.
0537: *
0538: * @return Client path.
0539: */
0540: public String getClientPath();
0541:
0542: /**
0543: * Get the content type.
0544: *
0545: * This value is used to determine if a provider is able to produce content
0546: * for the client's device.
0547: *
0548: * @return a <code>String</code> value
0549: */
0550: public String getContentType();
0551:
0552: /**
0553: * Escapes a String
0554: *
0555: * This method escapes the string using an encoder class that encodes a
0556: * specific type of markup. This method is used to allow provider code to
0557: * encode content in a device-unaware manner.
0558: * <br><br>
0559: * The following is an example usage of this method, and
0560: * illustrates how to encode content in a device-unaware
0561: * fashion:<br><br>
0562: * <code>
0563: * String unencoded = "<this><is><a><test>";<br>
0564: * String encoded = escape(unencoded);<br>
0565: * </code><br><br>
0566: * The encoder class name used by this method is read from a client type
0567: * property keyed "encoderClassName". If this property does not
0568: * exist, <code>EncoderClassNames.ENCODER_DEFAULT</code>
0569: * is assumed.
0570: *
0571: * @param unescaped. String to escape
0572: * @return String. escaped String
0573: */
0574: public String escape(String unescaped)
0575: throws ProviderContextException;
0576:
0577: //
0578: // session
0579: //
0580:
0581: /**
0582: * Get a session property.
0583: *
0584: * There is a 1-1 mapping between a session and a ProviderContext
0585: * object. Session properties are therefore specific to a
0586: * and instance of a ProviderContext object.
0587: * Session properties are made available for garbage
0588: * collection when the session ends.
0589: *
0590: * @param name Property name.
0591: * @return Property value. If the property is
0592: * not not found, then null is returned.
0593: */
0594: public Object getSessionProperty(String name);
0595:
0596: /**
0597: * Set a session property.
0598: *
0599: * There is a 1-1 mapping between a session and a ProviderContext
0600: * object. Session properties are therefore specific to a
0601: * and instance of a ProviderContext object.
0602: * Session properties are made available for garbage
0603: * collection when the session ends.
0604: *
0605: * @param name The property name.
0606: * @param value The property value.
0607: */
0608: public void setSessionProperty(String name, Object val);
0609:
0610: /**
0611: * Get the unique session identifier.
0612: *
0613: * The format of the return value is implementation specific. The only
0614: * guarantee is that it is unique (each user session has a unique
0615: * session ID).
0616: *
0617: * @return Session ID.
0618: */
0619: public String getSessionID();
0620:
0621: /**
0622: * Get if the current Desktop session is non-authenticated (authless).
0623: * Authless Desktop sessions are created by the Desktop and are not subject
0624: * to the normal authentication process that is required for authenticated
0625: * Desktop sessions. When writing providers to be used in the context of
0626: * an authless Desktop, it is important to keep several factors in mind.
0627: * It is typical that many clients will be accessing a single authless
0628: * Desktop session. The implication is that changing properties for an
0629: * authless channel affects all accessing clients. Normally, authless
0630: * providers are configured to hold state in client properties instead of
0631: * provider properties. Desktop session properties are per-Desktop session;
0632: * any Desktop session properties that are set for an authless user are
0633: * shared among all authless users. There can be many authless Desktop
0634: * sessions; such sessions are associated with a particular user ID.
0635: *
0636: * @param req Request object .
0637: *
0638: * @return <code>true</code> if the current Desktop session is an authless
0639: * session otherwise <code>false</code>.
0640: */
0641: public boolean isAuthless(HttpServletRequest req);
0642:
0643: /**
0644: * Get the authentication type.
0645: *
0646: * The method returns a string denoting the authentication type that was
0647: * used for the current session. No assumptions can be made about the
0648: * format of the returned string.
0649: *
0650: * @return a <code>String</code>, the authentication type.
0651: */
0652: public String getAuthenticationType();
0653:
0654: /**
0655: * Get the user identifier.
0656: *
0657: * The format of the return value is implementation specific. There is
0658: * no guarantee that this value is unique (there may be multiple user
0659: * sessions for a given user identifier).
0660: *
0661: * @return User identifier.
0662: */
0663: public String getUserID();
0664:
0665: //
0666: // client properties (per client)
0667: //
0668:
0669: /**
0670: * Get a client property.
0671: *
0672: * Client properties are specific to the particular client
0673: * accessing the portal, not to the ProviderContext object
0674: * used to access them.
0675: * <br>
0676: * Client properties are only guaranteed to persist for the
0677: * life of the request, although typically they will
0678: * persist for the life of the session.
0679: **
0680: * @param name a <code>String</code>, the property name.
0681: * @return a <code>String</code>, the property value.
0682: */
0683: public String getClientProperty(String name);
0684:
0685: /**
0686: * Set a client property.
0687: *
0688: * Client properties are specific to the particular client
0689: * accessing the portal, not to the ProviderContext object
0690: * used to access them. In some cases, there is a 1-1
0691: * mapping between client device and ProviderContext
0692: * object, however, client code cannot make this assumption.
0693: * <br>
0694: * Client properties are only guaranteed to persist for the
0695: * life of the request, although typically they will
0696: * persist for the life of the session.
0697: *
0698: * @param name a <code>String</code>, the property name.
0699: * @param value <code>String</code>, the property value.
0700: */
0701: public void setClientProperty(String name, String value);
0702:
0703: //
0704: // debug
0705: //
0706:
0707: /**
0708: * Get if the debug is enabled
0709: *
0710: * @return <code>true</code> if the debugging is on,
0711: * otherwise <code>false</code>.
0712: */
0713: public boolean isDebugEnabled();
0714:
0715: /**
0716: * Get if the debug is set to error
0717: *
0718: * @return <code>true</code> if the debugging level is set to error,
0719: * otherwise <code>false</code>.
0720: */
0721: public boolean isDebugErrorEnabled();
0722:
0723: /**
0724: * Get if the debug level is set to warning or higher.
0725: *
0726: * @return <code>true</code> if the debugging level is set to warning
0727: * or higher, otherwise <code>false</code>.
0728: */
0729: public boolean isDebugWarningEnabled();
0730:
0731: /**
0732: * Get if the debug level is set to message or higher.
0733: *
0734: * @return <code>true</code> if the debugging level is set to message
0735: * or higher, otherwise <code>false</code>.
0736: */
0737: public boolean isDebugMessageEnabled();
0738:
0739: /**
0740: * logs a message if the debugging level is "message" or higher.
0741: * The location
0742: * to store debugging messages is implementation dependent.
0743: *
0744: * @param o Object to debug (o.toString() is logged).
0745: */
0746: public void debugMessage(Object o);
0747:
0748: /**
0749: * Logs a message if the debugging level is "warning" or higher.
0750: * The location
0751: * to store debugging messages is implementation dependent.
0752: *
0753: * @param o Object to debug (o.toString() is logged).
0754: */
0755: public void debugWarning(Object o);
0756:
0757: /**
0758: * Logs a message if the debugging level is "error". The location
0759: * to store debugging messages is implementation dependent.
0760: *
0761: * @param o Object to debug (o.toString() is logged).
0762: */
0763: public void debugError(Object o);
0764:
0765: /**
0766: * Logs a message and stack trace
0767: * if the debugging level is "message" or higher.
0768: * The location
0769: * to store debugging messages is implementation dependent.
0770: *
0771: * @param o Object to debug (o.toString() is logged).
0772: * @param t Throwable object to log a stack trace of.
0773: */
0774: public void debugMessage(Object o, Throwable t);
0775:
0776: /**
0777: * Logs a message and stack trace if the debugging
0778: * level is "warning" or higher.
0779: * The location
0780: * to store debugging messages is implementation dependent.
0781: *
0782: * @param o Object to debug (o.toString() is logged).
0783: * @param t Throwable object to log a stack trace of.
0784: */
0785: public void debugWarning(Object o, Throwable t);
0786:
0787: /**
0788: * Logs a message and stack trace, if the debugging level is "error".
0789: * The location
0790: * to store debugging messages is implementation dependent.
0791: *
0792: * @param o Object to debug (o.toString() is logged).
0793: * @param t Throwable object to print a stack trace of.
0794: */
0795: public void debugError(Object o, Throwable t);
0796:
0797: //
0798: // template
0799: //
0800:
0801: /**
0802: * Get a desktop template.
0803: *
0804: * The actual template buffer returned is based on the Desktop type,
0805: * locale, channel, client type, and the template name.
0806: *
0807: * @param name Channel name
0808: * @param file Template name to return.
0809: * @return Buffer containng the template.
0810: * @exception ProviderContextException if an error occurs in getting the
0811: * desktop template.
0812: */
0813: public StringBuffer getTemplate(String name, String file)
0814: throws ProviderContextException;
0815:
0816: /**
0817: * Get a desktop template.
0818: *
0819: * The actual template buffer returned is based on the Desktop type,
0820: * locale, channel, client type, and the template name.
0821: *
0822: * @param desktopType Desktop type.
0823: * @param locale Locale.
0824: * @param name Channel name.
0825: * @param cilentType client type.
0826: * @param file Template name to return.
0827: * @param baseDir the base directory from which the lookup mechanism
0828: * begins its lookup.
0829: * @return Buffer containng the template.
0830: * @exception ProviderContextException if an error occurs in getting the
0831: * desktop template.
0832: */
0833: public StringBuffer getTemplate(String desktopType, String locale,
0834: String name, String clientType, String file, String baseDir)
0835: throws ProviderContextException;
0836:
0837: /**
0838: * Get and tag swaps a desktop template.
0839: *
0840: * The actual template buffer returned is based on the the name,
0841: * locale, client path, and Desktop type.
0842: *
0843: * @param name Channel name
0844: * @param file Template name to return
0845: * @param table Tag table to use for tag swapping.
0846: * @return Buffer containng the template.
0847: * @exception ProviderContextException if an error occurs in getting or
0848: * tag swapping the desktop template.
0849: */
0850: public StringBuffer getTemplate(String name, String file,
0851: Hashtable table) throws ProviderContextException;
0852:
0853: /**
0854: * Get and tag swaps a desktop template.
0855: *
0856: * The actual template buffer returned is based on the the name,
0857: * locale, client path, and Desktop type.
0858: *
0859: * @param desktopType Desktop type.
0860: * @param locale Locale.
0861: * @param name Channel name.
0862: * @param cilentType client type.
0863: * @param file Template name to return.
0864: * @param table Tag table to use for tag swapping.
0865: * @param baseDir the base directory from which the lookup mechanism
0866: * begins its lookup.
0867: * @return Buffer containng the template.
0868: * @exception ProviderContextException if an error occurs in getting or
0869: * tag swapping the desktop template.
0870: */
0871: public StringBuffer getTemplate(String desktopType, String locale,
0872: String name, String clientType, String file,
0873: Hashtable table, String baseDir)
0874: throws ProviderContextException;
0875:
0876: /**
0877: * Get the template path for the given channel name and the given
0878: * template name.
0879: *
0880: * If non-null, the key returned by this method will map to a valid
0881: * template file. The format of the returned path is implementation
0882: * dependent.
0883: *
0884: * @param name Channel name.
0885: * @param file The template name, or <code>null</code> if the template
0886: * for the name does not exist.
0887: * @return Path key to access the template.
0888: * @exception ProviderContextException if an error occurs in getting the
0889: * template path.
0890: */
0891: public File getTemplatePath(String name, String file)
0892: throws ProviderContextException;
0893:
0894: /**
0895: * Get the template path for the given channel name and the given
0896: * template name.
0897: *
0898: * If non-null, the key returned by this method will map to a valid
0899: * template file. The format of the returned path is implementation
0900: * dependent.
0901: *
0902: * @param desktopType Desktop type.
0903: * @param locale Locale.
0904: * @param name Channel name.
0905: * @param cilentType client type.
0906: * @param file The template name.
0907: * @param baseDir the base directory from which the lookup mechanism
0908: * begins its lookup.
0909: * @return Path key to access the template.
0910: * @exception ProviderContextException if an error occurs in getting the
0911: * template path.
0912: */
0913: public File getTemplatePath(String desktopType, String locale,
0914: String name, String clientType, String file, String baseDir)
0915: throws ProviderContextException;
0916:
0917: /**
0918: * Get the most specific template path for the given channel name and the
0919: * given template name. The file returned may not exist at all.
0920: *
0921: * If non-null, the key returned by this method will map to the most specific
0922: * template file. The file may or may not exist. The format of the returned
0923: * path is implementation
0924: * dependent.
0925: *
0926: * @param name Channel name.
0927: * @param file The template name, or <code>null</code> if the template
0928: * for the name does not exist.
0929: * @return Path key to access the template.
0930: * @exception ProviderContextException if an error occurs in getting the
0931: * most specific template path.
0932: */
0933: public File getTemplateMostSpecificPath(String name, String file)
0934: throws ProviderContextException;
0935:
0936: /**
0937: * Get the most specific template path for the given channel name and the
0938: * given template name. The file returned may not exist at all.
0939: *
0940: * If non-null, the key returned by this method will map to the most specific
0941: * template file. The file may or may not exist. The format of the returned
0942: * path is implementation
0943: * dependent.
0944: *
0945: * @param desktopType Desktop type.
0946: * @param locale Locale.
0947: * @param name Channel name.
0948: * @param cilentType client type.
0949: * @param file The template name.
0950: * @param baseDir the base directory from which the lookup mechanism
0951: * begins its lookup.
0952: * @return Path key to access the template.
0953: * @exception ProviderContextException if an error occurs in getting the
0954: * most specific template path.
0955: */
0956: public File getTemplateMostSpecificPath(String desktopType,
0957: String locale, String name, String clientType, String file,
0958: String baseDir) throws ProviderContextException;
0959:
0960: //
0961: // properties
0962: //
0963:
0964: /**
0965: * Get the class name for the provider class that this object will be
0966: * providing an environment for. This class name returned must implement
0967: * the provider interface.
0968: * This method is used to construct the provider object. It is used
0969: * by container channels.
0970: *
0971: * @param channel Channel name.
0972: * @return String fully qualified class name
0973: * (com.sun.portal.providers.foo.FooProvider).
0974: * @exception ProviderContextException if an error occurs in getting the
0975: * class name.
0976: */
0977: public String getClassName(String channel)
0978: throws ProviderContextException;
0979:
0980: /**
0981: * Get the name of the provider that backs the channel that this object
0982: * provides an environment for.
0983: *
0984: * The format of the provider name is implementation dependent.
0985: * The provider name is not necessarily equal to the provider class name
0986: * (see <code>getProviderClassName()</code>).
0987: *
0988: * @param channel Channel name.
0989: * @return Provider name.
0990: * @exception ProviderContextException if an error occurs in getting the
0991: * provider name.
0992: */
0993: public String getProviderName(String channel)
0994: throws ProviderContextException;
0995:
0996: /**
0997: * Get the version of the provider schema for the named channel.
0998: *
0999: * The provider schema defines what properties are available to a provider.
1000: * Depending on the schema version number, the provider can assume the
1001: * existence of and appropriate defaults for particular channel properties.
1002: *
1003: * The exact set of properties that a particular schema version maps to is
1004: * documented in the product manuals, for each provider.
1005: *
1006: * Additionally, the exists*Property() methods may be used to determine
1007: * the presence or absence of specific properties.
1008: *
1009: * The return value from this method does not indicate the version of the
1010: * provider class being used for the channel.
1011: *
1012: * @return Provider version.
1013: * @see #existsStringProperty(String, String)
1014: * @see #existsStringProperty(String, String, List)
1015: * @see #existsStringProperty(String, String, boolean)
1016: * @see #existsBooleanProperty(String, String)
1017: * @see #existsBooleanProperty(String, String, List)
1018: * @see #existsIntegerProperty(String, String)
1019: * @see #existsIntegerProperty(String, String, List)
1020: * @see #existsCollectionProperty(String, String)
1021: * @see #existsCollectionProperty(String, String, List)
1022: * @see #existsCollectionProperty(String, String, boolean)
1023: */
1024: public int getProviderVersion(String channel)
1025: throws ProviderContextException;
1026:
1027: /**
1028: * Get property names for the channel.
1029: *
1030: * @param channel Channel name.
1031: * @return <code>Iterator</code> over <code>String</code> objects.
1032: * @exception ProviderContextException if an error occurs in getting the
1033: * property names.
1034: */
1035: public Iterator getNames(String channel)
1036: throws ProviderContextException;
1037:
1038: /**
1039: * Get a property. The value retured from this method is a Java
1040: * <code>Object</code>, of type <code>String</code>, <code>Integer</code>,
1041: * <code>Boolean</code>, or <code>Map</code>.
1042: *
1043: * @param channel Channel name.
1044: * @param name Property name.
1045: * @return Property value.
1046: * @exception ProviderContextException if an error occurs in getting the
1047: * property.
1048: */
1049: public Object getProperty(String channel, String name)
1050: throws ProviderContextException;
1051:
1052: /**
1053: * TBD
1054: */
1055: public void setProperty(String channel, String key, Object val)
1056: throws ProviderContextException;
1057:
1058: /**
1059: * Get a property. The value retured from this method is a Java
1060: * <code>Object</code>, of type <code>String</code>, <code>Integer</code>,
1061: * <code>Boolean</code>, or <code>Map</code>.
1062: * If the property does not exist, then the default value is
1063: * returned.
1064: *
1065: * @param channel Channel name.
1066: * @param name Property name.
1067: * @param def Default value.
1068: * @return Property value.
1069: * @exception ProviderContextException if an error occurs in setting the
1070: * property.
1071: */
1072: public Object getProperty(String channel, String name, Object def)
1073: throws ProviderContextException;
1074:
1075: /**
1076: * Get a String property.
1077: *
1078: * @param channel Channel name.
1079: * @param name Property name.
1080: * @return Property value.
1081: * @exception ProviderContextException if an error occurs in getting the
1082: * String property.
1083: */
1084: public String getStringProperty(String channel, String name)
1085: throws ProviderContextException;
1086:
1087: /**
1088: * Get the filtered String property.
1089: *
1090: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1091: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1092: * determines the order that the property is searched.
1093: * If there is no property that exactly matches the filter criteria,
1094: * the best partial match is returned. When there is not even a
1095: * partial match, an unfiltered property is returned.
1096: *
1097: * @param channel Channel name.
1098: * @param name Property name.
1099: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1100: * @return Property value.
1101: * @exception ProviderContextException if an error occurs in getting the
1102: * the filtered String property.
1103: *
1104: * @see PropertiesFilter
1105: */
1106: public String getStringProperty(String channel, String name,
1107: List pflist) throws ProviderContextException;
1108:
1109: /**
1110: * Get the filtered String property.
1111: *
1112: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1113: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1114: * determines the order that the property is searched.
1115: * If there is no property that exactly matches the filter criteria,
1116: * null value is returned
1117: *
1118: * @param channel Channel name.
1119: * @param name Property name.
1120: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1121: * @return Property value.
1122: * @exception ProviderContextException if an error occurs in getting the
1123: * the filtered String property.
1124: *
1125: * @see PropertiesFilter
1126: */
1127: public String getStringProperty(String channel, String name,
1128: List pflist, boolean exact) throws ProviderContextException;
1129:
1130: /**
1131: * Get a String property. This method returns a default value if the
1132: * property does not exist.
1133: *
1134: * @param channel Channel name.
1135: * @param name Property name.
1136: * @param def Default value.
1137: * @return Property value.
1138: * @exception ProviderContextException if an error occurs in getting the
1139: * String property.
1140: */
1141: public String getStringProperty(String channel, String name,
1142: String def) throws ProviderContextException;
1143:
1144: /**
1145: * Get the filtered String property.
1146: * This method returns a default value if the property does not exist.
1147: *
1148: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1149: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1150: * determines the order that the property is searched.
1151: * If there is no property that exactly matches the filter criteria,
1152: * the best partial match is returned. When there is not even a
1153: * partial match, an unfiltered property is returned.
1154: *
1155: * @param channel Channel name.
1156: * @param name Property name.
1157: * @param def Default value.
1158: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1159: * @return Property value.
1160: * @exception ProviderContextException if an error occurs in getting the
1161: * the filtered String property.
1162: *
1163: * @see PropertiesFilter
1164: */
1165: public String getStringProperty(String channel, String name,
1166: String def, List pflist) throws ProviderContextException;
1167:
1168: /**
1169: * Get the localized version of a String property.
1170: *
1171: * Locales are searched from more to less
1172: * specific. For example, for a locale setting of "en_US_WE", the search
1173: * order would be: en_US_WE, en_US, en. If the locale-specific property
1174: * is not found, then the non-locale-specific version is returned
1175: * (if it exists).
1176: *
1177: * @param channel Channel name.
1178: * @param name Property name.
1179: * @param localized Search for a localized version?
1180: * @return Property value.
1181: * @exception ProviderContextException if an error occurs in getting the
1182: * localized version of the String property.
1183: */
1184: public String getStringProperty(String channel, String name,
1185: boolean localized) throws ProviderContextException;
1186:
1187: /**
1188: * Get the localized version of a String property.
1189: * This method returns a default value if the
1190: * property does not exist.
1191: *
1192: * Locales are searched from more to less
1193: * specific. For example, for a locale setting of "en_US_WE", the search
1194: * order would be: en_US_WE, en_US, en. If the locale-specific property
1195: * is not found, then the non-locale-specific version is returned
1196: * (if it exists).
1197: *
1198: * @param channel Channel name.
1199: * @param name Property name.
1200: * @param def Default value.
1201: * @param localized Search for a localized version?
1202: * @return Property value.
1203: * @exception ProviderContextException if an error occurs in getting the
1204: * localized version of the String property.
1205: */
1206: public String getStringProperty(String channel, String name,
1207: String def, boolean localized)
1208: throws ProviderContextException;
1209:
1210: /**
1211: * Sets a string property.
1212: *
1213: * @param channel Channel name.
1214: * @param name Property name.
1215: * @param value Property value.
1216: * @exception ProviderContextException if an error occurs in setting the
1217: * String property.
1218: */
1219: public void setStringProperty(String channel, String key, String val)
1220: throws ProviderContextException;
1221:
1222: /**
1223: * Sets a string property according to the given filter criteria.
1224: *
1225: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1226: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1227: * determines the order that the property is searched.
1228: * If the property that matches the filter criteria does not exist,
1229: * the most specific, existing property gets set.
1230: * If only the default value existed, it sets the default value. If the default
1231: * and filtered properties existed, it sets the most specific existing filtered
1232: * property.
1233: * Note that the "exact" flag in the <code>PropertiesFilter</code>s has no meaning
1234: * and will be ignored.
1235: *
1236: * @param channel Channel name.
1237: * @param name Property name.
1238: * @param value Property value.
1239: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1240: * @exception ProviderContextException if an error occurs in setting the
1241: * String property.
1242: *
1243: * @see PropertiesFilter
1244: */
1245: public void setStringProperty(String channel, String key,
1246: String val, List pflist) throws ProviderContextException;
1247:
1248: /**
1249: * Get a collection property.
1250: *
1251: * Here, a collection is used to refer to a multi-value property.
1252: * Depending on the context, it is either the analogue of
1253: * Java <code>Maps</code> or <code>List</code>. For <code>List</code>,
1254: * the returned Java <code>Map</code> object
1255: * contains key-value pairs where the key equals the value. For example,
1256: * to treat the <code>Map</code> object as a List, do the following:
1257: * <br><br>
1258: * <code>Set list = map.keySet();<br><br></code>
1259: * <p/>
1260: * The Java <code>Map</code> object returned from this method
1261: * does not fronts the persistent store for the property.
1262: * Changes to the return value are not persisted.<br>
1263: * Changes must be persisted with
1264: * <code>setMapProperty()</code> call.
1265: * For example, <br><br>
1266: * <code>
1267: * Map m = pc.getCollectionProperty("foo");<br>
1268: * m.put("a", "1");<br>
1269: * pc.setCollectionProperty("foo", m);<br><br>
1270: * </code>
1271: *
1272: * @param channel Channel name.
1273: * @param name Property name.
1274: * @return Property value, a Java <code>Map</code> that maps
1275: * <code>String</code>s to Java objects, either <code>String</code>,
1276: * <code>Integer</code>, <code>Boolean</code>, or <code>Map</code>.
1277: * @exception ProviderContextException if an error occurs in getting the
1278: * Collection property.
1279: * @see #setCollectionProperty(String, String, Map)
1280: * @see #setCollectionProperty(String, String, List)
1281: */
1282: public Map getCollectionProperty(String channel, String name)
1283: throws ProviderContextException;
1284:
1285: /**
1286: * Get a collection property.
1287: * This method returns a default value if the
1288: * property does not exist.
1289: *
1290: * @param channel Channel name.
1291: * @param name Property name.
1292: * @param def Default value.
1293: * @return Property value, a Java <code>Map</Map> that maps
1294: * <code>String</code>s to Java objects, either <code>String</code>,
1295: * <code>Integer</code>, <code>Boolean</code>, or <code>Map</code>.
1296: * @exception ProviderContextException if an error occurs in getting
1297: * the Collection property.
1298: * @see #getCollectionProperty(String, String)
1299: */
1300: public Map getCollectionProperty(String channel, String name,
1301: Map def) throws ProviderContextException;
1302:
1303: /**
1304: * Get the filtered Collection property.
1305: *
1306: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1307: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1308: * determines the order that the property is searched.
1309: * If there is no property that exactly matches the filter criteria,
1310: * a partial match is returned.
1311: *
1312: * @param channel Channel name.
1313: * @param name Property name.
1314: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1315: * @return Property value.
1316: * @exception ProviderContextException if an error occurs in getting the
1317: * the filtered String property.
1318: *
1319: * @see PropertiesFilter
1320: */
1321: public Map getCollectionProperty(String channel, String name,
1322: List pflist) throws ProviderContextException;
1323:
1324: /**
1325: * Get the filtered Collection property.
1326: * This method returns a default value if the property does not exist.
1327: *
1328: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1329: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1330: * determines the order that the property is searched.
1331: * If there is no property that exactly matches the filter criteria,
1332: * a partial match is returned.
1333: *
1334: * @param channel Channel name.
1335: * @param name Property name.
1336: * @param def Default value.
1337: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1338: * @return Property value.
1339: * @exception ProviderContextException if an error occurs in getting the
1340: * the filtered String property.
1341: *
1342: * @see PropertiesFilter
1343: */
1344: public Map getCollectionProperty(String channel, String name,
1345: Map def, List pflist) throws ProviderContextException;
1346:
1347: /**
1348: * Get the localized version of a collection property.
1349: *
1350: * Locales are searched from more to less
1351: * specific. For example, for a locale setting of "en_US_WE", the search
1352: * order would be: en_US_WE, en_US, en. If the locale-specific property
1353: * is not found, then the non-locale-specific version is returned
1354: * (if it exists).
1355: *
1356: * @param channel Channel name.
1357: * @param name Property name.
1358: * @param localized Search for a localized version?
1359: * @return Property value, a Java <code>Map</Map> that maps
1360: * <code>String</code>s to Java objects, either <code>String</code>,
1361: * <code>Integer</code>, <code>Boolean</code>, or <code>Map</code>.
1362: * @exception ProviderContextException if an error occurs in getting
1363: * localized version of the Collection property.
1364: * @see #getCollectionProperty(String, String)
1365: */
1366: public Map getCollectionProperty(String channel, String name,
1367: boolean localized) throws ProviderContextException;
1368:
1369: /**
1370: * Get the localized version of a collection property.
1371: *
1372: * @param channel Channel name.
1373: * @param name Property name.
1374: * @param def Default value.
1375: * @param localized Search for a localized version?
1376: * @return Property value, a Java <code>Map</Map> that maps
1377: * <code>String</code>s to Java objects, either <code>String</code>,
1378: * <code>Integer</code>, <code>Boolean</code>, or <code>Map</code>.
1379: * @exception ProviderContextException if an error occurs in getting
1380: * the localized version of the Collection property.
1381: * @see #getCollectionProperty(String, String)
1382: */
1383: public Map getCollectionProperty(String channel, String name,
1384: Map def, boolean localized) throws ProviderContextException;
1385:
1386: /**
1387: * Sets a collection property.
1388: *
1389: * @param channel Channel name.
1390: * @param key Property name.
1391: * @param value Property value.
1392: * @return New property value.
1393: * @exception ProviderContextException if an error occurs in setting
1394: * the Collection property.
1395: * @see #getCollectionProperty(String, String)
1396: */
1397: public void setCollectionProperty(String channel, String key,
1398: Map val) throws ProviderContextException;
1399:
1400: /**
1401: * Sets a collection property according to the given filter criteria.
1402: *
1403: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1404: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1405: * determines the order that the property is searched.
1406: * If the property that matches the filter criteria does not exist,
1407: * the most specific, existing property gets set.
1408: * If only the default value existed, it sets the default value. If the default
1409: * and filtered properties existed, it sets the most specific existing filtered
1410: * property.
1411: * Note that the "exact" flag in the <code>PropertiesFilter</code>s has no meaning
1412: * and will be ignored.
1413: *
1414: * @param channel Channel name.
1415: * @param key Property name.
1416: * @param value Property value.
1417: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1418: * @exception ProviderContextException if an error occurs in setting the
1419: * collection property.
1420: *
1421: * @see PropertiesFilter
1422: */
1423: public void setCollectionProperty(String channel, String key,
1424: Map val, List pflist) throws ProviderContextException;
1425:
1426: /**
1427: * Sets a collection property.
1428: *
1429: * @param channel Channel name.
1430: * @param name Property name.
1431: * @param value Proeprty value.
1432: * @exception ProviderContextException if an error occurs in setting
1433: * the Collection property.
1434: * @see #getCollectionProperty(String, String)
1435: */
1436: public void setCollectionProperty(String channel, String name,
1437: List value) throws ProviderContextException;
1438:
1439: /**
1440: * Sets a collection property according to the given filter criteria.
1441: *
1442: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1443: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1444: * determines the order that the property is searched.
1445: * If the property that matches the filter criteria does not exist,
1446: * the most specific, existing property gets set.
1447: * If only the default value existed, it sets the default value. If the default
1448: * and filtered properties existed, it sets the most specific existing filtered
1449: * property.
1450: * Note that the "exact" flag in the <code>PropertiesFilter</code>s has no meaning
1451: * and will be ignored.
1452: *
1453: * @param channel Channel name.
1454: * @param key Property name.
1455: * @param value Property value.
1456: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1457: * @exception ProviderContextException if an error occurs in setting the
1458: * collection property.
1459: *
1460: * @see PropertiesFilter
1461: */
1462: public void setCollectionProperty(String channel, String key,
1463: List val, List pflist) throws ProviderContextException;
1464:
1465: /**
1466: * Get a boolean property property.
1467: *
1468: * @param channel Channel name.
1469: * @param name Property name.
1470: * @return Property value.
1471: * @exception ProviderContextException if an error occurs in getting
1472: * the boolean property.
1473: */
1474: public boolean getBooleanProperty(String channel, String name)
1475: throws ProviderContextException;
1476:
1477: /**
1478: * Get the filtered boolean property property.
1479: *
1480: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1481: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1482: * determines the order that the property is searched.
1483: * If there is no property that exactly matches the filter criteria,
1484: * the best partial match is returned. When there is not even a
1485: * partial match, an unfiltered property is returned.
1486: *
1487: * @param channel Channel name.
1488: * @param name Property name.
1489: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1490: * @return Property value.
1491: * @exception ProviderContextException if an error occurs in getting
1492: * the boolean property.
1493: */
1494: public boolean getBooleanProperty(String channel, String name,
1495: List pflist) throws ProviderContextException;
1496:
1497: /**
1498: * Get a boolean property property.
1499: * This method returns a default value if the
1500: * property does not exist.
1501: *
1502: * @param channel Channel name.
1503: * @param name Property name.
1504: * @param def Default value.
1505: * @return Property value.
1506: * @exception ProviderContextException if an error occurs in getting
1507: * the boolean property.
1508: */
1509: public boolean getBooleanProperty(String channel, String name,
1510: boolean def) throws ProviderContextException;
1511:
1512: /**
1513: * Get the filtered boolean property property.
1514: * This method returns a default value if the
1515: * property does not exist.
1516: *
1517: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1518: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1519: * determines the order that the property is searched.
1520: * If there is no property that exactly matches the filter criteria,
1521: * the best partial match is returned. When there is not even a
1522: * partial match, an unfiltered property is returned.
1523: *
1524: * @param channel Channel name.
1525: * @param name Property name.
1526: * @param def Default value.
1527: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1528: * @return Property value.
1529: * @exception ProviderContextException if an error occurs in getting
1530: * the boolean property.
1531: */
1532: public boolean getBooleanProperty(String channel, String name,
1533: boolean def, List pflist) throws ProviderContextException;
1534:
1535: /**
1536: * Sets a boolean property.
1537: *
1538: * @param channel Channel name.
1539: * @param name Property name.
1540: * @param value Property value.
1541: * @exception ProviderContextException if an error occurs in setting
1542: * the boolean property.
1543: */
1544: public void setBooleanProperty(String channel, String name,
1545: boolean value) throws ProviderContextException;
1546:
1547: /**
1548: * Sets a boolean property according to the given filter criteria.
1549: *
1550: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1551: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1552: * determines the order that the property is searched.
1553: * If the property that matches the filter criteria does not exist,
1554: * the most specific, existing property gets set.
1555: * If only the default value existed, it sets the default value. If the default
1556: * and filtered properties existed, it sets the most specific existing filtered
1557: * property.
1558: * Note that the "exact" flag in the <code>PropertiesFilter</code>s has no meaning
1559: * and will be ignored.
1560: *
1561: * @param channel Channel name.
1562: * @param name Property name.
1563: * @param value Property value.
1564: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1565: * @exception ProviderContextException if an error occurs in setting
1566: * the boolean property.
1567: */
1568: public void setBooleanProperty(String channel, String name,
1569: boolean value, List pflist) throws ProviderContextException;
1570:
1571: /**
1572: * Get an integer property.
1573: *
1574: * @param channel Channel name.
1575: * @param name Property name.
1576: * @return Property value.
1577: * @exception ProviderContextException if an error occurs in getting
1578: * the integer property.
1579: */
1580: public int getIntegerProperty(String channel, String name)
1581: throws ProviderContextException;
1582:
1583: /**
1584: * Get the filtered integer property.
1585: *
1586: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1587: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1588: * determines the order that the property is searched.
1589: * If the property that matches the filter criteria does not exist,
1590: * a new property will be created.
1591: * Note that the "exact" flag in the <code>PropertiesFilter</code>s has no meaning
1592: * and will be ignored.
1593: *
1594: * @param channel Channel name.
1595: * @param name Property name.
1596: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1597: * @return Property value.
1598: * @exception ProviderContextException if an error occurs in getting
1599: * the integer property.
1600: */
1601: public int getIntegerProperty(String channel, String name,
1602: List pflist) throws ProviderContextException;
1603:
1604: /**
1605: * Get an integer property.
1606: * This method returns a default value if the
1607: * property does not exist.
1608: *
1609: * @param channel Channel name.
1610: * @param name Property name.
1611: * @param def Default value.
1612: * @return Property value.
1613: * @exception ProviderContextException if an error occurs in getting
1614: * the integer property.
1615: */
1616: public int getIntegerProperty(String channel, String name, int def)
1617: throws ProviderContextException;
1618:
1619: /**
1620: * Get an integer property.
1621: * This method returns a default value if the
1622: * property does not exist.
1623: *
1624: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1625: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1626: * determines the order that the property is searched.
1627: * If the property that matches the filter criteria does not exist,
1628: * a new property will be created.
1629: * Note that the "exact" flag in the <code>PropertiesFilter</code>s has no meaning
1630: * and will be ignored.
1631: *
1632: * @param channel Channel name.
1633: * @param name Property name.
1634: * @param def Default value.
1635: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1636: * @return Property value.
1637: * @exception ProviderContextException if an error occurs in getting
1638: * the integer property.
1639: */
1640: public int getIntegerProperty(String channel, String name, int def,
1641: List pflist) throws ProviderContextException;
1642:
1643: /**
1644: * Sets an integer property.
1645: *
1646: * @param channel Channel name.
1647: * @param name Property name.
1648: * @param value Property value.
1649: * @exception ProviderContextException if an error occurs in setting
1650: * the integer property.
1651: */
1652: public void setIntegerProperty(String channel, String name,
1653: int value) throws ProviderContextException;
1654:
1655: /**
1656: * Sets an integer property according to the given filter criteria.
1657: *
1658: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1659: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1660: * determines the order that the property is searched.
1661: * If the property that matches the filter criteria does not exist,
1662: * the most specific, existing property gets set.
1663: * If only the default value existed, it sets the default value. If the default
1664: * and filtered properties existed, it sets the most specific existing filtered
1665: * property.
1666: * Note that the "exact" flag in the <code>PropertiesFilter</code>s has no meaning
1667: * and will be ignored.
1668: *
1669: * @param channel Channel name.
1670: * @param name Property name.
1671: * @param value Property value.
1672: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1673: * @exception ProviderContextException if an error occurs in setting
1674: * the integer property.
1675: */
1676: public void setIntegerProperty(String channel, String name,
1677: int value, List pflist) throws ProviderContextException;
1678:
1679: /**
1680: * Test for the existence of a string property.
1681: *
1682: * @param channel Channel name.
1683: * @param name a <code>String</code>, the property name.
1684: * @return a <code>boolean</code>, <code>true</code> if the
1685: * property exists, otherwise <code>false</code>.
1686: * @exception ProviderContextException if an error occurs in testing
1687: * for the existence of a String property.
1688: */
1689: public boolean existsStringProperty(String channel, String name)
1690: throws ProviderContextException;
1691:
1692: /**
1693: * Test for the existence of a filtered string property.
1694: *
1695: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1696: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1697: * determines the order that the property is searched.
1698: * If the property that matches the filter criteria does not exist,
1699: * a new property will be created.
1700: * Note that the "exact" flag in the <code>PropertiesFilter</code>s has no meaning
1701: * and will be ignored.
1702: *
1703: * @param channel Channel name.
1704: * @param name a <code>String</code>, the property name.
1705: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1706: * existence of
1707: * localized properties.
1708: * @return a <code>boolean</code>, <code>true</code> if the
1709: * property exists, otherwise <code>false</code>.
1710: * @exception ProviderContextException if an error occurs in testing
1711: * for the existence of a String property.
1712: */
1713: public boolean existsStringProperty(String channel, String name,
1714: List pflist) throws ProviderContextException;
1715:
1716: /**
1717: * Test for the existence of a string property. This method will also
1718: * check for the existence of the localized version of the property.
1719: *
1720: * @param channel Channel name.
1721: * @param name a <code>String</code>, the property name.
1722: * @param localized a <code>boolean</code>, whether to check the
1723: * existence of
1724: * localized properties.
1725: * @return a <code>boolean</code>, <code>true</code> if the
1726: * property exists, otherwise <code>false</code>.
1727: * @exception ProviderContextException if an error occurs in testing
1728: * for the existence of a String property.
1729: */
1730: public boolean existsStringProperty(String channel, String name,
1731: boolean localized) throws ProviderContextException;
1732:
1733: /**
1734: * Test for the existence of a boolean property.
1735: *
1736: * @param channel Channel name.
1737: * @param name a <code>String</code>, the property name.
1738: * @return a <code>boolean</code>, <code>true</code> if the
1739: * property exists, otherwise <code>false</code>.
1740: * @exception ProviderContextException if an error occurs in testing
1741: * for the existence of a boolean property.
1742: */
1743: public boolean existsBooleanProperty(String channel, String name)
1744: throws ProviderContextException;
1745:
1746: /**
1747: * Test for the existence of the filtered boolean property.
1748: *
1749: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1750: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1751: * determines the order that the property is searched.
1752: * If the property that matches the filter criteria does not exist,
1753: * a new property will be created.
1754: * Note that the "exact" flag in the <code>PropertiesFilter</code>s has no meaning
1755: * and will be ignored.
1756: *
1757: * @param channel Channel name.
1758: * @param name a <code>String</code>, the property name.
1759: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1760: * @return a <code>boolean</code>, <code>true</code> if the
1761: * property exists, otherwise <code>false</code>.
1762: * @exception ProviderContextException if an error occurs in testing
1763: * for the existence of a boolean property.
1764: */
1765: public boolean existsBooleanProperty(String channel, String name,
1766: List pflist) throws ProviderContextException;
1767:
1768: /**
1769: * Test for the existence of an integer property.
1770: *
1771: * @param channel Channel name.
1772: * @param name a <code>String</code>, the property name.
1773: * @return a <code>boolean</code>, <code>true</code> if the
1774: * property exists, otherwise <code>false</code>.
1775: * @exception ProviderContextException if an error occurs in testing
1776: * for the existence of an integer property.
1777: */
1778: public boolean existsIntegerProperty(String channel, String name)
1779: throws ProviderContextException;
1780:
1781: /**
1782: * Test for the existence of the filtered integer property.
1783: *
1784: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1785: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1786: * determines the order that the property is searched.
1787: * If the property that matches the filter criteria does not exist,
1788: * a new property will be created.
1789: * Note that the "exact" flag in the <code>PropertiesFilter</code>s has no meaning
1790: * and will be ignored.
1791: *
1792: * @param channel Channel name.
1793: * @param name a <code>String</code>, the property name.
1794: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1795: * @return a <code>boolean</code>, <code>true</code> if the
1796: * property exists, otherwise <code>false</code>.
1797: * @exception ProviderContextException if an error occurs in testing
1798: * for the existence of an integer property.
1799: */
1800: public boolean existsIntegerProperty(String channel, String name,
1801: List pflist) throws ProviderContextException;
1802:
1803: /**
1804: * Test for the existence of a collection property.
1805: *
1806: * @param channel Channel name.
1807: * @param name a <code>String</code>, the property name.
1808: * @return a <code>boolean</code>, <code>true</code> if the
1809: * property exists, otherwise <code>false</code>.
1810: * @exception ProviderContextException if an error occurs in testing
1811: * for the existence of a Collection property.
1812: */
1813: public boolean existsCollectionProperty(String channel, String name)
1814: throws ProviderContextException;
1815:
1816: /**
1817: * Test for the existence of the filtered collection property.
1818: *
1819: * Filter criteria can be specified using a series of <code>PropertiesFilter</code>
1820: * objects. The order in that the <code>PropertiesFilter</code> objects are listed
1821: * determines the order that the property is searched.
1822: * If the property that matches the filter criteria does not exist,
1823: * a new property will be created.
1824: * Note that the "exact" flag in the <code>PropertiesFilter</code>s has no meaning
1825: * and will be ignored.
1826: *
1827: * @param channel Channel name.
1828: * @param name a <code>String</code>, the property name.
1829: * @param pflist An ordered list of <code>PropertiesFilter</code> objects
1830: * @return a <code>boolean</code>, <code>true</code> if the
1831: * property exists, otherwise <code>false</code>.
1832: * @exception ProviderContextException if an error occurs in testing
1833: * for the existence of a Collection property.
1834: */
1835: public boolean existsCollectionProperty(String channel,
1836: String name, List pflist) throws ProviderContextException;
1837:
1838: /**
1839: * Test for the existence of a collection property. This method will also
1840: * check for the existence of the localized version of the property.
1841: *
1842: * @param channel Channel name.
1843: * @param name a <code>String</code>, the property name.
1844: * @param localized a <code>boolean</code>, whether to check the
1845: * existence of
1846: * localized properties.
1847: * @return a <code>boolean</code>, <code>true</code> if the
1848: * property exists, otherwise <code>false</code>.
1849: * @exception ProviderContextException if an error occurs in testing
1850: * for the existence of a Collection property.
1851: */
1852: public boolean existsCollectionProperty(String channel,
1853: String name, boolean localized)
1854: throws ProviderContextException;
1855:
1856: /**
1857: * Get the locale in the form of <code>PropertiesFilter</code>'s.
1858: *
1859: * Each locale suffix is used to create <code>PropertiesFilter</code>.
1860: * Note that by default, the <code>PropertiesFilter</code> objects return
1861: * in the list are constructed with their "required" flag set to
1862: * <code>false</code>. See the javadocs for <code>PropertiesFilter</code>
1863: * for more information on the semantics of the required flag. Use
1864: * getPropertiesFilter() method should you need to customize the
1865: * required flag.
1866: *
1867: * @return List of <code>PropertiesFilter</code> objects representing
1868: * the locale setting.
1869: * @exception ProviderContextException if an error occurs in creating
1870: * PropertiesFilter objects.
1871: *
1872: * @see PropertiesFilter
1873: * @see PropertiesFilter#isRequired()
1874: */
1875: public List getLocalePropertiesFilters()
1876: throws ProviderContextException;
1877:
1878: /**
1879: * Get the client and locale in the form of <code>PropertiesFilter</code>'s.
1880: *
1881: * Each client and locale suffix is used to create <code>PropertiesFilter</code>.
1882: * Note that by default, the <code>PropertiesFilter</code> objects return
1883: * in the list are constructed with their "required" flag set to
1884: * <code>false</code>. See the javadocs for <code>PropertiesFilter</code>
1885: * for more information on the semantics of the required flag. Use
1886: * getPropertiesFilter() method should you need to customize the
1887: * required flag.
1888: *
1889: * This method is a convenience for putting together a list of properties filters
1890: * for the current session's locale and client type. the property filter list
1891: * returned from this method can be used as input to the <various get property
1892: * methods> to access properties in a locale and client type specific manner.
1893: *
1894: * @return List of <code>PropertiesFilter</code> objects representing
1895: * the client and locale setting.
1896: * @exception ProviderContextException if an error occurs in creating
1897: * PropertiesFilter objects.
1898: *
1899: * @see PropertiesFilter
1900: * @see PropertiesFilter#isRequired()
1901: * @see #getClientPropertiesFilters()
1902: * @see #getLocalePropertiesFilters()
1903: */
1904: public List getClientAndLocalePropertiesFilters()
1905: throws ProviderContextException;
1906:
1907: /**
1908: * Get the client <code>PropertiesFilter</code>'s.
1909: *
1910: * The hierarchy of client <code>PropertiesFilter</code> is returned.
1911: * Note that by default, the <code>PropertiesFilter</code> objects return
1912: * in the list are constructed with their "required" flag set to
1913: * <code>false</code>. See the javadocs for <code>PropertiesFilter</code>
1914: * for more information on the semantics of the required flag. Use
1915: * getPropertiesFilter() method should you need to customize the
1916: * required flag.
1917: *
1918: * @return List of <code>PropertiesFilter</code> objects representing
1919: * the client.
1920: * @exception ProviderContextException if an error occurs in creating
1921: * PropertiesFilter objects.
1922: *
1923: * @see PropertiesFilter
1924: * @see PropertiesFilter#isRequired()
1925: */
1926: public List getClientPropertiesFilters()
1927: throws ProviderContextException;
1928:
1929: /**
1930: * Get the client <code>PropertiesFilter</code>'s for a given clientType.
1931: *
1932: * The hierarchy of client <code>PropertiesFilter</code> is returned.
1933: * Note that by default, the <code>PropertiesFilter</code> objects return
1934: * in the list are constructed with their "required" flag set to
1935: * <code>false</code>. See the javadocs for <code>PropertiesFilter</code>
1936: * for more information on the semantics of the required flag. Use
1937: * getPropertiesFilter() method should you need to customize the
1938: * required flag.
1939: * It is advisable to use getClientPropertiesFilters() if getting the
1940: * filters for the current clientType.
1941: *
1942: * @param clientType client type.
1943: * @return List of <code>PropertiesFilter</code> objects representing
1944: * the client.
1945: *
1946: * @see PropertiesFilter
1947: * @see PropertiesFilter#isRequired()
1948: * @see #getClientPropertiesFilters()
1949: */
1950: public List getClientPropertiesFilters(String clientType);
1951:
1952: //
1953: // config
1954: //
1955:
1956: /**
1957: * Get the URI prefix to web server static content.
1958: *
1959: * Static content may be located separately from dynamic content
1960: * such as servlets and JSP.
1961: * This
1962: * URI prefix is used to access static web content such as
1963: * images and HTML files. For example, to reference an image, a the
1964: * href might look like:
1965: * <br><br>
1966: * <code>http://server:port/STATIC_URI/images/foo.gif
1967: *
1968: * @return URI prefix.
1969: */
1970: public String getStaticContentPath();
1971:
1972: /**
1973: * Get the Servlet Config.
1974: * @return ServletConfig object.
1975: * @deprecated A specific front end servlet cannot be assumed.
1976: * Therefore, programmers should not access a ServletConfig
1977: * object since it may make their Providers non-portable
1978: * to other environments. Use getServletContext() instead.
1979: * @see #getServletContext()
1980: */
1981: public ServletConfig getServletConfig();
1982:
1983: /**
1984: * Get the Servlet Context.
1985: * @return ServletContext object.
1986: */
1987: public ServletContext getServletContext();
1988:
1989: /**
1990: * Get the default channel name.
1991: * This method returns the channel name from the session
1992: * using <code>getSessionProperty</code> if exists. If not
1993: * returns the defaultChannelName attribute
1994: * using <code>getStringAtribute</code>
1995: * @return a <code>String</code>, name of the channel
1996: * @see #getSessionProperty(String)
1997: * @see #getStringAttribute(String)
1998: */
1999: public String getDefaultChannelName();
2000:
2001: /**
2002: * Get the named configuration property.
2003: *
2004: * @param key a <code>String</code>, the property name.
2005: * @return a <code>String</code>, the property value.
2006: */
2007: public String getConfigProperty(String key);
2008:
2009: /**
2010: * Get the display container name for the named channel.
2011: * A display container visually holds another channel.
2012: *
2013: * This method returns the parent container name in which
2014: * this channel is contained on the desktop page.
2015: * returns null if this channel is the parent container or if
2016: * this method is called outside <code>getContent()</code> in
2017: * <code>Provider</code> class.
2018: *
2019: * A channel only has a display container when it is being visually
2020: * displayed within a container channel. This method relies on
2021: * CPC.getContent() to set up the display container name.
2022: * Calling this method in a call stack that does not include CPC.getContent()
2023: * somewhere above the current stack frame will result in a return value of null.
2024: *
2025: * For an example of where it makes sense to use this method, consider this:
2026: * container A calls CPC.getContent() to gather content for the channels
2027: * that is visually contains. CPC.getContent() calls channel X's getContent() method.
2028: * Channel X may now call PC.getParentContainerName().
2029: *
2030: * For an exmaple of where it *does not* make sense to us this method, consider this:
2031: * channel X calls PC.getParentContainerName() from within it's getEdit() method.
2032: * When a channel is displaying it's edit page, it is not visually contained.
2033: * At this point, channel X has no display container as PC.getParentContainerName()
2034: * will return null.
2035: *
2036: * @param channel Channel name for which the parent is requested.
2037: * @return a <code>String</code>, name of the parent container
2038: * or null if parent is not known.
2039: *
2040: * @see ContainerProviderContext.getContent()
2041: */
2042: public String getParentContainerName(String channel);
2043:
2044: /**
2045: * Get the roles the user is in.
2046: *
2047: * This method returns the set of strings where
2048: * each string corresponds to the role the user is in.
2049: *
2050: * @return Set of roles the user is in.
2051: */
2052: public Set getRoles();
2053:
2054: /**
2055: * Get the top channel name.
2056: * This method returns the top channel for the
2057: * current request, identified by the request object argument.
2058: * The top channel is responsible for directly rendering the
2059: * portal page or by partially or wholly delegating
2060: * the rendering to one or more channels.
2061: *
2062: *
2063: * @param req HttpServletRequest
2064: *
2065: * @return a <code>String</code>, name of the channel
2066: */
2067: public String getTopChannelName(HttpServletRequest req);
2068:
2069: /**
2070: * URL encodes a unicode string
2071: *
2072: * This method is used for encoding multi-byte characters
2073: * to be passed as arguments in a URL.
2074: * This method converts the string to encode into a sequence of
2075: * bytes using the default charset <code>UTF-8()</code> and then the
2076: * sequence is converted to <code>urlencoded</code> format.
2077: *
2078: * All URL parameter values that are passed to the desktop
2079: * and that may be localized (non-ascii) must be url encoded using
2080: * this method and should be decoded using <code>decodeURLParameter</code>
2081: * when getting it back from the request.
2082: *
2083: * @param enc string to encode
2084: * @return a <code>String</code>, encoded string
2085: * @see #decodeURLParameter
2086: */
2087: public String encodeURLParameter(String enc);
2088:
2089: /**
2090: * Decodes the URL encoded
2091: * Unicode string
2092: *
2093: * This method is used for decoding
2094: * <code>urlencoded</code> multi-byte characters
2095: * that were passed as arguments in a URL
2096: *
2097: * @param dec string to decode
2098: * @return a <code>String</code>, decoded string
2099: *
2100: * @deprecated. This method just returns the argument back.
2101: * Desktop handles the decoding of the url parameters, hence
2102: * clients doesn't need to do decoding anymore.
2103: * @see #encodeURLParameter
2104: */
2105: public String decodeURLParameter(String dec);
2106:
2107: }
|