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

Last Update: | September 24, 2002
Status: | Production
Version: | Any PDK Release

## 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;`

#### do_login

The do_login method allows a provider to peform provider level initialization before any portlets from this provider are displayed. One such initialization that the provider may do is to generate an application cookie for its own use. This may be particulary useful when integrating existing web based applications that generate their own cookies.
This method accepts the data structure wwpro_api_provider.cookie_table as an input parameter. This contains all the cookies in the current HTTP request which have been received by portal. The same data structure is returned by the provider as an output parameter and it contains the cookies that have been created by the provider. Refer to the PL/SQL API Reference for a full description of this data structure.
It is only during this method that the cookies created by the provider will be processed by portal and sent to the browser. The provider cannot create cookies in any of the other methods.

`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;`

#### get_api_version

The get_api_version method is used to indicate the API version of the provider's implementation. For Oracle Portal 3.0, providers must return wwpro_api_provider.API_VERSION_1.

#### register_provider

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

Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065, USA http://www.oracle.com/ | Worldwide Inquiries: 1-800-ORACLE1 Fax 650.506.7200 | Copyright and Corporate Info