Chapter 5 Overview of the Container Providers

Containers are simply channels that include in their output the content of one or more other channels. The container providers present containment metaphors for channel aggregation including single, table, tab, and framed.

This chapter discusses the out-of-the-box extensible set of container providers that implement various metaphors for aggregating content and contains the following sections:

• The ContainerProvider Architecture

• Overview of the ContainerProviders

• JSPContainerProviderAdapter Class

The ContainerProvider Architecture

The ContainerProvider Architecture shows the relationship between the various interfaces and classes discussed in this chapter. The JSPProvider (see Chapter 4, Overview of the Leaf Providers for more information) and ContainerProviderAdapter classes extend ProfileProviderAdapter (see Chapter 2, Overview of the Provider API (PAPI) for more information).

The ContainerProvider interface defines the interface for implementing a container provider. A container provider is a provider that generates its views primarily by being a client of other provider objects.

The ContainerProviderAdapter provides default implementations of the following methods in the ContainerProvider: get/setSelectedChannels(), get/setAvailableChannels(), get/setWindowState(), and getSupportedWindowStates(). For more information on all the methods in this class, see the Javadocs.

The ContainerProviderContext extends ProviderContext and adds container functionality to the ProviderContext interface. The ContainerProviderAdapter uses the ContainerProviderContext object as the persistent store.

The JSPContainerProviderAdapter extends the JSPProvider (see Chapter 4, Overview of the Leaf Providers for more information) and provides implementations of methods in the ContainerProvider interface to facilitate the execution of JavaServer Pages^TM (JSP^TM).

The JSPTabContainerProvider extends the JSPContainerProviderAdapter and provides default implementation for methods in the TabContainer interface. The JSPSingleContainerProvider and the JSPTableContainerProvider also extend the JSPContainerProviderAdapter.

Figure 5–1 The ContainerProvider Architecture

Overview of the ContainerProviders

To support the container providers, the PAPI includes three APIs, the ContainerProvider interface, the ContainerProviderAdapter class, and the ContainerProviderContext interface. This section provides an overview of these three APIs.

ContainerProvider Interface

The ContainerProvider interface defines the interface for implementing a container provider and is the programmatic entity for generating container channels.

A container provider has a selected and available channels list, and allows getting and setting of these lists. Selected channels are those that are considered active on the Desktop. Available channels are those that are available to be activated on the Desktop. That is, selected channels are those that are available and selected for display on the Desktop by the user; available channels are those that are available for display on the Desktop, but not selected for display on the Desktop by the user.

The Desktop container providers (such as JSPSingleContainerProvider, JSPTableContainerProvider, and JSPTabContainerProvider) discussed in this chapter extend the JSPContainerProviderAdapter that implements the ContainerProvider interface.

The ContainerProvider includes interfaces to get/setAvailableChannels and get/setSelectedChannels. See the Javadocs for more information.

ContainerProviderContext Interface

The ContainerProviderContext interface provides an environment for container provider execution. More formally, this class adds container channel functionality to the ProviderContext interface (see Chapter 2, Overview of the Provider API (PAPI) for more information). That is, where provider object can obtain access to a ProviderContext object, container providers obtain access to a ContainerProviderContext object.

A ContainerProviderContext object has a superset of the functionality exposed in ProviderContext. The additions are related to managing contained providers. For example, container channel functionality includes getting provider objects, fetching content, content caching, adding clients, creating channels and containers, and getting and setting selected and available channels list.

The ContainerProviderContext is the object to get the container channel properties from the store at run time. The ContainerProviderContext can also be used to getProvider() on another channel or container and getContent() on another channel or container.

ContainerProviderAdapter Class

The ContainerProviderAdapter class extends ProfileProviderAdapter. ContainerProviderAdapter can be used as the base class for any container provider (except for the JSP-based container providers, which can extend the JSPContainerProviderAdapter). For example, the sample template-based Desktop container providers are developed based on this class.

The ContainerProviderAdapter class provides default implementations of methods in the ContainerProvider interface implemented using a ContainerProviderContext object as the persistent store. This class also has the getContainerProviderContext() method, which gets the container provider context, in addition to the get/setAvailableChannels and get/setSelectedChannels methods.

JSPContainerProviderAdapter Class

To extend container functionality for JSP-based container providers, a JSPContainerProviderAdapter class is included with the software. This class extends the JSPProvider. The JSPContainerProviderAdapter can be used as the base class for any JSP-based ContainerProvider and is similar in functionality to the ContainerProviderAdapter. For example, the JSPSingleContainerProvider extends from this class.

The JSPContainerProviderAdapter class provides default implementations of methods in the ContainerProvider interface implemented using a ContainerProviderContext object as the persistent store and extends JSPProvider to facilitate the execution of JSPs. It includes interfaces to get/setAvailableChannels(), get/setSelectedChannels(), and getContainerProviderContext().

