Introducing the Portlet Repository

The portlet repository is a content area where portlet metadata is stored. It serves two main functions:

• Firstly, the portlet repository is exposed to end users in the "Add Portlets" screen. This is the screen where users select portlets to add to Portal pages. It is in the portlet repository that a portal administrator can reorganize the portlets and folders in order to customize the "Add Portlets" screen. They may want to customize this screen in order to meet usability and organizations requirements.
• Secondly, it provides a way in which to secure portlets.

REGISTERING A PROVIDER

When a provider is registered with Oracle9iAS Portal the following events take place:

• provider metadata and the provider's portlets metadata is stored
• provider is contacted for the registration
• provider is contacted for portlet information
• portlet repository items are generated for the provider and its portlets
• the user registering the provider is given Manage privilege on the provider.

• Validates the information entered. For database providers, this validation includes verifying that the implementation package of the specified provider is valid.
• Makes a call to the provider's register provider method. For database providers, this is the provider's register_provider API. For Web providers, this is the oracle.portal.provider.v2.ProviderInstance.register() method.
• Stores the provider registration data. This data includes the provider name, display name, timeout, timeout message, login frequency, etc.
• Adds the provider to the portlet repository. The process of adding a provider to the portlet repository involves creating a folder for the provider in the portlet repository content area and then creating portlet items for each portlet along with the portlet translations. A portlet item is a custom item type that represents a provider's portlet. The steps in this process are:
• Get a list of the languages installed in Oracle9iAS Portal.
• For each language, get the provider's list of portlets by calling the wwpro_api_provider.get_portlet_list with the security parameter set to false. This in turn calls the provider to return its list of portlets in the specified language. For database providers, this call is the get_portlet_list API. For Web providers, this call is the oracle.portal.provider.v2.ProviderInstance.getPortletDefinitions().
• Create a folder for the provider. This folder is created by default and does not have dependencies with the provider registry record. The administrator may move the portlets and remove the folder if desired. The folder is created using the provider name and display name. It is assigned to the general category and it is secured to the user registering the provider. Since it is an organizational tool and not dependent on the provider, changes to the provider will not effect the folder's properties.
• For each portlet record returned, create portlet items (or its translation). The items are created using the portlet names and descriptions. They are created under the general category and do not have portlet item security turned on.
• For each portlet record returned, store the portlet record metadata.
• The user registering the provider is given Manage privilege on the provider.

When a provider is edited, the following events take place:

• Provider metadata is updated.
• The provider's portlets and all pages containing the provider's portlets are invalidated .

• Validates the information entered. For database providers, this validation includes verifying that the implementation package of the specified provider is valid.
• Updates the provider metadata.
• Invalidates the page cache for any Portal page containing any of the provider's portlets. Invalidate the portlet cache for the provider's portlets.

When a provider is registered or edited via the wwpro_api_provider_registry APIs, the users privileges are checked against the ACL associated with the provider. Oracle9iAS Portal performs the following privilege checks:

• Register a provider
• The user must have at least the Publish privilege on All Providers to register a provider.
• Editing a provider
• In order to edit a provider, the user must have either: at least the Edit privilege on All Providers, or at least Edit privilege on the specified provider.

When a provider is registered, or edited via Oracle9iAS Portal, the Oracle9iAS Portal exhibits the following behaviors:

• In the Providers Portlet, the Register a Portlet Provider link is only valid for users who have at least the Publish privilege on All Providers.
• In the Providers Portlet, the browse link in the Edit a Portlet Provider section, returns the list portlets that the user has the privileges to edit. If the user has Edit privilege on All Providers then all providers are displayed in the list. Otherwise, only those providers that the user has at least Edit privilege on are displayed in the list.
• In the Providers Portlet, the Edit and Delete button in the Edit A Portlet Provider section is only valid for users who have either: at least the Edit privilege on All Providers, or at least Edit privilege on the specified provider.
• In the Edit Provider wizard, the Access tab is only displayed to users who have either: at least the Manage privilege on All Providers, or at least Manage privilege on the specified provider.

You can refresh the portlet repository by clicking the Refresh link in the portlet repository, or by running the wwpro_api_provider_registry.refresh_portlet_repository API.

When the portlet repository is refreshed, the following events take place:

• the portlet repository is updated
• the portlet metadata is updated
• pages containing updated portlets have their page caches invalidated.

When the portlet repository is refreshed, Oracle9iAS Portal performs the following functions:

