com.sun.portal.providers.context
Interface ProviderContext

All Known Subinterfaces:
ContainerProviderContext

public interface ProviderContext

An environment for provider execution. More formally, this class provides information pertaining to the container that a provider object executes within. Such information may be specific to the user, to the web container, or be global (shared between multiple users). This interface does not define what information falls into each of these categories; this is left up to the implementation. For example, it is up to the implementation whether a user's locale (see getLocaleString() and getLocale()) is specific to the user or is a global for all users.

At runtime, a single provider context object is shared between all channels in the system. Methods in this interface that target a specific channel require the channel name to be passed in as a parameter to the method (see get*Property()).

Any container channel that wishes to make a provider context available to its contained leaf channels must do so using an agreed-upon contract between the container and the leaf channels. Any channels that extends ProviderAdapter falls into this category. See the ProviderAdapter Javadocs for details.

A provider context forms the layer between the services used by the provider and the provider code. A provider context isolates provider code from specific service interfaces and implementations.

All methods in this interface may throw errors. Errors are thrown when a serious problem arises such that a reasonable application either should not try, or there is no clear way to resolve. The actual object thrown will be a subclass of Error. This error may be caught, if it can be handled reasonably in the application. Applications that wish to try and resolve such errors may catch Error. The get*Property() and set*Property() methods deserve special mention. It is considered a serious error when an application attempts to get or set a property that does not exist. Again, an error is thrown from these methods if the property does not exist. The set of properties that an application uses is a contract between the persistent store providing the properties and the application. To avoid application errors, the exists*Property() methods can be used to check for the existence of a property. Additionally, the get*Property() method versions that accept a default value may be used.

There is a 1-1 mapping between a session and a ProviderContext object. Typically, there is a unique session for every client accessing the Desktop. However, there are exceptions to this. When accessed in authless mode, multiple clients access the same ProviderContext object and therefore the same session. A subset of methods in this interface access session functionality. These include getSessionProperty(), setSessionProperty(), getSessionID(), and getUserID(). The getSessionProperty() and setSessionProperty() methods get and set properties per session, or per ProviderContext object. A session property is shared between all clients using the session. In the case of authless, a session property is shared for all authless clients. In some cases it is desirable to set properties such that there is a 1-1 mapping between client and property. An example of this is a selected tab name. In the case of authless, it would not do to have the selected tab name shared between all authless clients because this would cause all authless clients to have the same selected tab. To set / get properties per accessing client, use the setClientProperty() and getClientProperty() methods.

ProviderContext is a generic interface, the documentation here describes it in this light. There are implementation classes as well. To make use of this interface, it is necessary to expose aspects of the implementation. While the implementation classes are private, their semantics are documented. Please see the iPS product documentation for details.

See Also:
ProviderAdapter, ContainerProviderContext