Three sample extensions (namely JSPSingleContainerProvider Class, JSPTableContainerProvider Class, and JSPTabContainerProvider Class) to the JSPContainerProviderAdapter API are included.

JSPSingleContainerProvider Class

This section contains the following:

• Introduction to JSPSingleContainerProvider

• Using the JSPSingleContainerProvider

Introduction to JSPSingleContainerProvider

A single container wraps the content of a single channel. The single container enables a channel to take over an entire browser page. For example, this can be used to provide the front page or can be used to display a single channel whose name is passed in the request parameter. Typically, the front page consists of some banners and the output of another channel. The purpose of the single channel is to allow these banners, menu bars, and the like to be wrapped around the content of the included channel.

Another purpose of the single container is that the decorational elements (such as banners and menu bars) which wrap around the channel can be easily changed without changing the channel itself.

Using the JSPSingleContainerProvider

The JSPSingleContainerProvider class extends JSPContainerProviderAdapter. A single container simply displays a single leaf channel or a container. It must be a JSP that wraps a container or leaf channel.

The JSPSingleContainerProvider Class

Steps

1. Gets the selected channel name.

2. Returns the selected channel name as a String.

   If more than one channel is defined, it displays the first channel in the list.

   Some examples of single container include JSPContentContainer, JSPLayoutContainer, JSPEditContainer.

JSPTableContainerProvider Class

This section contains the following:

• Introduction to JSPTableContainerProvider

• Using the JSPTableContainerProvider

Introduction to JSPTableContainerProvider

A table container aggregates the content of other channels into rows and columns. It can be thought of as a bucket for the content of other channels. The JSPTableContainerProvider class extends JSPContainerProviderAdapter.

The table container facilitates the aggregation of multiple channels into a single display. That is, the JSPTableContainerProvider aggregates channels into HTML rows and columns.

Using the JSPTableContainerProvider

A JSPTableContainerProvider provides methods that allow the associated JSP files to use these methods, and generate a view that arranges the contained channels to be displayed in a HTML table. By the nature of the container provider, the JSPTableContainer has a list of available channels and a list of selected channels.

Available channels are the channels that are available to be activated in the Desktop, and selected channels are the channels that are displayed in the Desktop. Selected and available channels list is defined in the table container channel definition in the display profile.

The TabContainer

A tab container aggregates the output of channels, providing a tabbed user interface to switch between them. A tab container’s configuration can be modified at runtime to vary which leaf channel is displayed.

A tab container provider generates its views primarily by being a client of table container objects. The TabContainer displays one of its contained channels at a time. It allows containers to be arranged onto virtual pages. The container can then switch between these pages allowing them to be physically viewed one at a time.

It allows the user to switch logically separate row-column displays. From the container perspective, each page is a table container. The tab container then contains multiple table containers, one for each page. By default, each tab in a tab container corresponds to a table container. The tab container can contain any number of table, single, or tab containers theoretically. Having a tab container inside a tab container is not advisable.

A tab container provider is a container provider that has a selected and available channels list, and allows getting and setting of these lists. Selected channels are the table containers that are considered active on the Desktop. Available channels are those that are available to be activated on the Desktop.

The TabContainer interface defines the interface for implementing a TabContainerProvider. A TabContainerProvider must implement this interface. This interface contains methods to query information about a TabContainer and to set the properties of a TabContainer. See the Javadocs for more information on the methods in this interface.

UnmodifiableTab Interface

The UnmodifiableTab interface represents a tab that cannot be modified. This interface includes methods to:

• Get the name (getName()), the display name (getDisplayname()), the HTML encoded name (getEncodedName()), and description (getDesc()) of the tab as a string.

• Get the properties (getTabMap()) of the tab as a map.

• Determine whether or not the tab is removable (isRemovable()) and renamable (isRenamable()) by returning true or false.

• Determine if the tab was created by the user or was predefined for the user (isPredefined()) by returning true or false. A value of true indicates that the tab was predefined and a value of false indicates that the tab was created by the user.

ModifiableTab Interface

The ModifiableTab interface represents an instance of the tab that can be modified. It extends UnmodifiableTab and all modifiable tabs inherit the characteristics of the UnmodifiableTab. This interface provides methods to allow the user to reset the display name (setDisplayname()) and description (setDesc()) of the predefined tab.

JSPTabContainerProvider Class

The JSPTabContainerProvider includes the functionality to enable display of JSPs in the TabContainer environment. It provides methods that allow the associated JSP files to use these methods, and generate a view that aggregates the output of channels, providing a tabbed user interface to switch between them.

The JSPTabContainerProvider class extends JSPContainerProviderAdapter and implements the TabContainer interface.