• Updates the portlets in the portlet repository. The process of updating a provider in the portlet repository involves creating portlet items for each new portlet along with the portlet translations. The steps in this process are:
• Get a list of the providers by calling wwpro_api_provider_registry.get_provider_list.
• For each provider:
• Get a list of the languages installed in Oracle9iAS Portal.
• For each language, get the provider's list of portlets by calling the wwpro_api_provider.get_portlet_list with the security parameter set to false. This in turn calls the provider to return its list of portlets in the specified language. For database providers, this call is the get_portlet_list API. For Web providers, this call is the oracle.portal.provider.v2.ProviderInstance.getPortletDefinitions() method.
• For each new portlet record returned, create the portlet item or its translation. The items are created using the portlet names and descriptions. These portlets are created under the general category and do not have portlet item security turned on. For usability, provider portlet items that represent portlets no longer supported by the provider are not removed. These portlets are not displayed in the Portal pages, but the Edit/Customize page shows an error message for these portlets. In this way portlets do not mysteriously disappear from pages. It is the responsibility of the administrator to remove such portlets.
• For each new portlet record returned, create the portlet record metadata.
• For the provider, invalidate the page cache of any page containing the provider's portlets.
• Captures exceptions raised during the refresh process, in the Refresh Log. When a provider raises an exception during a call to get_portlet_list, the provider framework captures the exception and raises the exception HTTP_PROV_EXEC_EXCEPTION, which in turn is captured by the portlet repository code and recorded in the Refresh Log. The portlet repository recovers from the exception and continues. The Refresh Log can be viewed by clicking the Refresh Log link in the portlet repository.

When the portlet repository is displayed, the following events take place:

• Oracle9iAS Portal determines which portlets you (the currently logged in user) has the right to view
• the appropriate portlet items are displayed.

• Determines whether the user has the rights to view the portlet repository folder. If so, it continues checking other security levels, otherwise neither the folder, or its portlet items are displayed.
• For each portlet in the portlet repository folder, checks whether the portlet item has set portlet security:
• If the portlet item does not have portlet security set, Oracle9iAS Portal checks the value of the portlet's call_is_runnable flag. If the flag is false, it means that the provider has indicated that this is a public portlet and the portlet item is displayed. If the flag is true, the provider is contacted to determine if the user can view the portlet item. For database providers, this call is the is_portlet_runnableAPI. For Web providers, this call is the oracle.portal.provider.v2.PortletDefinition.hasAccess() method. Oracle9iAS Portal determines the value of the call_is_runnable flag using the stored portlet metadata.
• If the portlet item has set security then Oracle9iAS Portal checks that the user has at least Access privilege on Any Portlet, or has at least Access privilege on the portlet item. If the user does not have the privilege then the portlet item is not rendered. If the user does have the privilege then Oracle9iAS Portal checks the value of the portlets call_is_runnable flag. If the flag is false, it means that the provider has indicated that this is a public portlet and the portlet item is displayed. If the flag is true, Oracle9iAS Portal contacts the provider to determine if the user can view the portlet item. For database providers, this call is the is_portlet_runnable API. For Web providers, this call is the oracle.portal.provider.v2.PortletDefinition.hasAccess() method when the DefaultPortletDefinition is used. If a security manager has been defined then the hasAccess() method of the portlet's security manager (oracle.portal.provider.v2.security.PortletSecurityManager) is called. Oracle9iAS Portal determines the value of the call_is_runnable flag using the stored portlet metadata.

When you edit or customize an Oracle9iAS Portal page, the following events take place:

• privileges necessary to view the portlet are determined
• the display title for the portlet is determined.

When the Edit or Customization screens are displayed, Oracle9iAS Portal performs these security checks for each portlet:

• Oracle9iAS Portal has a mechanism for allowing Portal administrators to secure portlets. Portal administrators can secure portlets via portlet items in the portlet repository. They do so by updating the privileges associated with a portlet item using the portlet item's access tab. There are two privileges associated with a portlet item: Manage and Access. If a user does not have Access privilege on a portlet item then Oracle9iAS Portal secures the portlet. When a portlet is secured from a user, the user does not see the portlet in:
• Portal pages
• Portlet repository
• Edit screens
• Customization screens
The Manage privilege is the same as the Access privilege, except that it also allows a user to update the privileges associated with a portlet item. By default, portlet items are not secured. There are two global privileges for portlet items: Manage and Access. The Manage and Access privileges are the same as the portlet item's Manage and Access privileges respectively, except that they apply to all portlets. These global privileges can be set in the Privileges tab of the Edit Portal User Profile screen. The privileges are located in this screen in the Page Privileges section under the All Portlets object type.

When the Edit or Customize screen is displayed, Oracle9iAS Portal checks to see if the portlet item associated with the portlet has security set. If it does, it determines whether the user can view the portlet. If the user has the appropriate privilege, or if the portlet item does not have security set, then Oracle9iAS Portal attempts to render the portlet.