Method Summary
 void allContentChanged()
          Flags content for all channels as changed.
 void contentChanged(java.lang.String channelName)
          Flags channel content as changed.
 void debugError(java.lang.Object o)
          Logs a message if the debugging level is "error".
 void debugError(java.lang.Object o, java.lang.Throwable t)
          Logs a message and stack trace, if the debugging level is "error".
 void debugMessage(java.lang.Object o)
          logs a message if the debugging level is "message" or higher.
 void debugMessage(java.lang.Object o, java.lang.Throwable t)
          Logs a message and stack trace if the debugging level is "message" or higher.
 void debugWarning(java.lang.Object o)
          Logs a message if the debugging level is "warning" or higher.
 void debugWarning(java.lang.Object o, java.lang.Throwable t)
          Logs a message and stack trace if the debugging level is "warning" or higher.
 java.lang.String decodeURLParameter(java.lang.String dec)
          Decodes the URL encoded Unicode string This method is used for decoding urlencoded multi-byte characters that were passed as arguments in a URL
 java.lang.String encodeURL(java.lang.String url)
          Encodes a URL.
 java.lang.String encodeURLParameter(java.lang.String enc)
          URL encodes a unicode string This method is used for encoding multi-byte characters to be passed as arguments in a URL.
 java.lang.String escape(java.lang.String unescaped)
          Escapes a String This method escapes the string using an encoder class that encodes a specific type of markup.
 boolean existsBooleanProperty(java.lang.String channel, java.lang.String name)
          Test for the existence of a boolean property.
 boolean existsBooleanProperty(java.lang.String channel, java.lang.String name, java.util.List pflist)
          Test for the existence of the filtered boolean property.
 boolean existsCollectionProperty(java.lang.String channel, java.lang.String name)
          Test for the existence of a collection property.
 boolean existsCollectionProperty(java.lang.String channel, java.lang.String name, boolean localized)
          Test for the existence of a collection property.
 boolean existsCollectionProperty(java.lang.String channel, java.lang.String name, java.util.List pflist)
          Test for the existence of the filtered collection property.
 boolean existsIntegerProperty(java.lang.String channel, java.lang.String name)
          Test for the existence of an integer property.
 boolean existsIntegerProperty(java.lang.String channel, java.lang.String name, java.util.List pflist)
          Test for the existence of the filtered integer property.
 boolean existsStringProperty(java.lang.String channel, java.lang.String name)
          Test for the existence of a string property.
 boolean existsStringProperty(java.lang.String channel, java.lang.String name, boolean localized)
          Test for the existence of a string property.
 boolean existsStringProperty(java.lang.String channel, java.lang.String name, java.util.List pflist)
          Test for the existence of a filtered string property.
 java.lang.String getAuthenticationType()
          Get the authentication type.
 boolean getBooleanProperty(java.lang.String channel, java.lang.String name)
          Get a boolean property property.
 boolean getBooleanProperty(java.lang.String channel, java.lang.String name, boolean def)
          Get a boolean property property.
 boolean getBooleanProperty(java.lang.String channel, java.lang.String name, boolean def, java.util.List pflist)
          Get the filtered boolean property property.
 boolean getBooleanProperty(java.lang.String channel, java.lang.String name, java.util.List pflist)
          Get the filtered boolean property property.
 java.lang.String getCharset()
          Get the character set.
 java.lang.String getClassName(java.lang.String channel)
          Get the class name for the provider class that this object will be providing an environment for.
 java.util.List getClientAndLocalePropertiesFilters()
          Get the client and locale in the form of PropertiesFilter's.
 java.lang.String getClientPath()
          Get the client path.
 java.util.List getClientPropertiesFilters()
          Get the client PropertiesFilter's.
 java.util.List getClientPropertiesFilters(java.lang.String clientType)
          Get the client PropertiesFilter's for a given clientType.
 java.lang.String getClientProperty(java.lang.String name)
          Get a client property.
 java.lang.String getClientType()
          Get the client type.
 java.util.Set getClientTypeProperties(java.lang.String clientType, java.lang.String key)
          Get a set of client type properties for the given client type.
 java.lang.String getClientTypeProperty(java.lang.String key)
          Get a client type property for the user's client type.
 java.lang.String getClientTypeProperty(java.lang.String clientType, java.lang.String key)
          Get a client type property for the given client type.
 java.util.Map getCollectionProperty(java.lang.String channel, java.lang.String name)
          Get a collection property.
 java.util.Map getCollectionProperty(java.lang.String channel, java.lang.String name, boolean localized)
          Get the localized version of a collection property.
 java.util.Map getCollectionProperty(java.lang.String channel, java.lang.String name, java.util.List pflist)
          Get the filtered Collection property.
 java.util.Map getCollectionProperty(java.lang.String channel, java.lang.String name, java.util.Map def)
          Get a collection property.
 java.util.Map getCollectionProperty(java.lang.String channel, java.lang.String name, java.util.Map def, boolean localized)
          Get the localized version of a collection property.
 java.util.Map getCollectionProperty(java.lang.String channel, java.lang.String name, java.util.Map def, java.util.List pflist)
          Get the filtered Collection property.
 java.lang.String getConfigProperty(java.lang.String key)
          Get the named configuration property.
 java.lang.String getContentType()
          Get the content type.
 java.lang.String getDefaultChannelName()
          Get the default channel name.
 java.lang.String getDefaultClientType()
          Get the default client type.
 java.lang.String getDesktopType()
          Get the Desktop type.
 java.lang.String getDesktopURL(javax.servlet.http.HttpServletRequest req)
          Get the Desktop URL.
 java.lang.String getDesktopURL(javax.servlet.http.HttpServletRequest req, java.util.Map query, java.util.Map pathInfo)
          Get the Desktop URL.
 java.lang.String getDesktopURL(javax.servlet.http.HttpServletRequest req, java.util.Map query, java.util.Map pathInfo, boolean escape)
          Get the Desktop URL.
 java.lang.String getDesktopURL(javax.servlet.http.HttpServletRequest req, java.lang.String query, boolean escape)
          Get the Desktop URL.
 int getIntegerProperty(java.lang.String channel, java.lang.String name)
          Get an integer property.
 int getIntegerProperty(java.lang.String channel, java.lang.String name, int def)
          Get an integer property.
 int getIntegerProperty(java.lang.String channel, java.lang.String name, int def, java.util.List pflist)
          Get an integer property.
 int getIntegerProperty(java.lang.String channel, java.lang.String name, java.util.List pflist)
          Get the filtered integer property.
 java.util.Locale getLocale()
          Get the locale.
 java.util.List getLocalePropertiesFilters()
          Get the locale in the form of PropertiesFilter's.
 java.lang.String getLocaleString()
          Get the string form of the locale.
 java.lang.String getLoginURL()
          Get the login URL.
 java.lang.String getLogoutURL()
          Get the logout URL.
 java.util.Iterator getNames(java.lang.String channel)
          Get property names for the channel.
 java.lang.String getParentContainerName(java.lang.String channel)
          Get the display container name for the named channel.
 java.lang.Object getProperty(java.lang.String channel, java.lang.String name)
          Get a property.
 java.lang.Object getProperty(java.lang.String channel, java.lang.String name, java.lang.Object def)
          Get a property.
 java.lang.String getProviderName(java.lang.String channel)
          Get the name of the provider that backs the channel that this object provides an environment for.
 int getProviderVersion(java.lang.String channel)
          Get the version of the provider schema for the named channel.
 java.lang.StringBuffer getRequestServer(javax.servlet.http.HttpServletRequest req)
          Get the request server.
 java.util.Set getRoles()
          Get the roles the user is in.
 javax.servlet.ServletConfig getServletConfig()
          Deprecated. A specific front end servlet cannot be assumed. Therefore, programmers should not access a ServletConfig object since it may make their Providers non-portable to other environments. Use getServletContext() instead.
 javax.servlet.ServletContext getServletContext()
          Get the Servlet Context.
 java.lang.String getSessionID()
          Get the unique session identifier.
 java.lang.Object getSessionProperty(java.lang.String name)
          Get a session property.
 java.lang.String getStaticContentPath()
          Get the URI prefix to web server static content.
 java.lang.String getStringAttribute(java.lang.String name)
          Get a string attribute.
 java.lang.String getStringProperty(java.lang.String channel, java.lang.String name)
          Get a String property.
 java.lang.String getStringProperty(java.lang.String channel, java.lang.String name, boolean localized)
          Get the localized version of a String property.
 java.lang.String getStringProperty(java.lang.String channel, java.lang.String name, java.util.List pflist)
          Get the filtered String property.
 java.lang.String getStringProperty(java.lang.String channel, java.lang.String name, java.lang.String def)
          Get a String property.
 java.lang.String getStringProperty(java.lang.String channel, java.lang.String name, java.lang.String def, boolean localized)
          Get the localized version of a String property.
 java.lang.String getStringProperty(java.lang.String channel, java.lang.String name, java.lang.String def, java.util.List pflist)
          Get the filtered String property.
 java.lang.StringBuffer getTemplate(java.lang.String name, java.lang.String file)
          Get a desktop template.
 java.lang.StringBuffer getTemplate(java.lang.String name, java.lang.String file, java.util.Hashtable table)
          Get and tag swaps a desktop template.
 java.lang.StringBuffer getTemplate(java.lang.String desktopType, java.lang.String locale, java.lang.String name, java.lang.String clientType, java.lang.String file, java.util.Hashtable table, java.lang.String baseDir)
          Get and tag swaps a desktop template.
 java.lang.StringBuffer getTemplate(java.lang.String desktopType, java.lang.String locale, java.lang.String name, java.lang.String clientType, java.lang.String file, java.lang.String baseDir)
          Get a desktop template.
 java.io.File getTemplateMostSpecificPath(java.lang.String name, java.lang.String file)
          Get the most specific template path for the given channel name and the given template name.
 java.io.File getTemplateMostSpecificPath(java.lang.String desktopType, java.lang.String locale, java.lang.String name, java.lang.String clientType, java.lang.String file, java.lang.String baseDir)
          Get the most specific template path for the given channel name and the given template name.
 java.io.File getTemplatePath(java.lang.String name, java.lang.String file)
          Get the template path for the given channel name and the given template name.
 java.io.File getTemplatePath(java.lang.String desktopType, java.lang.String locale, java.lang.String name, java.lang.String clientType, java.lang.String file, java.lang.String baseDir)
          Get the template path for the given channel name and the given template name.
 java.lang.String getTopChannelName(javax.servlet.http.HttpServletRequest req)
          Get the top channel name.
 java.lang.String getUserID()
          Get the user identifier.
 void init(javax.servlet.http.HttpServletRequest req)
          Initialize this provider context.
 boolean isAuthless(javax.servlet.http.HttpServletRequest req)
          Get if the current Desktop session is non-authenticated (authless).
 boolean isDebugEnabled()
          Get if the debug is enabled
 boolean isDebugErrorEnabled()
          Get if the debug is set to error
 boolean isDebugMessageEnabled()
          Get if the debug level is set to message or higher.
 boolean isDebugWarningEnabled()
          Get if the debug level is set to warning or higher.
 void refresh()
          Causes Provider Context to throw away any cached data.
 void setBooleanProperty(java.lang.String channel, java.lang.String name, boolean value)
          Sets a boolean property.
 void setBooleanProperty(java.lang.String channel, java.lang.String name, boolean value, java.util.List pflist)
          Sets a boolean property according to the given filter criteria.
 void setClientProperty(java.lang.String name, java.lang.String value)
          Set a client property.
 void setCollectionProperty(java.lang.String channel, java.lang.String name, java.util.List value)
          Sets a collection property.
 void setCollectionProperty(java.lang.String channel, java.lang.String key, java.util.List val, java.util.List pflist)
          Sets a collection property according to the given filter criteria.
 void setCollectionProperty(java.lang.String channel, java.lang.String key, java.util.Map val)
          Sets a collection property.
 void setCollectionProperty(java.lang.String channel, java.lang.String key, java.util.Map val, java.util.List pflist)
          Sets a collection property according to the given filter criteria.
 void setIntegerProperty(java.lang.String channel, java.lang.String name, int value)
          Sets an integer property.
 void setIntegerProperty(java.lang.String channel, java.lang.String name, int value, java.util.List pflist)
          Sets an integer property according to the given filter criteria.
 void setProperty(java.lang.String channel, java.lang.String key, java.lang.Object val)
          TBD
 void setSessionProperty(java.lang.String name, java.lang.Object val)
          Set a session property.
 void setStringAttribute(java.lang.String name, java.lang.String val)
          Sets a string attribute.
 void setStringProperty(java.lang.String channel, java.lang.String key, java.lang.String val)
          Sets a string property.
 void setStringProperty(java.lang.String channel, java.lang.String key, java.lang.String val, java.util.List pflist)
          Sets a string property according to the given filter criteria.
 

Method Detail

init

public void init(javax.servlet.http.HttpServletRequest req)
Initialize this provider context. The request object must contain the service specific data to allow the underlying implementation to be initialized. This data might be cookies, HTTP headers, etc. The details of how the request object is used is specific to the implementation of this interface.

Parameters:
req - Request object containing service specific data.

refresh

public void refresh()
Causes Provider Context to throw away any cached data. This method informs the Provider Context that the system has changed state in a such a way that cached data (if any) should be considered stale.
This method should be used with caution because of the obvious performance implications. If a Provider Context caches data, it is most likely doing so as a performance optimization. Calling this method causes such optimizations to be negated, until the Provider Context can re-cache the data.
For an exaple of when it makes sense to call this method, consider the following: the Provider Context implementation is driven by a single large chunk of data that is read from an LDAP server. The raw data is passed to the Provider Context by the Desktop. To be useful, the Provider Context must parse the raw data into an internal representation. Parsing the raw data is expensive, so the Provider Context caches the internal representation and does not re-generate it every request. However, the Provider Context must throw away the internal representation if the raw data changes. The Desktop notifies the Provider Context when the raw data changes by calling refresh. This informs the Provider Context that is must throw away the internal representation and re-generate.


