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 TBD

Method Summary

void	createChannel(String channelName, String providerName) Creates a new global scope channel.
void	createContainer(String channelName, String providerName) Creates a new global scope container channel.A global scope channel can be referenced globally from all other channels.
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, encodeURL, existsBooleanProperty, existsCollectionProperty, existsCollectionProperty, existsIntegerProperty, existsStringProperty, existsStringProperty, getBooleanProperty, getBooleanProperty, getCharset, getClassName, getClientPath, getClientProperty, getClientType, getClientTypeProperty, getClientTypeProperty, getCollectionProperty, getCollectionProperty, getCollectionProperty, getCollectionProperty, getConfigProperty, getContentType, getDefaultChannelName, getDefaultClientType, getDesktopType, getDesktopURL, getIntegerProperty, getIntegerProperty, getLocale, getLocaleString, getLogoutURL, getNames, getProperty, getProperty, getProviderName, getRequestServer, getServletConfig, getSessionID, getSessionProperty, getStaticContentPath, getStringAttribute, getStringProperty, getStringProperty, getStringProperty, getStringProperty, getTemplate, getTemplate, getTemplateMostSpecificPath, getTemplatePath, getUserID, init, isDebugEnabled, isDebugErrorEnabled, isDebugMessageEnabled, isDebugWarningEnabled, refresh, setBooleanProperty, setClientProperty, setCollectionProperty, setCollectionProperty, setIntegerProperty, setProperty, setSessionProperty, setStringAttribute, setStringProperty

Field Detail

CHANNEL_NAME_SEPARATOR

public static final char CHANNEL_NAME_SEPARATOR

TBD

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 global scope channel. A global scope channel can be referenced globally from all other channels.

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 global scope container channel.A global scope channel can be referenced globally from all other channels.

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)

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.

name - Channel name.

Returns:

a StringBuffer that is the channels content view.

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.

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.

selected - List of Strings; the channel names.

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.