• The provider may also implement security, so the next security check is at the provider level. Oracle9iAS Portal checks the portlet's call_get_portlet flag to determine whether to call the provider to get the portlet title. If the provider has set the value of this flag to false, it indicates that the portlet metadata is public and is not user dependent. In this case, Oracle9iAS Portal displays the portlet title using the title stored in the portlet metadata repository. If the provider sets the value of this flag to true, then Oracle9iAS Portal contacts the provider for the portlet information.

For database providers, this call is the get_portletAPI. For Web providers, this call is the oracle.portal.provider.v2.ProviderInstance.getPortletDefinition() method. At this point, when the provider is called, if the provider determines that the user does not have the privileges to view the portlet then the provider raises a security exception. For database providers, this exception is wwpro_api_provide.portlet_security_exception. For Web providers, this exception is assumed when the provider returns null for the getPortlet method. When Oracle9iAS Portal encounters a portlet security exception then it does not display the portlet or an error. All other exceptions cause an error message to be displayed in the Edit/Customization screens for the portlet.

When you add a portlet to a page, the following events take place:

• privileges necessary to view the portlet are determined
• the display title for the portlet is determined.

• Performs the security checks detailed in the section Displaying the Portlet Repository, as the display of available portlets is in fact, the rendering of a portlet repository folder.
• Performs the security checks detailed in the section Adding a Portlet to a Page - Edit/Customization Screen, as the display of selected portlets follows the same process as that involved in displaying portlets in the Edit/Customization screens.

When Oracle9iAS Portal renders a Portal page, the following events take place:

• privileges necessary to view the portlet are determined
• the provider is called to render the portlet.

• Checks if the portlet item associated with the portlet instance has security set.
• If security is set, determines whether the user has at least Access privilege on Any Portlet, or at least Access privilege on the portlet item.
• If user has the appropriate privilege or if the portlet item does not have security set, contacts the provider to render the portlet.

• Depending on the provider's login frequency value, calls the provider's login method. For database providers, this call is the do_login API. For Web providers, this call is the oracle.portal.provider.v2.ProviderInstance.initSession() method.
• Calls the provider to render the portlet. For database providers, this call is the show_portlet API. For Web providers, this call is the oracle.portal.provider.v2.PortletInstance.render() method. If you are declaring your provider using a provider definition file (provider.xml), then the call to PortletInstance.render() is forwarded to the PortletRenderer, such as RenderManager, you declared in your provider definition file.

When you remove a portlet from an Oracle9iAS Portal page, the following events take place:

• provider is called to remove customizations relating to the portlet
• provider performs other necessary cleanup work.

• Calls the provider's deregister portlet function so that the provider can perform the necessary tasks in order to cleanup customizations related to the portlet instance. For database providers, this call is the deregister_portlet API. For Web providers, this call is the oracle.portal.provider.v2.PortletInstance.deregister() method.

When you deregister a provider, the following events take place:

• provider metadata is removed
• portlet metadata is removed
• pages containing the provider's portlets, have those portlets removed and their page caches are invalidated
• provider's portlets are removed from the portlet repository.

• Makes a call to the provider's deregister provider method. For database providers, this is the provider's deregister_provider API. For Web providers, this is the oracle.portal.provider.v2.ProviderInstance.deregister(). The oracle.portal.provider.v2.ProviderInstance.deregister() in turn calls oracle.portal.provider.v2.PortletDefinition.deregister() for each portlet to remove all customization data for the provider instance/portlet method.
• Removes the provider metadata.
• Removes the portlet metadata.
• Removes all portlet instances for the provider and invalidates the page cache for any page containing the provider's portlets.
• Removes the provider's portlets from the portlet repository. Since portlet items can be reorganized within the portlet repository, the provider folder is not removed.

When a provider is taken offline, the following events take place:

• provider metadata is updated to indicate that the provider is offline
• portlet metadata is updated to indicate that the provider of the portlet is offline
• pages containing the provider's portlets are invalidated

• Updates the provider metadata.
• Updates the portlet metadata for all the portlets of the provider.
• Invalidates the page cache for any Portal page containing any of the provider's portlets.
• Does not contact the provider for any calls including the call to initialize provider's session.
• For Oracle9iAS Portal pages and Edit /Customize screens either of the following is displayed in the provider's portlet:
• The default or custom offline message in the provider's portlet. The display is based on whether the 'Display default message' or 'Display custom offline message' option is selected in the Global Settings page.
• Nothing is displayed if the 'Do not display offline message' option is selected in the Global Settings page.
• For Add Portlet screens, nothing is displayed for the provider  under 'Available Portlets'. Nothing is displayed in the portlet under 'Selected Portlets' if the portlet's provider is offline.
• In the Portlet Repository the provider and the portlet items are displayed even if the provider is offline. This is to allow the administrators to rearrange and categorize the items.

Revision History:

• January, 2002