contentChanged

public void contentChanged(java.lang.String channelName)
Flags channel content as changed. Clients should use this method to inform the Provider Context that the content for a channel has been updated and any cached content for the channel should be considered stale.
This method should be used with caution because of the obvious performance implications. Content caching is done for channels as an optimization to prevent potentially expensive calls to get content. This method forces fresh content to be fetched for the named channel upon the next request.
For an example of when it makes sense to use this method, consider the case where a channel's content is affected (only) when it's edit page is processed. For desktop reloads, the content for the channel can be cached indefinetly, because we know the only thing that can cause the content to be changed is processing of its edit page. When the edit page is processed, we call this method to cause any cached content for this channel to be discarded, so the content will be regenerated based on the processed edit page.


allContentChanged

public void allContentChanged()
Flags content for all channels as changed. Clients should use this method to inform the Provider Context that the content for all channels has been updated and any cached content for the channels should be considered stale.
This method should be used with caution because of the obvious performance implications. Content caching is done for channels as an optimization to prevent potentially expensive calls to get content. This method forces fresh content to be fetched from all channels.
For an example of when it makes sense to use this method, consider the case where the locale has changed. A new locale value means that any cached content is specific to the old locale value. Each channel must generate new content based on the new locale value.


getDesktopURL

public java.lang.String getDesktopURL(javax.servlet.http.HttpServletRequest req)
Get the Desktop URL. The Desktop URL is the absolute URL used to access the Desktop application. For example: http://SERVER:PORT/ps/desktop. The request object parameter is included to facilitate implementations. It may be used to build the Desktop URL by supplying the server, port, and protocol of the request. It is not required that the request object be utilizied to generate the Desktop URL.

Parameters:
req - Request object containing the protocol, server, port, etc. information required to build the Desktop URL. If the implementation does not use the request object, this parameter may be null.
Returns:
String representation of the URL.

getDesktopURL

public java.lang.String getDesktopURL(javax.servlet.http.HttpServletRequest req,
                                      java.util.Map query,
                                      java.util.Map pathInfo)
Get the Desktop URL. The Desktop URL is the absolute URL used to access the Desktop application. For example: http://SERVER:PORT/ps/desktop/pathinfo?query. The request object parameter is included to facilitate implementations. It may be used to build the Desktop URL by supplying the server, port, and protocol of the request. It is not required that the request object be utilizied to generate the Desktop URL. The pathInfo Map passed in as an argument will be encoded and appended as a pathInfo to the desktopURL. The key/value pairs in the pathInfo Map can be accessed by calling req.getParameter(). path info parameters are overriden by query string params, which are overriden by post parameters. query Map passed in as an argument will be appended as query string to the desktopURL. This method is equivalent to calling getDesktopURL() if pathInfo and query are null.

Parameters:
req - Request object containing the protocol, server, port, etc. information required to build the Desktop URL. If the implementation does not use the request object, this parameter may be null.
pathInfo - Map.
query - Map. queryString key/value pairs to be appended to URL.
Returns:
String representation of the URL.
See Also:
getDesktopURL(HttpServletRequest req)

getDesktopURL

public java.lang.String getDesktopURL(javax.servlet.http.HttpServletRequest req,
                                      java.util.Map query,
                                      java.util.Map pathInfo,
                                      boolean escape)
Get the Desktop URL. The Desktop URL is the absolute URL used to access the Desktop application. For example: http://SERVER:PORT/ps/desktop/pathinfo?query. This method internally calls escape to escape the desktop url using a client specific encoder if escape flag is true. This method is equivalent to calling getDesktopURL(req, query, pathInfo) if escape flag is false.

Parameters:
req - Request object containing the protocol, server, port, etc. information required to build the Desktop URL. If the implementation does not use the request object, this parameter may be null.
pathInfo - Map.
query - Map. queryString key/value pairs to be appended to URL.
escape - Boolean. flag specifying whether to escape the url string specific to the client using a client specific encoder.
Returns:
String representation of the URL.
See Also:
getDesktopURL(HttpServletRequest req, Map query, Map pathInfo), escape(String unescaped)

getDesktopURL

public java.lang.String getDesktopURL(javax.servlet.http.HttpServletRequest req,
                                      java.lang.String query,
                                      boolean escape)
Get the Desktop URL. The Desktop URL is the absolute URL used to access the Desktop application. For example: http://SERVER:PORT/ps/desktop?queryString. query String passed in as an argument will be appended as query string to the desktopURL. This method is equivalent to calling getDesktopURL() if query is null and escape flag false.

Parameters:
req - Request object containing the protocol, server, port, etc. information required to build the Desktop URL. If the implementation does not use the request object, this parameter may be null.
query - String. queryString to be appended to URL.
escape - Boolean. flag specifying whether to escape the url string specific to the client using a client specific encoder.
Returns:
String representation of the URL.
See Also:
getDesktopURL(HttpServletRequest req), escape(String unescaped)

getLocaleString

public java.lang.String getLocaleString()
Get the string form of the locale. The various locale suffixes are combined together using the underscore character ("_") as:
LANG_COUNTRY_VARIANT

If a particular suffix is not present, then it is ommited from the string. An example for a language setting of "en", and country setting of "US" is "en_US".

Returns:
String representation of the locale.

getLocale

public java.util.Locale getLocale()
Get the locale.

Returns:
Java Locale object representation of the locale.
See Also:
Locale

getDesktopType

public java.lang.String getDesktopType()
Get the Desktop type. The Desktop type, or also known as template type, is a string that is one of several indexes used to lookup Desktop templates and JSP files. The Desktop type is typically used to group such Desktop customization files to provide different themes.

Returns:
Desktop type as a string.

getLogoutURL

public java.lang.String getLogoutURL()
Get the logout URL. The result of making a connection to the logout URL is typcically the termination of the user's session. What actually happens is dependent on the application receiving the URL connection.

Providers may use this value to generate links that allow the user to end their session.

Returns:
Logout URL as a string.

getLoginURL

public java.lang.String getLoginURL()
Get the login URL. Providers may use this value to generate links to the login url. The URL returned from this method is encoded.

Returns:
Login URL as a string.

getStringAttribute

public java.lang.String getStringAttribute(java.lang.String name)
Get a string attribute. "Attributes" are settings that are not channel-specific. An example of an attribute might be the user's first and last name. Channel-specific settings are called "properties". Properties can be retrieved by calling the get*Property() methods. Whether a particular value is considered a property or an attribute depends on the underlying implementation of ProviderContext.

Parameters:
name - Attribute name.
Returns:
Attribute value as a string. If attribute is not not found, null is returned.

setStringAttribute

public void setStringAttribute(java.lang.String name,
                               java.lang.String val)
Sets a string attribute. "Attributes" are settings that are not channel-specific. An example of an attribute might be the user's first and last name. Channel-specific settings are called "properties". Properties can be set by calling the set*Property() methods. Whether a particular value is considered a property or an attribute depends on the underlying implementation of ProviderContext.

Parameters:
name - Attribute name.

encodeURL

public java.lang.String encodeURL(java.lang.String url)
Encodes a URL. Rewrite the URL to include the session id.

Parameters:
url - The URL to be encoded.

getRequestServer

public java.lang.StringBuffer getRequestServer(javax.servlet.http.HttpServletRequest req)
Get the request server. This is a replacement for HttpUtils.getRequestURL() because the version of that method does not use the Host HTTP header field to reconstruct the URL. The difference in this version is that it grabs the servername:port from the Host header if it is there.

Parameters:
req - HTTP request object to grab the server information from.
Returns:
Buffer containing the request server.
See Also:
HttpUtils.getRequestURL(HttpServletRequest)

getClientTypeProperty

public java.lang.String getClientTypeProperty(java.lang.String key)
Get a client type property for the user's client type.

Parameters:
key - Property key.
Returns:
Property value.
See Also:
getClientType()

getClientTypeProperty

public java.lang.String getClientTypeProperty(java.lang.String clientType,
                                              java.lang.String key)
