com.sun.portal.providers.context
Interface ContainerProviderContext

All Superinterfaces:
ProviderContext

public interface ContainerProviderContext
extends ProviderContext

An environment for container provider execution. More formally, this class adds container channel functionality to the ProviderContext interface. Container channel functionality includes getting provider objects, fetching content, content caching features, and getting / setting selected and available channel lists.

See Also:
ProviderContext

Field Summary
static char CHANNEL_NAME_SEPARATOR
          Separator character for nested channel names.
 
Method Summary
 void copyChannel(String srcName, String dstName)
          Copies a channel.
 void createChannel(String channelName, String providerName)
          Creates a new channel.
 void createContainer(String channelName, String providerName)
          Creates a new container channel.
 boolean existsChannel(String channel)
          Tests if channel configuration exists.
 List getAvailableChannels(String container)
          Gets the available channels for the container channel that this is providing an environment for.
 StringBuffer getCachedContent(String name)
          Gets the cached content view for a channel.
 long getCachedTime(String name)
          Gets the content view cache time for a channel.
 Map getContent(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res, String container, List channels, int timeout)
          Gets the content view for a set of channels.
 StringBuffer getContent(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res, String container, String channel)
          Gets the content view for the named channel.
 Provider getProvider(javax.servlet.http.HttpServletRequest req, String container, String channel)
          Gets a provider.
 List getSelectedChannels(String container)
          Gets the selected channels for the container channel that this is providing an environment for.
 void initProviders(javax.servlet.http.HttpServletRequest req, String container, List channels, int timeout)
          Initializes a set of channels.
 void putCachedContent(String name, StringBuffer content)
          Puts the cached content into a map and using the provider name as the key.
 void removeChannel(String channelName)
          Removes a global scope channel.
 void setAvailableChannels(String container, List available)
          Sets the available channels for the container channel that this is providing an environment for.
 void setSelectedChannels(String container, List selelected)
          Sets the selected channels for the container channel that this is providing an environment for.
 
Methods inherited from interface com.sun.portal.providers.context.ProviderContext
allContentChanged, contentChanged, debugError, debugError, debugMessage, debugMessage, debugWarning, debugWarning, decodeURLParameter, encodeURL, encodeURLParameter, escape, existsBooleanProperty, existsBooleanProperty, existsCollectionProperty, existsCollectionProperty, existsCollectionProperty, existsIntegerProperty, existsIntegerProperty, existsStringProperty, existsStringProperty, existsStringProperty, getAuthenticationType, getBooleanProperty, getBooleanProperty, getBooleanProperty, getBooleanProperty, getCharset, getClassName, getClientAndLocalePropertiesFilters, getClientPath, getClientPropertiesFilters, getClientPropertiesFilters, getClientProperty, getClientType, getClientTypeProperties, getClientTypeProperty, getClientTypeProperty, getCollectionProperty, getCollectionProperty, getCollectionProperty, getCollectionProperty, getCollectionProperty, getCollectionProperty, getConfigProperty, getContentType, getDefaultChannelName, getDefaultClientType, getDesktopType, getDesktopURL, getDesktopURL, getDesktopURL, getDesktopURL, getIntegerProperty, getIntegerProperty, getIntegerProperty, getIntegerProperty, getLocale, getLocalePropertiesFilters, getLocaleString, getLoginURL, getLogoutURL, getNames, getParentContainerName, getProperty, getProperty, getProviderName, getProviderVersion, getRequestServer, getRoles, getServletConfig, getServletContext, getSessionID, getSessionProperty, getStaticContentPath, getStringAttribute, getStringAttribute, getStringProperty, getStringProperty, getStringProperty, getStringProperty, getStringProperty, getStringProperty, getTemplate, getTemplate, getTemplate, getTemplate, getTemplateMostSpecificPath, getTemplateMostSpecificPath, getTemplatePath, getTemplatePath, getTopChannelName, getUserID, init, isAuthless, isDebugEnabled, isDebugErrorEnabled, isDebugMessageEnabled, isDebugWarningEnabled, refresh, setBooleanProperty, setBooleanProperty, setClientProperty, setCollectionProperty, setCollectionProperty, setCollectionProperty, setCollectionProperty, setIntegerProperty, setIntegerProperty, setProperty, setSessionProperty, setStringAttribute, setStringProperty, setStringProperty
 

Field Detail

CHANNEL_NAME_SEPARATOR

