Oracle9iAS Portal Developer Kit (PDK)
An Overview of Writing Portlets for Database Providers

Introduction

In the Oracle9iAS Portal architecture a provider is an entity that is used as a container of portlets.

The provider serves as the communication link between portal and the provider's portlets.  Portal communicates with the provider and in turn the provider communicates with its portlets.  Portal never talks to a portlet directly, this communication is always done through the provider in which it is contained.  Providers abstract the actual implementation of portlets from the portal, allowing for a simpler portal architecture.

There are two main types of provider interfaces - Database and Web.  This article describes Database Providers, their architecture, and how they are implemented.

Portlet Overview

The portlet is PL/SQL or Java code stored in the database server.  Your portlet may reference the framework services or make calls to other database objects including tables and procedures.  The portlet may also just display static information.

To create a portlet, you simply write the code to display information.  For example, you would write a procedure to display the body of the portlet and would reference that in the show method (mode = MODE_SHOW).  You would also write procedures for each display mode you wish to use for your portlet.  For instance, if you have four display modes for the portlet you should write four procedures and also reference them in the show method.

The portlet is the code to display information for each display mode.  The provider handles all the work for the portlet, it stores the portlet information and handles execution by passing the required information to the Portal.

Provider Architecture

A database provider is one that must conform to a well defined PL/SQL API that portal requires.  This API is called the Database Provider API.  It consists of a number of methods that portal uses to communicate with the provider.

The provider should be implemented as a PL/SQL package that contains the methods defined by the Database Provider API.  This package should exist in a schema in the same database instance as the portal.

A provider may contain one or more portlets, there is no limit on the number of portlets a provider may contain.

Database Provider API

As indicated above the provider implementation package should conform to the Database Provider API by implementing a number of methods in its implementation package.  The following is a list of all of these methods:

• get_api_version
• register_provider
• deregister_provider
• do_login
• get_portlet
• get_portlet_list
• is_portlet_runnable
• register_portlet
• deregister_portlet
• show_portlet
• copy_portlet

These methods are used by the provider to retrieve information about or display its portlets.

The function of each of this methods is briefly described below.

show_portlet

The show_portlet method is used to render a portlet.  It should generate HTML or XML/XSL to be displayed.

This method accepts the data structure wwpro_api_provider.portlet_runtime_record which contains information about the execution of the portlet.  Refer to the PL/SQL API Reference for a full description of this data structure.

This method has several modes in which it may be executed.  These are called the Show Modes of a portlet and they are described in the table below.

Show Mode	Description
show	Displays the content body of a portlet.
edit	Displays the customization page for a portlet.
help	Displays the help page of a portlet.  Customization must be used specific.
about	Displays the about page that contains information about the portlet.
details	Displays the portlet in a full browser window.
edit defaults	Displays the edit defaults page for a portet.
preview	Displays the preview of a portlet.
link	If the portlet is mobile enabled this is the text that is displayed for the portlet in a mobile device.

Example
 

procedure show_portlet(     p_portlet_record in out portlet_runtime_record ) is      ... begin     if p_portlet_record.mode = wwpro_api_provider.MODE_SHOW then         display_show_mode(p_portlet_record);     elsif p_portlet_record.mode = wwpro_api_provider.MODE_SHOW_ABOUT then         display_show_about(p_portlet_record);     elsif p_portlet_record.mode = wwpro_api_provider.MODE_SHOW_EDIT then         display_show_edit(p_portlet_record);     elsif p_portlet_record.mode = wwpro_api_provider.MODE_SHOW_HELP then         display_show_help(p_portlet_record);     elsif p_portlet_record.mode = wwpro_api_provider.MODE_SHOW_EDIT_DEFAULTS then         display_show_edit_defaults(p_portlet_record);     elsif p_portlet_record.mode = wwpro_api_provider.MODE_SHOW_DETAILS then         display_show_details(p_portlet_record);     elsif p_portlet_record.mode = wwpro_api_provider.MODE_PREVIEW then         display_show_preview(p_portlet_record);     elsif p_portlet_record.mode = wwpro_api_provider.MODE_LINK then         display_show_preview(p_portlet_record);     else         raise wwpro_api_provider.PORTLET_EXECUTION_EXCEPTION;     end if; end show_portlet; ... procedure display_show_mode(     p_portlet_record p_portlet_runtime_record ) is begin     htp.p('This is the show mode of this sample portlet'); end display_show_mode;

procedure do_login(     p_provider_id in integer     p_browser_cookies in wwpro_api_provider.cookie_table     p_provider_cookies out wwpro_api_provider.cookie_table ) is begin     -- Create application cookie 1.     p_provider_cookies(1).cookie_name := 'cookie1';     p_provider_cookies(1).cookie_content := 'content1';     -- Create application cookie 2.     p_provider_cookies(2).cookie_name := 'cookie2';     p_provider_cookies(2).cookie_content := 'content2'; end do_login;