Get a client type property for the given client type.

Parameters:
clientType - Client type to get the property from.
key - Property key.
Returns:
Property value.

getClientTypeProperties

public java.util.Set getClientTypeProperties(java.lang.String clientType,
                                             java.lang.String key)
Get a set of client type properties for the given client type.

Parameters:
clientType - Client type to get the property keys from.
key - Property key.
Returns:
Set of property values.

getDefaultClientType

public java.lang.String getDefaultClientType()
Get the default client type.

Returns:
Default client type.

getClientType

public java.lang.String getClientType()
Get the client type. There is no requirement as to how the client type is determined. It may be hardcoded, derived from the session, or otherwise.

Returns:
Client type.

getCharset

public java.lang.String getCharset()
Get the character set. The character set is used for decoding input and encoding output.

Returns:
Character set.

getClientPath

public java.lang.String getClientPath()
Get the client path. The client path is one of several components used to lookup Desktop templates and JSPs. This allows the lookup to be client-specific.

Returns:
Client path.

getContentType

public java.lang.String getContentType()
Get the content type. This value is used to determine if a provider is able to produce content for the client's device.

Returns:
a String value

escape

public java.lang.String escape(java.lang.String unescaped)
                        throws ProviderContextException
Escapes a String This method escapes the string using an encoder class that encodes a specific type of markup. This method is used to allow provider code to encode content in a device-unaware manner.

The following is an example usage of this method, and illustrates how to encode content in a device-unaware fashion:

String unencoded = "";
String encoded = escape(unencoded);


The encoder class name used by this method is read from a client type property keyed "encoderClassName". If this property does not exist, EncoderClassNames.ENCODER_DEFAULT is assumed.

Returns:
String. escaped String
Throws:
ProviderContextException

getSessionProperty

public java.lang.Object getSessionProperty(java.lang.String name)
Get a session property. There is a 1-1 mapping between a session and a ProviderContext object. Session properties are therefore specific to a and instance of a ProviderContext object. Session properties are made available for garbage collection when the session ends.

Parameters:
name - Property name.
Returns:
Property value. If the property is not not found, then null is returned.

setSessionProperty

public void setSessionProperty(java.lang.String name,
                               java.lang.Object val)
Set a session property. There is a 1-1 mapping between a session and a ProviderContext object. Session properties are therefore specific to a and instance of a ProviderContext object. Session properties are made available for garbage collection when the session ends.

Parameters:
name - The property name.

getSessionID

public java.lang.String getSessionID()
Get the unique session identifier. The format of the return value is implementation specific. The only guarantee is that it is unique (each user session has a unique session ID).

Returns:
Session ID.

isAuthless

public boolean isAuthless(javax.servlet.http.HttpServletRequest req)
Get if the current Desktop session is non-authenticated (authless). Authless Desktop sessions are created by the Desktop and are not subject to the normal authentication process that is required for authenticated Desktop sessions. When writing providers to be used in the context of an authless Desktop, it is important to keep several factors in mind. It is typical that many clients will be accessing a single authless Desktop session. The implication is that changing properties for an authless channel affects all accessing clients. Normally, authless providers are configured to hold state in client properties instead of provider properties. Desktop session properties are per-Desktop session; any Desktop session properties that are set for an authless user are shared among all authless users. There can be many authless Desktop sessions; such sessions are associated with a particular user ID.

Parameters:
req - Request object .
Returns:
true if the current Desktop session is an authless session otherwise false.

getAuthenticationType

public java.lang.String getAuthenticationType()
Get the authentication type. The method returns a string denoting the authentication type that was used for the current session. No assumptions can be made about the format of the returned string.

Returns:
a String, the authentication type.

getUserID

public java.lang.String getUserID()
Get the user identifier. The format of the return value is implementation specific. There is no guarantee that this value is unique (there may be multiple user sessions for a given user identifier).

Returns:
User identifier.

getClientProperty

public java.lang.String getClientProperty(java.lang.String name)
Get a client property. Client properties are specific to the particular client accessing the portal, not to the ProviderContext object used to access them.
Client properties are only guaranteed to persist for the life of the request, although typically they will persist for the life of the session.

Parameters:
name - a String, the property name.
Returns:
a String, the property value.

setClientProperty

public void setClientProperty(java.lang.String name,
                              java.lang.String value)
Set a client property. Client properties are specific to the particular client accessing the portal, not to the ProviderContext object used to access them. In some cases, there is a 1-1 mapping between client device and ProviderContext object, however, client code cannot make this assumption.
Client properties are only guaranteed to persist for the life of the request, although typically they will persist for the life of the session.

Parameters:
name - a String, the property name.
value - String, the property value.

isDebugEnabled

public boolean isDebugEnabled()
Get if the debug is enabled

Returns:
true if the debugging is on, otherwise false.

isDebugErrorEnabled

public boolean isDebugErrorEnabled()
Get if the debug is set to error

Returns:
true if the debugging level is set to error, otherwise false.

isDebugWarningEnabled

public boolean isDebugWarningEnabled()
Get if the debug level is set to warning or higher.

Returns:
true if the debugging level is set to warning or higher, otherwise false.

isDebugMessageEnabled

public boolean isDebugMessageEnabled()
Get if the debug level is set to message or higher.

Returns:
true if the debugging level is set to message or higher, otherwise false.

debugMessage

public void debugMessage(java.lang.Object o)
logs a message if the debugging level is "message" or higher. The location to store debugging messages is implementation dependent.

Parameters:
o - Object to debug (o.toString() is logged).

debugWarning

public void debugWarning(java.lang.Object o)
Logs a message if the debugging level is "warning" or higher. The location to store debugging messages is implementation dependent.

Parameters:
o - Object to debug (o.toString() is logged).

debugError

public void debugError(java.lang.Object o)
Logs a message if the debugging level is "error". The location to store debugging messages is implementation dependent.

Parameters:
o - Object to debug (o.toString() is logged).

debugMessage

public void debugMessage(java.lang.Object o,
                         java.lang.Throwable t)
Logs a message and stack trace if the debugging level is "message" or higher. The location to store debugging messages is implementation dependent.

Parameters:
o - Object to debug (o.toString() is logged).
t - Throwable object to log a stack trace of.

debugWarning

public void debugWarning(java.lang.Object o,
                         java.lang.Throwable t)
Logs a message and stack trace if the debugging level is "warning" or higher. The location to store debugging messages is implementation dependent.

Parameters:
o - Object to debug (o.toString() is logged).
t - Throwable object to log a stack trace of.

debugError

public void debugError(java.lang.Object o,
                       java.lang.Throwable t)
Logs a message and stack trace, if the debugging level is "error". The location to store debugging messages is implementation dependent.

Parameters:
o - Object to debug (o.toString() is logged).
t - Throwable object to print a stack trace of.

getTemplate

public java.lang.StringBuffer getTemplate(java.lang.String name,
                                          java.lang.String file)
                                   throws ProviderContextException
Get a desktop template. The actual template buffer returned is based on the Desktop type, locale, channel, client type, and the template name.

Parameters:
name - Channel name
file - Template name to return.
Returns:
Buffer containng the template.
Throws:
ProviderContextException - if an error occurs in getting the desktop template.

getTemplate

public java.lang.StringBuffer getTemplate(java.lang.String desktopType,
                                          java.lang.String locale,
                                          java.lang.String name,
                                          java.lang.String clientType,
                                          java.lang.String file,
                                          java.lang.String baseDir)
                                   throws ProviderContextException
Get a desktop template. The actual template buffer returned is based on the Desktop type, locale, channel, client type, and the template name.

Parameters:
desktopType - Desktop type.
locale - Locale.
name - Channel name.
file - Template name to return.
baseDir - the base directory from which the lookup mechanism begins its lookup.
Returns:
Buffer containng the template.
Throws:
ProviderContextException - if an error occurs in getting the desktop template.

getTemplate

public java.lang.StringBuffer getTemplate(java.lang.String name,
                                          java.lang.String file,
                                          java.util.Hashtable table)
                                   throws ProviderContextException
Get and tag swaps a desktop template. The actual template buffer returned is based on the the name, locale, client path, and Desktop type.

Parameters:
name - Channel name
file - Template name to return
table - Tag table to use for tag swapping.
Returns:
Buffer containng the template.
Throws:
ProviderContextException - if an error occurs in getting or tag swapping the desktop template.