public static final char CHANNEL_NAME_SEPARATOR
Separator character for nested channel names. Channels configuration can be defined in a nested, hierarchical manner within containers. This affects the name of the channel. For example, if channel A was defined with container X, the full name of the channel would be X + CHANNEL_NAME_SEPARATOR + A. This name is used in all ContainerProviderContext and ProviderContext methods that accept a channel name. Examples of this are:

See Also:
Constant Field Values
Method Detail

existsChannel

public boolean existsChannel(String channel)
Tests if channel configuration exists.

Parameters:
channel - a String, the channel name.
Returns:
a boolean, true if the channel has been added, otherwise false.

createChannel

public void createChannel(String channelName,
                          String providerName)
                   throws ProviderContextException
Creates a new channel. A new channel is created based on the named provider. To create a nested channel, supply a hierarchical channel name. For example, to create channel A inside of container X, based on provider P:

createChannel("X" + CHANNEL_NAME_SEPARATOR + "A", "P");

This method only modifies the underlying configuration and does not create a Provider object. After calling this method, to get the provider object that backs this channel, call getProvider().

Parameters:
channelName - Name of the channel being created.
providerName - Symbolic name of the provider that will back the channel being created.
Throws:
ProviderContextException - if an error occurs in creating the new global scope channel.
See Also:
getProvider(HttpServletRequest, String, String)

createContainer

public void createContainer(String channelName,
                            String providerName)
                     throws ProviderContextException
Creates a new container channel. A new container channel is created based on the named provider. To create a nested container channel, supply a hierarchical channel name. For example, to create container C inside of container X, based on provider P:

createContainer("X" + CHANNEL_NAME_SEPARATOR + "C", "P");

This method only modifies the underlying configuration and does not create a Provider object. After calling this method, to get the provider object that backs this channel, call getProvider().

Parameters:
channelName - Name of the channel being created.
providerName - Symbolic name of the provider that will back the container being created.
Throws:
ProviderContextException - if an error occurs in creating a global scope container channel.
See Also:
getProvider(HttpServletRequest, String, String)

copyChannel

public void copyChannel(String srcName,
                        String dstName)
                 throws ProviderContextException
Copies a channel. A copy of the source channel is created and named as the destination channel. All properties of the source channel are copied to the destination channel. The destination channel will use the same provider as the source. To copy a channel into a container, supply a hierarchical channel name. For example, to copy channel A inside of container X, renaming it as channel B: copyChannel("A", "X" + CHANNEL_NAME_SEPARATOR + "B");

This method only modifies the underlying configuration and does not create a Provider object. After calling this method, to get the provider object that backs this channel, call getProvider().

This method copies container channels as well as channels. To copy a container channel, simply supply its name as the source.

Parameters:
srcName - Name of the source channel, the channel to be copied.
dstName - Name of the destination channe, the channel copy.
Throws:
ProviderContextException - if an error occurs copying the channel.
See Also:
getProvider(HttpServletRequest, String, String)

removeChannel

public void removeChannel(String channelName)
                   throws ProviderContextException
Removes a global scope channel.

This method only modifies the underlying configuration and does not modify the references of the channel in other places in the configuration.

Parameters:
channelName - Name of the channel being removed.
Throws:
ProviderContextException - if an error occurs in removing the global scope channel.

getProvider

public Provider getProvider(javax.servlet.http.HttpServletRequest req,
                            String container,
                            String channel)
Gets a provider. This method returns an instance of a Provider object for the named channel. This method will return null if the provider object is not available.

The HTTP request object parameter must contain implementation specific initialization information.

Parameters:
req - an HttpServletRequest object containing provider initialization information.
container - Container channel name, or null if the channel is not contained.
channel - a String, the channel name.
Returns:
Provider object for the given channel name.

getContent

public StringBuffer getContent(javax.servlet.http.HttpServletRequest req,
                               javax.servlet.http.HttpServletResponse res,
                               String container,
                               String channel)
                        throws ProviderException
Gets the content view for the named channel. This method is provided for convenience. It gets the provider object for the named channel and calls Provider.getContent(HttpServletRequest, HttpServletResponse).

Parameters:
req - an HttpServletRequest object to pass on to the provider object.
res - an HttpServletResponse object to pass on to the provider object.
container - Container channel name, or null if the channel is not contained.
Returns:
a StringBuffer that is the channels content view, or null if there is an error in getting the channel content or if the channel is not presentable for that particular client type.
Throws:
ProviderException - if an error occurs in the provider's getContent() method.
See Also:
Provider.getContent(HttpServletRequest, HttpServletResponse)

initProviders