get_portlet

The get_portlet method is used to deliver information about the portlet to the portal.  This information includes such elements as the name, title, ID, description, etc.  This information is communicated to the portal via the data structure wwpro_api_provider.portlet_record.  Refer to the PL/SQL API Reference for a full description of this data structure.

Example

function get_portlet(     p_provider_id in integer,     p_portlet_id in integer,     p_language in varchar2 ) return wwpro_api_provider.portlet_record is     l_portlet wwpro_api_provider.portlet_record; begin     if (p_portlet_id = starter_provider.PORTLET_HELLOWORLD) then         l_portlet.id := starter_provider.PORTLET_HELLOWORLD;         l_portlet.provider_id := p_provider_id;         l_portlet.title := 'Hello World';         l_portlet.name := 'Hello_World';         l_portlet.description :=             'This portlet displays the hello world string';         l_portlet.timeout := null;         l_portlet.timeout_msg := null;         l_portlet.language := 'us';         l_portlet.has_show_edit := true;         l_portlet.has_show_edit_defaults := true;         l_portlet.has_show_preview := true;         l_portlet.content_type := wwpro_api_provider.CONTENT_TYPE_HTML;         l_portlet.preference_store_path := null;         l_portlet.created_on := sysdate;         l_portlet.created_by := wwctx_api.get_user;         l_portlet.last_updated_on := sysdate;         l_portlet.last_updated_by := wwctx_api.get_user;     end if;     return l_portlet; end get_portlet;

get_portlet_list

The get_portlet_list method returns the list of portlets that the provider implements and are available to the user.  This method is called by portal during the registration of the provider and also during provider refresh in order to obtain information about the provider's portlets.

This method returns the list of portlets in a wwpro_api_provider.portlet_table data structure.  Refer to the PL/SQL API Reference for a full description of this data structure.

function get_portlet_list(     p_provider_id in integer,     p_start_row in integer,     p_rowcount in integer,     p_language in varchar2,     p_security_level in boolean,     p_type in integer ) return wwpro_api_provider.portlet_table is     l_portlet_list  wwpro_api_provider.portlet_table;     l_cnt   number; begin     l_cnt := 0;     if (p_security_level = false ) then         l_cnt := l_cnt + 1;         l_portlet_list(l_cnt) := get_portlet(             p_provider_id  => p_provider_id,             p_portlet_id   => PORTLET_HELLOWORLD,             p_language     => p_language,         );         l_cnt := l_cnt + 1;         l_portlet_list(l_cnt) := get_portlet(             p_provider_id  => p_provider_id             p_portlet_id   => PORTLET_SNOOP             p_language     => p_language         );     else         ... end get_portlet_list;

The register_provider method is called when the provider is registered with the portal.  It allows the provider to do provider-level initializations.

deregister_provider

The deregister_provider method is called when the provider deregistered with the portal.  It allows the provider to do provider-level cleanup.

is_portlet_runnable

The is_portlet_runnable method is used to determine if the currently logged on user has sufficient privileges to access a portlet.

register_portlet

The register_portlet method is called every time a portlet is added to a page.  This procedure gives the portlet a chance to perform instance-level initialization, such as establishing defaults for end-user customization, before the portlet is displayed.

deregister_portlet

The deregister_portlet method is called when a portlet instance is removed from a page.  This procedure gives the portlet a chance to perform instance-level cleanup, such as the removal of end-user customizations.

copy_portlet

The copy_portlet method is called when a page that contains the portlet is being copied.  It is used to copy a portlet's customization and default settings from a portlet instance to a new portlet instance.

Provider Creation Process

The following steps summarize the process of creating and deploying a database provider.  These steps are required by the developer of a provider to allow Oracle9iAS Portal to recognize the provider, register its portlets, and make them available for use in portal pages.

Step 1 - Create your provider

Create a package for the portlet provider.  You must implement all the methods defined by the Database Provider API.

Step 2 - Build your Show Modes

Create a procedure for each display mode of the portlet.  To simplify matters, you may want to place all the procedures in a single PL/SQL package.

Step 3 - Store your packages

Create a schema to store the PL/SQL packages.  You should not place your packages in the Portal schema.

Step 4 - Register your provider

Register the provider with Oracle9iAS Portal. This registration is required to make the provider and its portlets visible to the users of the portal.  A provider can be registered programmatically through SQL*Plus (using the wwpro_api_provider_registry.register_provider API) or it can be registered through the Oracle9iAS Portal user interface (Portal Design Time Pages -> Build Tab -> Providers portlet -> Register a portlet provider).

Once you have registered the provider, the new provider and it's portlets are added to the portlet repository. The portlet repository stores information in the portal for the providers and a list of portlets that the provider owns. '

Step 5 - Add the portlet to a Portal page

You are now ready to add you portlets to a portal page.

Revision History:

Revision No Last Update 1.0 July 21, 2002 2.0 Sep 24, 2002