getTemplate

public java.lang.StringBuffer getTemplate(java.lang.String desktopType,
                                          java.lang.String locale,
                                          java.lang.String name,
                                          java.lang.String clientType,
                                          java.lang.String file,
                                          java.util.Hashtable table,
                                          java.lang.String baseDir)
                                   throws ProviderContextException
Get and tag swaps a desktop template. The actual template buffer returned is based on the the name, locale, client path, and Desktop type.

Parameters:
desktopType - Desktop type.
locale - Locale.
name - Channel name.
file - Template name to return.
table - Tag table to use for tag swapping.
baseDir - the base directory from which the lookup mechanism begins its lookup.
Returns:
Buffer containng the template.
Throws:
ProviderContextException - if an error occurs in getting or tag swapping the desktop template.

getTemplatePath

public java.io.File getTemplatePath(java.lang.String name,
                                    java.lang.String file)
                             throws ProviderContextException
Get the template path for the given channel name and the given template name. If non-null, the key returned by this method will map to a valid template file. The format of the returned path is implementation dependent.

Parameters:
name - Channel name.
file - The template name, or null if the template for the name does not exist.
Returns:
Path key to access the template.
Throws:
ProviderContextException - if an error occurs in getting the template path.

getTemplatePath

public java.io.File getTemplatePath(java.lang.String desktopType,
                                    java.lang.String locale,
                                    java.lang.String name,
                                    java.lang.String clientType,
                                    java.lang.String file,
                                    java.lang.String baseDir)
                             throws ProviderContextException
Get the template path for the given channel name and the given template name. If non-null, the key returned by this method will map to a valid template file. The format of the returned path is implementation dependent.

Parameters:
desktopType - Desktop type.
locale - Locale.
name - Channel name.
file - The template name.
baseDir - the base directory from which the lookup mechanism begins its lookup.
Returns:
Path key to access the template.
Throws:
ProviderContextException - if an error occurs in getting the template path.

getTemplateMostSpecificPath

public java.io.File getTemplateMostSpecificPath(java.lang.String name,
                                                java.lang.String file)
                                         throws ProviderContextException
Get the most specific template path for the given channel name and the given template name. The file returned may not exist at all. If non-null, the key returned by this method will map to the most specific template file. The file may or may not exist. The format of the returned path is implementation dependent.

Parameters:
name - Channel name.
file - The template name, or null if the template for the name does not exist.
Returns:
Path key to access the template.
Throws:
ProviderContextException - if an error occurs in getting the most specific template path.

getTemplateMostSpecificPath

public java.io.File getTemplateMostSpecificPath(java.lang.String desktopType,
                                                java.lang.String locale,
                                                java.lang.String name,
                                                java.lang.String clientType,
                                                java.lang.String file,
                                                java.lang.String baseDir)
                                         throws ProviderContextException
Get the most specific template path for the given channel name and the given template name. The file returned may not exist at all. If non-null, the key returned by this method will map to the most specific template file. The file may or may not exist. The format of the returned path is implementation dependent.

Parameters:
desktopType - Desktop type.
locale - Locale.
name - Channel name.
file - The template name.
baseDir - the base directory from which the lookup mechanism begins its lookup.
Returns:
Path key to access the template.
Throws:
ProviderContextException - if an error occurs in getting the most specific template path.

getClassName

public java.lang.String getClassName(java.lang.String channel)
                              throws ProviderContextException
Get the class name for the provider class that this object will be providing an environment for. This class name returned must implement the provider interface. This method is used to construct the provider object. It is used by container channels.

Parameters:
channel - Channel name.
Returns:
String fully qualified class name (com.sun.portal.providers.foo.FooProvider).
Throws:
ProviderContextException - if an error occurs in getting the class name.

getProviderName

public java.lang.String getProviderName(java.lang.String channel)
                                 throws ProviderContextException
Get the name of the provider that backs the channel that this object provides an environment for. The format of the provider name is implementation dependent. The provider name is not necessarily equal to the provider class name (see getProviderClassName()).

Parameters:
channel - Channel name.
Returns:
Provider name.
Throws:
ProviderContextException - if an error occurs in getting the provider name.

getProviderVersion

public int getProviderVersion(java.lang.String channel)
                       throws ProviderContextException
Get the version of the provider schema for the named channel. The provider schema defines what properties are available to a provider. Depending on the schema version number, the provider can assume the existence of and appropriate defaults for particular channel properties. The exact set of properties that a particular schema version maps to is documented in the product manuals, for each provider. Additionally, the exists*Property() methods may be used to determine the presence or absence of specific properties. The return value from this method does not indicate the version of the provider class being used for the channel.

Returns:
Provider version.
Throws:
ProviderContextException
See Also:
existsStringProperty(String, String), existsStringProperty(String, String, List), existsStringProperty(String, String, boolean), existsBooleanProperty(String, String), existsBooleanProperty(String, String, List), existsIntegerProperty(String, String), existsIntegerProperty(String, String, List), existsCollectionProperty(String, String), existsCollectionProperty(String, String, List), existsCollectionProperty(String, String, boolean)

getNames

public java.util.Iterator getNames(java.lang.String channel)
                            throws ProviderContextException
Get property names for the channel.

Parameters:
channel - Channel name.
Returns:
Iterator over String objects.
Throws:
ProviderContextException - if an error occurs in getting the property names.

getProperty

public java.lang.Object getProperty(java.lang.String channel,
                                    java.lang.String name)
                             throws ProviderContextException
Get a property. The value retured from this method is a Java Object, of type String, Integer, Boolean, or Map.

Parameters:
channel - Channel name.
name - Property name.
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the property.

setProperty

public void setProperty(java.lang.String channel,
                        java.lang.String key,
                        java.lang.Object val)
                 throws ProviderContextException
TBD

Throws:
ProviderContextException

getProperty

public java.lang.Object getProperty(java.lang.String channel,
                                    java.lang.String name,
                                    java.lang.Object def)
                             throws ProviderContextException
Get a property. The value retured from this method is a Java Object, of type String, Integer, Boolean, or Map. If the property does not exist, then the default value is returned.

Parameters:
channel - Channel name.
name - Property name.
def - Default value.
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in setting the property.

getStringProperty

public java.lang.String getStringProperty(java.lang.String channel,
                                          java.lang.String name)
                                   throws ProviderContextException
Get a String property.

Parameters:
channel - Channel name.
name - Property name.
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the String property.

getStringProperty

public java.lang.String getStringProperty(java.lang.String channel,
                                          java.lang.String name,
                                          java.util.List pflist)
                                   throws ProviderContextException
Get the filtered String property. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If there is no property that exactly matches the filter criteria, the best partial match is returned. When there is not even a partial match, an unfiltered property is returned.

Parameters:
channel - Channel name.
name - Property name.
pflist - An ordered list of PropertiesFilter objects
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the the filtered String property.
See Also:
PropertiesFilter

getStringProperty

public java.lang.String getStringProperty(java.lang.String channel,
                                          java.lang.String name,
                                          java.lang.String def)
                                   throws ProviderContextException
Get a String property. This method returns a default value if the property does not exist.

Parameters:
channel - Channel name.
name - Property name.
def - Default value.
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the String property.

getStringProperty

public java.lang.String getStringProperty(java.lang.String channel,
                                          java.lang.String name,
                                          java.lang.String def,
                                          java.util.List pflist)
                                   throws ProviderContextException
Get the filtered String property. This method returns a default value if the property does not exist. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If there is no property that exactly matches the filter criteria, the best partial match is returned. When there is not even a partial match, an unfiltered property is returned.

Parameters:
channel - Channel name.
name - Property name.
def - Default value.
pflist - An ordered list of PropertiesFilter objects
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the the filtered String property.
See Also:
PropertiesFilter

getStringProperty

public java.lang.String getStringProperty(java.lang.String channel,
                                          java.lang.String name,
                                          boolean localized)
                                   throws ProviderContextException
Get the localized version of a String property. Locales are searched from more to less specific. For example, for a locale setting of "en_US_WE", the search order would be: en_US_WE, en_US, en. If the locale-specific property is not found, then the non-locale-specific version is returned (if it exists).

Parameters:
channel - Channel name.
name - Property name.
localized - Search for a localized version?
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the localized version of the String property.