public void initProviders(javax.servlet.http.HttpServletRequest req,
                          String container,
                          List channels,
                          int timeout)
Initializes a set of channels. This method is provided for convenience. It gets the provider object for each channel and calls its Provider.init() method. Channel initialization can be an expenesive operation. This method allows said operation to be done for all channels at one time allowing for optimizations such as parallelization.

Parameters:
req - a HttpServletRequest object passed to each channel for initialized.
container - Container channel name, or null if the channel is not contained.
channels - a List of String objects; the channel names.
timeout - an int specifying the time to wait for all channels to complete initialization.
See Also:
Provider.init(String, HttpServletRequest)

getContent

public Map getContent(javax.servlet.http.HttpServletRequest req,
                      javax.servlet.http.HttpServletResponse res,
                      String container,
                      List channels,
                      int timeout)
               throws ProviderException
Gets the content view for a set of channels. This method is provided for convenience. It gets the provider object for each channel and calls its Provider.getContent() method. Fetching a channel's content view can be an expensive operation. This method allows said operation to be done in bulk for all of the channels constributing to the page allowing for optimizations such as parallelization.

Parameters:
req - a HttpServletRequest object passed to each channel in the request for its content view.
res - a HttpServletResponse object passed to each channel in the request for its content view.
container - Container channel name, or null if the channel is not contained.
channels - a List object of Strings; the channel names.
timeout - an int specifying the time to wait for all channels to complete getting their content view.
Returns:
a Map object; mapping String channel names to StringBuffer content, or mapping String channel names to null if there is an error in getting the channel content or if the channel is not presentable for that particular client type.
Throws:
ProviderException - if an error occurs in the provider's getContent() method.
See Also:
Provider.getContent(HttpServletRequest, HttpServletResponse)

getCachedContent

public StringBuffer getCachedContent(String name)
Gets the cached content view for a channel. When a channel's content view is retrieved from a channel, it is cached if the channel's provider object returns non-zero from its getRefreshTime() method. This method then gets this cached content for the channel. If containers wish to support this type of content caching, they can use this method.

Note that neither of the getContent() methods in this interface call this method automatically. It is up to the client of this interface to manually check the cache time and either call this method or call getContent() for the channel. It is not mandatory that a container channel use these features and thereby support content caching.

Parameters:
name - a String, the channel name.
Returns:
a StringBuffer, the cached content, or null if there is no cached content for the channel.
See Also:
Provider.getRefreshTime(), getCachedTime(String)

putCachedContent

public void putCachedContent(String name,
                             StringBuffer content)
Puts the cached content into a map and using the provider name as the key. The cached map is controlled internally in the implementation of this interface.

Parameters:
name - a String, the channel name.
content - StringBuffer, the cached content for the channel.

getCachedTime

public long getCachedTime(String name)
Gets the content view cache time for a channel. When the content view for a channel is cached (see getCachedContent()) the time that it was cached is also recorded. This information can be used by the client to decide if the cached value is stale.

Parameters:
name - a String, the channel name.
Returns:
a long, the cache time, in milliseconds, or -1 if the content is not cached.
See Also:
getCachedContent(String)

getSelectedChannels

public List getSelectedChannels(String container)
                         throws ProviderContextException
Gets the selected channels for the container channel that this is providing an environment for. Note that the selected channels are independent of the available channels. In other words, there may be channels that are selected but not available. This method will still include those channels and does not manipulate the result in any way. Ideally, however, a set of selected channels should be a subset of availble channels.

Parameters:
container - Container channel name. channel is not contained.
Returns:
A List of Strings; the channel names.
Throws:
ProviderContextException - if an error occurs in getting the selected channels for the named container.

getAvailableChannels

public List getAvailableChannels(String container)
                          throws ProviderContextException
Gets the available channels for the container channel that this is providing an environment for.

Parameters:
container - Container channel name.
Returns:
A List of Strings; the channel names.
Throws:
ProviderContextException - if an error occurs in getting the available channels for the named container.

setSelectedChannels

public void setSelectedChannels(String container,
                                List selelected)
                         throws ProviderContextException
Sets the selected channels for the container channel that this is providing an environment for.

Parameters:
container - Container channel name.
Throws:
ProviderContextException - if an error occurs in setting the selected channels for the named container.

setAvailableChannels

public void setAvailableChannels(String container,
                                 List available)
                          throws ProviderContextException
Sets the available channels for the container channel that this is providing an environment for.

Parameters:
container - Container channel name.
available - List of Strings; the channel names.
Throws:
ProviderContextException - if an error occurs in setting the available channels for the named container.