getStringProperty

public java.lang.String getStringProperty(java.lang.String channel,
                                          java.lang.String name,
                                          java.lang.String def,
                                          boolean localized)
                                   throws ProviderContextException
Get the localized version of a String property. This method returns a default value if the property does not exist. Locales are searched from more to less specific. For example, for a locale setting of "en_US_WE", the search order would be: en_US_WE, en_US, en. If the locale-specific property is not found, then the non-locale-specific version is returned (if it exists).

Parameters:
channel - Channel name.
name - Property name.
def - Default value.
localized - Search for a localized version?
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the localized version of the String property.

setStringProperty

public void setStringProperty(java.lang.String channel,
                              java.lang.String key,
                              java.lang.String val)
                       throws ProviderContextException
Sets a string property.

Parameters:
channel - Channel name.
Throws:
ProviderContextException - if an error occurs in setting the String property.

setStringProperty

public void setStringProperty(java.lang.String channel,
                              java.lang.String key,
                              java.lang.String val,
                              java.util.List pflist)
                       throws ProviderContextException
Sets a string property according to the given filter criteria. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If the property that matches the filter criteria does not exist, the most specific, existing property gets set. If only the default value existed, it sets the default value. If the default and filtered properties existed, it sets the most specific existing filtered property. Note that the "exact" flag in the PropertiesFilters has no meaning and will be ignored.

Parameters:
channel - Channel name.
pflist - An ordered list of PropertiesFilter objects
Throws:
ProviderContextException - if an error occurs in setting the String property.
See Also:
PropertiesFilter

getCollectionProperty

public java.util.Map getCollectionProperty(java.lang.String channel,
                                           java.lang.String name)
                                    throws ProviderContextException
Get a collection property. Here, a collection is used to refer to a multi-value property. Depending on the context, it is either the analogue of Java Maps or List. For List, the returned Java Map object contains key-value pairs where the key equals the value. For example, to treat the Map object as a List, do the following:

Set list = map.keySet();

The Java Map object returned from this method fronts the persistent store for the property. Changes to this object are immediately reflected in the persistent store. Because of this, it is not necessary to call setCollectionProperty() to persist changes made to a property returned from this method. However, if you are setting a new collection value, you must call setCollectionProperty(). For example, it is not necessary to call setCollectionProperty() in the following example:

Map m = pc.getCollectionProperty("foo");
m.put("a", "1");

This is because the Map m is returned from getCollectionProperty() and is therefore persistent. However, in the example below, you must call setCollectionProperty():

Map m = new HashMap();
m.put("a", "1");

Map m is not persistent because it was not returned from getCollectionProperty() method. The following line is required to persist the changes:

pc.setCollectionProperty("foo", m);

Parameters:
channel - Channel name.
name - Property name.
Returns:
Property value, a Java Map that maps Strings to Java objects, either String, Integer, Boolean, or Map.
Throws:
ProviderContextException - if an error occurs in getting the Collection property.
See Also:
setCollectionProperty(String, String, Map), setCollectionProperty(String, String, List)

getCollectionProperty

public java.util.Map getCollectionProperty(java.lang.String channel,
                                           java.lang.String name,
                                           java.util.Map def)
                                    throws ProviderContextException
Get a collection property. This method returns a default value if the property does not exist.

Parameters:
channel - Channel name.
name - Property name.
def - Default value.
Returns:
Property value, a Java Map that maps Strings to Java objects, either String, Integer, Boolean, or Map.
Throws:
ProviderContextException - if an error occurs in getting the Collection property.
See Also:
getCollectionProperty(String, String)

getCollectionProperty

public java.util.Map getCollectionProperty(java.lang.String channel,
                                           java.lang.String name,
                                           java.util.List pflist)
                                    throws ProviderContextException
Get the filtered Collection property. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If there is no property that exactly matches the filter criteria, a partial match is returned.

Parameters:
channel - Channel name.
name - Property name.
pflist - An ordered list of PropertiesFilter objects
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the the filtered String property.
See Also:
PropertiesFilter

getCollectionProperty

public java.util.Map getCollectionProperty(java.lang.String channel,
                                           java.lang.String name,
                                           java.util.Map def,
                                           java.util.List pflist)
                                    throws ProviderContextException
Get the filtered Collection property. This method returns a default value if the property does not exist. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If there is no property that exactly matches the filter criteria, a partial match is returned.

Parameters:
channel - Channel name.
name - Property name.
def - Default value.
pflist - An ordered list of PropertiesFilter objects
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the the filtered String property.
See Also:
PropertiesFilter

getCollectionProperty

public java.util.Map getCollectionProperty(java.lang.String channel,
                                           java.lang.String name,
                                           boolean localized)
                                    throws ProviderContextException
Get the localized version of a collection property. Locales are searched from more to less specific. For example, for a locale setting of "en_US_WE", the search order would be: en_US_WE, en_US, en. If the locale-specific property is not found, then the non-locale-specific version is returned (if it exists).

Parameters:
channel - Channel name.
name - Property name.
localized - Search for a localized version?
Returns:
Property value, a Java Map that maps Strings to Java objects, either String, Integer, Boolean, or Map.
Throws:
ProviderContextException - if an error occurs in getting localized version of the Collection property.
See Also:
getCollectionProperty(String, String)

getCollectionProperty

public java.util.Map getCollectionProperty(java.lang.String channel,
                                           java.lang.String name,
                                           java.util.Map def,
                                           boolean localized)
                                    throws ProviderContextException
Get the localized version of a collection property.

Parameters:
channel - Channel name.
name - Property name.
def - Default value.
localized - Search for a localized version?
Returns:
Property value, a Java Map that maps Strings to Java objects, either String, Integer, Boolean, or Map.
Throws:
ProviderContextException - if an error occurs in getting the localized version of the Collection property.
See Also:
getCollectionProperty(String, String)

setCollectionProperty

public void setCollectionProperty(java.lang.String channel,
                                  java.lang.String key,
                                  java.util.Map val)
                           throws ProviderContextException
Sets a collection property.

Parameters:
channel - Channel name.
key - Property name.
Returns:
New property value.
Throws:
ProviderContextException - if an error occurs in setting the Collection property.
See Also:
getCollectionProperty(String, String)

setCollectionProperty

public void setCollectionProperty(java.lang.String channel,
                                  java.lang.String key,
                                  java.util.Map val,
                                  java.util.List pflist)
                           throws ProviderContextException
Sets a collection property according to the given filter criteria. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If the property that matches the filter criteria does not exist, the most specific, existing property gets set. If only the default value existed, it sets the default value. If the default and filtered properties existed, it sets the most specific existing filtered property. Note that the "exact" flag in the PropertiesFilters has no meaning and will be ignored.

Parameters:
channel - Channel name.
key - Property name.
pflist - An ordered list of PropertiesFilter objects
Throws:
ProviderContextException - if an error occurs in setting the collection property.
See Also:
PropertiesFilter

setCollectionProperty

public void setCollectionProperty(java.lang.String channel,
                                  java.lang.String name,
                                  java.util.List value)
                           throws ProviderContextException
Sets a collection property.

Parameters:
channel - Channel name.
name - Property name.
value - Proeprty value.
Throws:
ProviderContextException - if an error occurs in setting the Collection property.
See Also:
getCollectionProperty(String, String)

setCollectionProperty

public void setCollectionProperty(java.lang.String channel,
                                  java.lang.String key,
                                  java.util.List val,
                                  java.util.List pflist)
                           throws ProviderContextException
Sets a collection property according to the given filter criteria. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If the property that matches the filter criteria does not exist, the most specific, existing property gets set. If only the default value existed, it sets the default value. If the default and filtered properties existed, it sets the most specific existing filtered property. Note that the "exact" flag in the PropertiesFilters has no meaning and will be ignored.

Parameters:
channel - Channel name.
key - Property name.
pflist - An ordered list of PropertiesFilter objects
Throws:
ProviderContextException - if an error occurs in setting the collection property.
See Also:
PropertiesFilter

getBooleanProperty

public boolean getBooleanProperty(java.lang.String channel,
                                  java.lang.String name)
                           throws ProviderContextException
Get a boolean property property.

Parameters:
channel - Channel name.
name - Property name.
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the boolean property.

getBooleanProperty

public boolean getBooleanProperty(java.lang.String channel,
                                  java.lang.String name,
                                  java.util.List pflist)
                           throws ProviderContextException
Get the filtered boolean property property. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If there is no property that exactly matches the filter criteria, the best partial match is returned. When there is not even a partial match, an unfiltered property is returned.

Parameters:
channel - Channel name.
name - Property name.
pflist - An ordered list of PropertiesFilter objects
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the boolean property.

getBooleanProperty

public boolean getBooleanProperty(java.lang.String channel,
                                  java.lang.String name,
                                  boolean def)
                           throws ProviderContextException
Get a boolean property property. This method returns a default value if the property does not exist.

Parameters:
channel - Channel name.
name - Property name.
def - Default value.
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the boolean property.

getBooleanProperty

public boolean getBooleanProperty(java.lang.String channel,
                                  java.lang.String name,
                                  boolean def,
                                  java.util.List pflist)
                           throws ProviderContextException
Get the filtered boolean property property. This method returns a default value if the property does not exist. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If there is no property that exactly matches the filter criteria, the best partial match is returned. When there is not even a partial match, an unfiltered property is returned.

Parameters:
channel - Channel name.
name - Property name.
def - Default value.
pflist - An ordered list of PropertiesFilter objects
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the boolean property.

setBooleanProperty

public void setBooleanProperty(java.lang.String channel,
                               java.lang.String name,
                               boolean value)
                        throws ProviderContextException
Sets a boolean property.

Parameters:
channel - Channel name.
name - Property name.
value - Property value.
Throws:
ProviderContextException - if an error occurs in setting the boolean property.

setBooleanProperty

public void setBooleanProperty(java.lang.String channel,
                               java.lang.String name,
                               boolean value,
                               java.util.List pflist)
                        throws ProviderContextException
Sets a boolean property according to the given filter criteria. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If the property that matches the filter criteria does not exist, the most specific, existing property gets set. If only the default value existed, it sets the default value. If the default and filtered properties existed, it sets the most specific existing filtered property. Note that the "exact" flag in the PropertiesFilters has no meaning and will be ignored.

Parameters:
channel - Channel name.
name - Property name.
value - Property value.
pflist - An ordered list of PropertiesFilter objects
Throws:
ProviderContextException - if an error occurs in setting the boolean property.

getIntegerProperty

public int getIntegerProperty(java.lang.String channel,
                              java.lang.String name)
                       throws ProviderContextException
Get an integer property.

Parameters:
channel - Channel name.
name - Property name.
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the integer property.

getIntegerProperty

public int getIntegerProperty(java.lang.String channel,
                              java.lang.String name,
                              java.util.List pflist)
                       throws ProviderContextException
Get the filtered integer property. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If the property that matches the filter criteria does not exist, a new property will be created. Note that the "exact" flag in the PropertiesFilters has no meaning and will be ignored.

Parameters:
channel - Channel name.
name - Property name.
pflist - An ordered list of PropertiesFilter objects
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the integer property.

getIntegerProperty

public int getIntegerProperty(java.lang.String channel,
                              java.lang.String name,
                              int def)
                       throws ProviderContextException
Get an integer property. This method returns a default value if the property does not exist.

Parameters:
channel - Channel name.
name - Property name.
def - Default value.
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the integer property.

getIntegerProperty

public int getIntegerProperty(java.lang.String channel,
                              java.lang.String name,
                              int def,
                              java.util.List pflist)
                       throws ProviderContextException
Get an integer property. This method returns a default value if the property does not exist. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If the property that matches the filter criteria does not exist, a new property will be created. Note that the "exact" flag in the PropertiesFilters has no meaning and will be ignored.

Parameters:
channel - Channel name.
name - Property name.
def - Default value.
pflist - An ordered list of PropertiesFilter objects
Returns:
Property value.
Throws:
ProviderContextException - if an error occurs in getting the integer property.

setIntegerProperty

public void setIntegerProperty(java.lang.String channel,
                               java.lang.String name,
                               int value)
                        throws ProviderContextException
Sets an integer property.

Parameters:
channel - Channel name.
name - Property name.
value - Property value.
Throws:
ProviderContextException - if an error occurs in setting the integer property.

setIntegerProperty

public void setIntegerProperty(java.lang.String channel,
                               java.lang.String name,
                               int value,
                               java.util.List pflist)
                        throws ProviderContextException
Sets an integer property according to the given filter criteria. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If the property that matches the filter criteria does not exist, the most specific, existing property gets set. If only the default value existed, it sets the default value. If the default and filtered properties existed, it sets the most specific existing filtered property. Note that the "exact" flag in the PropertiesFilters has no meaning and will be ignored.

Parameters:
channel - Channel name.
name - Property name.
value - Property value.
pflist - An ordered list of PropertiesFilter objects
Throws:
ProviderContextException - if an error occurs in setting the integer property.

existsStringProperty

public boolean existsStringProperty(java.lang.String channel,
                                    java.lang.String name)
                             throws ProviderContextException
Test for the existence of a string property.

Parameters:
channel - Channel name.
name - a String, the property name.
Returns:
a boolean, true if the property exists, otherwise false.
Throws:
ProviderContextException - if an error occurs in testing for the existence of a String property.

existsStringProperty

public boolean existsStringProperty(java.lang.String channel,
                                    java.lang.String name,
                                    java.util.List pflist)
                             throws ProviderContextException
Test for the existence of a filtered string property. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If the property that matches the filter criteria does not exist, a new property will be created. Note that the "exact" flag in the PropertiesFilters has no meaning and will be ignored.

Parameters:
channel - Channel name.
name - a String, the property name.
pflist - An ordered list of PropertiesFilter objects existence of localized properties.
Returns:
a boolean, true if the property exists, otherwise false.
Throws:
ProviderContextException - if an error occurs in testing for the existence of a String property.

existsStringProperty

public boolean existsStringProperty(java.lang.String channel,
                                    java.lang.String name,
                                    boolean localized)
                             throws ProviderContextException
Test for the existence of a string property. This method will also check for the existence of the localized version of the property.

Parameters:
channel - Channel name.
name - a String, the property name.
localized - a boolean, whether to check the existence of localized properties.
Returns:
a boolean, true if the property exists, otherwise false.
Throws:
ProviderContextException - if an error occurs in testing for the existence of a String property.

existsBooleanProperty

public boolean existsBooleanProperty(java.lang.String channel,
                                     java.lang.String name)
                              throws ProviderContextException
Test for the existence of a boolean property.

Parameters:
channel - Channel name.
name - a String, the property name.
Returns:
a boolean, true if the property exists, otherwise false.
Throws:
ProviderContextException - if an error occurs in testing for the existence of a boolean property.

existsBooleanProperty

public boolean existsBooleanProperty(java.lang.String channel,
                                     java.lang.String name,
                                     java.util.List pflist)
                              throws ProviderContextException
Test for the existence of the filtered boolean property. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If the property that matches the filter criteria does not exist, a new property will be created. Note that the "exact" flag in the PropertiesFilters has no meaning and will be ignored.

Parameters:
channel - Channel name.
name - a String, the property name.
pflist - An ordered list of PropertiesFilter objects
Returns:
a boolean, true if the property exists, otherwise false.
Throws:
ProviderContextException - if an error occurs in testing for the existence of a boolean property.

existsIntegerProperty

public boolean existsIntegerProperty(java.lang.String channel,
                                     java.lang.String name)
                              throws ProviderContextException
Test for the existence of an integer property.

Parameters:
channel - Channel name.
name - a String, the property name.
Returns:
a boolean, true if the property exists, otherwise false.
Throws:
ProviderContextException - if an error occurs in testing for the existence of an integer property.

existsIntegerProperty

public boolean existsIntegerProperty(java.lang.String channel,
                                     java.lang.String name,
                                     java.util.List pflist)
                              throws ProviderContextException
Test for the existence of the filtered integer property. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If the property that matches the filter criteria does not exist, a new property will be created. Note that the "exact" flag in the PropertiesFilters has no meaning and will be ignored.

Parameters:
channel - Channel name.
name - a String, the property name.
pflist - An ordered list of PropertiesFilter objects
Returns:
a boolean, true if the property exists, otherwise false.
Throws:
ProviderContextException - if an error occurs in testing for the existence of an integer property.

existsCollectionProperty

public boolean existsCollectionProperty(java.lang.String channel,
                                        java.lang.String name)
                                 throws ProviderContextException
Test for the existence of a collection property.

Parameters:
channel - Channel name.
name - a String, the property name.
Returns:
a boolean, true if the property exists, otherwise false.
Throws:
ProviderContextException - if an error occurs in testing for the existence of a Collection property.

existsCollectionProperty

public boolean existsCollectionProperty(java.lang.String channel,
                                        java.lang.String name,
                                        java.util.List pflist)
                                 throws ProviderContextException
Test for the existence of the filtered collection property. Filter criteria can be specified using a series of PropertiesFilter objects. The order in that the PropertiesFilter objects are listed determines the order that the property is searched. If the property that matches the filter criteria does not exist, a new property will be created. Note that the "exact" flag in the PropertiesFilters has no meaning and will be ignored.

Parameters:
channel - Channel name.
name - a String, the property name.
pflist - An ordered list of PropertiesFilter objects
Returns:
a boolean, true if the property exists, otherwise false.
Throws:
ProviderContextException - if an error occurs in testing for the existence of a Collection property.

existsCollectionProperty

public boolean existsCollectionProperty(java.lang.String channel,
                                        java.lang.String name,
                                        boolean localized)
                                 throws ProviderContextException
Test for the existence of a collection property. This method will also check for the existence of the localized version of the property.

Parameters:
channel - Channel name.
name - a String, the property name.
localized - a boolean, whether to check the existence of localized properties.
Returns:
a boolean, true if the property exists, otherwise false.
Throws:
ProviderContextException - if an error occurs in testing for the existence of a Collection property.

getLocalePropertiesFilters

public java.util.List getLocalePropertiesFilters()
                                          throws ProviderContextException
Get the locale in the form of PropertiesFilter's. Each locale suffix is used to create PropertiesFilter. Note that by default, the PropertiesFilter objects return in the list are constructed with their "required" flag set to false. See the javadocs for PropertiesFilter for more information on the semantics of the required flag. Use getPropertiesFilter() method should you need to customize the required flag.

Returns:
List of PropertiesFilter objects representing the locale setting.
Throws:
ProviderContextException - if an error occurs in creating PropertiesFilter objects.
See Also:
PropertiesFilter, PropertiesFilter.isRequired()

getClientAndLocalePropertiesFilters

public java.util.List getClientAndLocalePropertiesFilters()
                                                   throws ProviderContextException
Get the client and locale in the form of PropertiesFilter's. Each client and locale suffix is used to create PropertiesFilter. Note that by default, the PropertiesFilter objects return in the list are constructed with their "required" flag set to false. See the javadocs for PropertiesFilter for more information on the semantics of the required flag. Use getPropertiesFilter() method should you need to customize the required flag. This method is a convenience for putting together a list of properties filters for the current session's locale and client type. the property filter list returned from this method can be used as input to the to access properties in a locale and client type specific manner.

Returns:
List of PropertiesFilter objects representing the client and locale setting.
Throws:
ProviderContextException - if an error occurs in creating PropertiesFilter objects.
See Also:
PropertiesFilter, PropertiesFilter.isRequired(), getClientPropertiesFilters(), getLocalePropertiesFilters()

getClientPropertiesFilters

public java.util.List getClientPropertiesFilters()
                                          throws ProviderContextException
Get the client PropertiesFilter's. The hierarchy of client PropertiesFilter is returned. Note that by default, the PropertiesFilter objects return in the list are constructed with their "required" flag set to false. See the javadocs for PropertiesFilter for more information on the semantics of the required flag. Use getPropertiesFilter() method should you need to customize the required flag.

Returns:
List of PropertiesFilter objects representing the client.
Throws:
ProviderContextException - if an error occurs in creating PropertiesFilter objects.
See Also:
PropertiesFilter, PropertiesFilter.isRequired()

getClientPropertiesFilters

public java.util.List getClientPropertiesFilters(java.lang.String clientType)
Get the client PropertiesFilter's for a given clientType. The hierarchy of client PropertiesFilter is returned. Note that by default, the PropertiesFilter objects return in the list are constructed with their "required" flag set to false. See the javadocs for PropertiesFilter for more information on the semantics of the required flag. Use getPropertiesFilter() method should you need to customize the required flag. It is advisable to use getClientPropertiesFilters() if getting the filters for the current clientType.

Parameters:
clientType - client type.
Returns:
List of PropertiesFilter objects representing the client.
See Also:
PropertiesFilter, PropertiesFilter.isRequired(), getClientPropertiesFilters()

getStaticContentPath

public java.lang.String getStaticContentPath()
Get the URI prefix to web server static content. Static content may be located separately from dynamic content such as servlets and JSP. This URI prefix is used to access static web content such as images and HTML files. For example, to reference an image, a the href might look like:

http://server:port/STATIC_URI/images/foo.gif

Returns:
URI prefix.

getServletConfig

public javax.servlet.ServletConfig getServletConfig()
Deprecated. A specific front end servlet cannot be assumed. Therefore, programmers should not access a ServletConfig object since it may make their Providers non-portable to other environments. Use getServletContext() instead.

Get the Servlet Config.

Returns:
ServletConfig object.
See Also:
getServletContext()

getServletContext

public javax.servlet.ServletContext getServletContext()
Get the Servlet Context.

Returns:
ServletContext object.

getDefaultChannelName

public java.lang.String getDefaultChannelName()
Get the default channel name. This method returns the channel name from the session using getSessionProperty if exists. If not returns the defaultChannelName attribute using getStringAtribute

Returns:
a String, name of the channel
See Also:
getSessionProperty(String), getStringAttribute(String)

getConfigProperty

public java.lang.String getConfigProperty(java.lang.String key)
Get the named configuration property.

Parameters:
key - a String, the property name.
Returns:
a String, the property value.

getParentContainerName

public java.lang.String getParentContainerName(java.lang.String channel)
Get the display container name for the named channel. A display container visually holds another channel. This method returns the parent container name in which this channel is contained on the desktop page. returns null if this channel is the parent container or if this method is called outside getContent() in Provider class. A channel only has a display container when it is being visually displayed within a container channel. This method relies on CPC.getContent() to set up the display container name. Calling this method in a call stack that does not include CPC.getContent() somewhere above the current stack frame will result in a return value of null. For an example of where it makes sense to use this method, consider this: container A calls CPC.getContent() to gather content for the channels that is visually contains. CPC.getContent() calls channel X's getContent() method. Channel X may now call PC.getParentContainerName(). For an exmaple of where it *does not* make sense to us this method, consider this: channel X calls PC.getParentContainerName() from within it's getEdit() method. When a channel is displaying it's edit page, it is not visually contained. At this point, channel X has no display container as PC.getParentContainerName() will return null.

Parameters:
channel - Channel name for which the parent is requested.
Returns:
a String, name of the parent container or null if parent is not known.
See Also:
ContainerProviderContext.getContent()

getRoles

public java.util.Set getRoles()
Get the roles the user is in. This method returns the set of strings where each string corresponds to the role the user is in.

Returns:
Set of roles the user is in.

getTopChannelName

public java.lang.String getTopChannelName(javax.servlet.http.HttpServletRequest req)
Get the top channel name. This method returns the top channel for the current request, identified by the request object argument. The top channel is responsible for directly rendering the portal page or by partially or wholly delegating the rendering to one or more channels.

Parameters:
req - HttpServletRequest
Returns:
a String, name of the channel

encodeURLParameter

public java.lang.String encodeURLParameter(java.lang.String enc)
URL encodes a unicode string This method is used for encoding multi-byte characters to be passed as arguments in a URL. This method converts the string to encode into a sequence of bytes using the default charset UTF-8() and then the sequence is converted to urlencoded format. All URL parameter values that are passed to the desktop and that may be localized (non-ascii) must be url encoded using this method and should be decoded using decodeURLParameter when getting it back from the request.

Parameters:
enc - string to encode
Returns:
a String, encoded string
See Also:
decodeURLParameter(java.lang.String)

decodeURLParameter

public java.lang.String decodeURLParameter(java.lang.String dec)
Decodes the URL encoded Unicode string This method is used for decoding urlencoded multi-byte characters that were passed as arguments in a URL

Parameters:
dec - string to decode
Returns:
a String, decoded string
See Also:
encodeURLParameter(java.lang.String)