Package wwpro_api_provider

This package contains procedures and functions to register, edit, and retrieve providers.

Database providers can be implemented as PL/SQL packages. The packages need a specific set of procedures and functions in their implementation. The name of the package is flexible since the framework uses the physical implementation name that is specified during provider registration.

To create a database provider:

1. If you intend to store the provider in its own schema, create a schema to hold the provider.
2. If the provider is implemented in a schema other than that of OracleAS Portal 10G, run the script provsyns.sql.
   Note that provsyns.sql is on your OracleAS Portal 10G CD. Instructions for running the script are contained in this file.
3. Create a package that implements a provider with the following procedures and functions:
• get_portlet function
• get_portlet_list function
• get_api_version function
• do_login procedure
• show_portlet procedure
• is_portlet_runnable function
• register_portlet procedure
• copy_portlet procedure
• deregister_portlet procedure
• describe_portlet_parameters function
• register_provider procedure
• deregister_provider procedure
There are several sample portlets in the PDK that show how these procedures and functions should be implemented.
4. Register the portlet provider with OracleAS Portal 10G. To do this, use the Register a Provider link in the Remote Providers portlet.

A portlet is an entity that can produce output in HTML or XML/XSL. Portlets form the fundamental building blocks of a portal page. Each portal page consists of content presented through one or more portlets and links that allow the user to navigate to another page to take some action.

Portlets communicate with the portal through an entity called a provider. The provider ID uniquely identifies a provider with the portal. The portlet ID uniquely identifies the portlet within the provider. It is the responsibility of the provider to ensure that each portlet has a unique portlet ID. It is only the combination of provider ID and portlet ID that uniquely identifies a particular portlet.

Scope:

Public

Since:

Oracle9iAS Portal 3.0.6.6.5

ADD_PORTLET_EXCEPTION

ADD_PORTLET_EXCEPTION exception

An error occurred while attempting to add a portlet.

DELETE_PORTLET_EXCEPTION

DELETE_PORTLET_EXCEPTION exception

An error occurred while attempting to delete a portlet.

NODE_NOTCOMMONSSO_EXCEPTION

NODE_NOTCOMMONSSO_EXCEPTION exception

The SSO server used by the remote node is not the same as the SSO server used by the local node.

PORTLET_EXECUTION_EXCEPTION

PORTLET_EXECUTION_EXCEPTION exception

An error occurred while attempting to execute a portlet.

PORTLET_GENERAL_EXCEPTION

PORTLET_GENERAL_EXCEPTION exception

An unexpected error occurred while attempting to execute a portlet.

PORTLET_NOT_FOUND_EXCEPTION

PORTLET_NOT_FOUND_EXCEPTION exception

The provider could not find the specified portlet.

PORTLET_OFFLINE_EXCEPTION

PORTLET_OFFLINE_EXCEPTION exception

The provider which the portlet belongs to is currently offline.

PORTLET_PARAMETER_EXCEPTION

PORTLET_PARAMETER_EXCEPTION exception

An error occurred during the call to the provider's describe_portlet_parameters function.

PORTLET_SECURITY_EXCEPTION

PORTLET_SECURITY_EXCEPTION exception

The user does not have the appropriate privileges to run the portlet.

PORTLET_VALIDATION_EXCEPTION

PORTLET_VALIDATION_EXCEPTION exception

The provider gave invalid information for the portlet.

PROVIDER_CALLAPIV_EXCEPTION

PROVIDER_CALLAPIV_EXCEPTION exception

An error occurred during the call to the get_api_version function.

PROVIDER_CALLDEREG_EXCEPTION

PROVIDER_CALLDEREG_EXCEPTION exception

An error occurred during the call to the deregister function.

PROVIDER_CALLREG_EXCEPTION

PROVIDER_CALLREG_EXCEPTION exception

An error occurred during the call to the register function.

PROVIDER_EXECUTION_EXCEPTION

PROVIDER_EXECUTION_EXCEPTION exception

An unexpected error occurred while executing the requested provider or API.

PROVIDER_NOT_FOUND_EXCEPTION

PROVIDER_NOT_FOUND_EXCEPTION exception

The specified provider cannot be located.

PROVIDER_NOT_LOCAL_EXCEPTION

PROVIDER_NOT_LOCAL_EXCEPTION exception

The API cannot be executed on providers that are not on the local node.

PROVIDER_NOTDELETE_EXCEPTION

PROVIDER_NOTDELETE_EXCEPTION exception

A call is attempting to delete a provider that is not allowed to be deleted.

PROVIDER_REGISTRTN_EXCEPTION

PROVIDER_REGISTRTN_EXCEPTION exception

An unexpected error occurred while attempting to register the provider.

PROVIDER_REMOVAL_EXCEPTION

PROVIDER_REMOVAL_EXCEPTION exception

An error occurred during the deletion of a provider.

PROVIDER_RETRIEVAL_EXCEPTION

PROVIDER_RETRIEVAL_EXCEPTION exception

The API failed to communicate with the provider.

PROVIDER_SECURITY_EXCEPTION

PROVIDER_SECURITY_EXCEPTION exception

The user does not have the appropriate privileges to run the API.

PROVIDER_VALIDATION_EXCEPTION

PROVIDER_VALIDATION_EXCEPTION exception

The call to the API contained invalid information about the provider.

REFRESH_REPOSITORY_EXCEPTION

REFRESH_REPOSITORY_EXCEPTION exception

An error occurred while attempting to refresh the portlet repository.

cookie_record

type cookie_record is record (
    cookie_name varchar2(4096),
    cookie_content varchar2(4096),
    cookie_domain varchar2(200),
    cookie_path varchar2(200),
    cookie_expires date,
    cookie_update boolean,
    provider_id integer
)

A record structure containing the cookie details provided during login.

A cookie is a set of data that a Web site sends to a browser when a user visits the site.

Fields:

cookie_name - the name of the cookie

cookie_content - the value or content of the cookie

cookie_domain - the domain for which the cookie was created

cookie_path - the URL path within which the cookie is valid

cookie_expires - the date and time that the cookie expires

cookie_update - for internal use only

provider_id - for internal use only

Since:

Oracle Portal 3.0.6.6.5

cookie_table

type cookie_table is table of cookie_record index by binary_integer

A table structure containing the list of cookies.

Since:

Oracle Portal 3.0.6.6.5

copy_portlet_record

type copy_portlet_record is record (
    provider_id number,
    portlet_id number,
    srcreferencepath varchar2(100),
    dstreferencepath varchar2(100)
)

A record structure containing the details necessary to copy customization information from one portlet instance to a new portlet instance. A copy_portlet record structure is passed to wwpro_api_provider.copy_portlet. The provider can use this information to copy system-level customizations.

Fields:

provider_id - a unique identifier used to locate the provider

portlet_id - a unique identifier used to locate the portlet in the provider domain

srcReferencePath - the portlet instance ID that identifies the source portlet instance. It is the unique reference for a portlet in a page. This parameter can be used to retrieve instance-specific information for the portlet.

dstReferencePath - the portlet instance ID that identifies the destination portlet instance. It is the unique reference for a portlet placed in a page. This parameter can be used to store instance-specific information for the portlet.

portlet_instance_record

type portlet_instance_record is record (
    provider_id number,
    portlet_id number,
    reference_path varchar2(100),
    page_type varchar2(200)
)

A record structure containing the details for a portlet instance.

A portlet_instance_record structure is passed into these provider implementation procedures:

• is_portlet_runnable
• register_portlet
• deregister_portlet

A portlet instance is the display of a portlet on a single page. The same portlet may be displayed multiple times on the same page. Each time a portlet is added to a page, OracleAS Portal 10G generates a unique portlet instance ID that is the instance's reference path.

Fields:

provider_id - a unique identifier used to locate the provider

portlet_id - a unique identifier used to locate the portlet in the provider domain

reference_path - identifies the portlet instance being called. The portlet reference path specifies a unique identifier for a portlet instance on a page. This parameter can be used to store and retrieve instance specific information for the portlet.

page_type - for internal use only

Since:

Oracle Portal 3.0.6.6.5

portlet_parameter_record

type portlet_parameter_record is record (
    name varchar2(30),
    datatype varchar2(30) default STRING_TYPE,
    usage_type varchar2(30) default PORTLET_PARM_PARAMETER,
    description varchar2(200),
    display_name varchar2(80),
    language varchar2(30)
)

A record structure containing details of one parameter for a portlet in a specified language.

Fields:

name - the portlet parameter name

datatype - one of five data type constants:

• STRING
• NUMBER
• INTEGER
• CURRENCY
• DATE

Not used in Oracle9iAS Portal 9.0.2 or later.

usage_type - an indicator for the intended use of the parameter.

• portlet_parm_parameter
• portlet_parm_display
• portlet_parm_dataitem

This value is defined and used by portlet providers. Not used in Oracle9iAS Portal 9.0.2 or later.

description - a short description for the parameter

display_name - a name/title for the parameter to be displayed in the UI

language - the language in which the portlet instance is called, for example, 'AMERICAN'

Since:

Oracle Portal 3.0.6.6.5

portlet_parameter_table

type portlet_parameter_table is table of portlet_parameter_record index by binary_integer

A table structure containing descriptions of all the parameters of a portlet.

Since:

Oracle Portal 3.0.6.6.5

portlet_record

type portlet_record is record (
    id integer,
    provider_id integer,
    name varchar2(240),
    title varchar2(200),
    short_title varchar2(80),
    description varchar2(200),
    image_url varchar2(1024),
    thumbnail_image_url varchar2(1024),
    help_url varchar2(1024),
    timeout integer,
    timeout_msg varchar2(200),
    implementation_style integer,
    implementation_owner varchar2(2000),
    implementation_name varchar2(2000),
    content_type integer,
    api_version integer,
    has_show_edit boolean,
    has_show_edit_defaults boolean,
    has_show_preview boolean,
    call_is_runnable boolean,
    call_get_portlet boolean,
    accept_content_type varchar2(2000),
    has_show_link_mode boolean,
    mobile_only boolean,
    show_behaviour_style integer,
    language varchar2(30),
    preference_store_path varchar2(2000),
    created_on date,
    created_by varchar2(256),
    last_updated_on date,
    last_updated_by varchar2(256),
    pass_all_url_params boolean,
    cache_level integer,
    rewrite_urls boolean
)

A record structure containing detailed information about a portlet.

This contains all of the details of the portlet and, for the NLS property timeout_msg, it includes both the NLS IDs and the actual translated strings (in the language requested).

A portlet provider is required to return a portlet_record or a portlet_table when either get_portlet or get_portlet_list is called.

The provider should fill in this structure with the details of portlet. Note that the provider_id parameter will be filled in by the framework during registration.

Fields:

id - a unique identifier used to locate the portlet in the provider domain. A null value is not permitted.

provider_id - the ID of the provider that implements the portlet

name - a unique identifier used to locate the portlet in the provider domain. The name should not contain any spaces. A null value is not permitted.

title - the title string displayed when the portlet is displayed. This is the same as the title returned when the list of portlets is requested. The description returned is responsive to the language parameter used when obtaining the wwpro_api_provider.portlet_record. A null value is not permitted.

short_title - a shorter version of the title (above). A maximum of 80 characters is allowed. If this parameter is not set the long title is used instead. This field is available with Oracle9iAS Portal version 9.0.2 or later.

description - a short description of the portlet. This description is sensitive to the language parameter used when obtaining the wwpro_api_provider.portlet_record. This description may be used when a list of portlets is requested. A null value is not permitted.

image_url - this field is not used by Oracle Portal 3.0 or later

help_url - this field is not used by Oracle Portal 3.0 or later

thumbnail_image_url - this field is not used by Oracle Portal 3.0 or later

timeout - the number of seconds that should be spent attempting to execute the portlet before a timeout operation occurs. This property is only used when the portlet is executed directly inside OracleAS Portal 10G. A null value indicates to use the timeout value of the provider.

timeout_msg - the message string to be presented when an execution timeout occurs. The timeout message may not contain mobile (mobileMXL) or desktop (HTML) markup. A null value indicates that the timeout message of the provider should be used.

implementation_style - this field is not used by Oracle Portal 3.0 or later

implementation_owner - this field is not used by Oracle Portal 3.0 or later

implementation_name - this field is not used by Oracle Portal 3.0 or later

content_type - the type of data the portlet produces, i.e. one of:

• wwpro_api_provider.CONTENT_TYPE_HTML
• wwpro_api_provider.CONTENT_TYPE_XML
• wwpro_api_provider.CONTENT_TYPE_MOBILE

or a combination of the above (by adding any of the above together). This field is now deprecated.

api_version - the version of the API to which the portlet conforms. At present , this value must be wwpro_api_provider.API_VERSION_1.

has_show_edit - indicates if the portlet implements an Edit (or Customize) page. See show_portlet procedure.

has_show_edit_defaults - indicates if the portlet implements an Edit Defaults page that can be used by administrators to establish default display options for all users. See show_portlet procedure.

has_show_preview - indicates if the portlet implements a Preview portlet, i.e. one that can be viewed from the Add Portlet screen and the Portlet Repository. See show_portlet procedure. This field is available with Oracle Portal version 3.0.9 or later.

call_is_runnable - indicates whether the portal must make calls to the provider's is_portlet_runnable function for the portlet. The provider's is_portlet_runnable function is called prior to displaying a portlet in the Portlet Repository. For a public portlet this function will always return true so there is no need to contact the provider. In this case the provider should set the value for call_is_runnable to false so that the provider's is_portlet_runnable function is not called. The default for this flag is true. This field is available with Oracle Portal version 3.0.9 or later.

call_get_portlet - indicates whether the portal can use the portlet record data stored in the Portlet Metadata Repository (PMR) instead of contacting the provider for the portlet record. If the portlet record (specified by provider id, portlet id, and language) returned by a provider does not change, then the provider should set the value for call_get_portlet to false. This tells the portal to use the PMR instead of making calls to the provider's get_portlet and get_portlet_list functions. An example of when a provider would not want the portal to use portlet metadata from the PMR, is when the value of the portlet records is different for logged on users. The default for this flag is true. This field is available with Oracle Portal version 3.0.9 or later.

accept_content_type - this is a comma delimited list of content_types whose values are the types of content that the portlet produces. For example, if a portlet can produce both HTML and MOBILEXML the string would be: 'text/html,text/vnd.oracle.mobilexml'. This field is available with Oracle Portal version 3.0.9 or later.

has_show_link_mode - this portlet implements show Link mode. If the value is FALSE, the portlet uses its short or full title to display a link label that references the portlet content in a mobile device. Otherwise, a customized link can be generated in the portlet code. Portal version 3.0.9 or later.

mobile_only - indicates whether the portlet is available only to mobile devices. If set to true, the portlet is only available for mobile devices, i.e. it cannot be added to standard Web pages. If set to false (default) the portlet can be displayed on both Web pages and mobile devices (if the portlet can produce at least mobilexml). This field is available with Oracle9iAS Portal version 9.0.2 or later.

show_behaviour_style - set to one of the SHOW behavior style constants. Currently, the only one defined is EXTERNAL_PORTLET. When set to EXTERNAL_PORTLET (1) this indicates that the mobile portlet's SHOW mode links outside of OracleAS Portal 10G, to a different location. This can be used in mobile devices for existing OracleiAS Wireless applications that have not been fully converted to portlets. Only the LINK mode needs to be implemented, specifying the URL for the actual portlet content without going via OracleAS Portal 10G. Although this is not recommended, it does allow current OracleAS Wireless 10G applications to be integrated with Oracle Portal with minimum effort. Normally this parameter is set to 0 to indicate normal operation, i.e. that the mobile portlet has a SHOW mode. This field is available with Oracle9iAS Portal version 9.0.2 or later.

language - the language in which the strings are returned. A null value is not permitted.

preference_store_path - the base preference store path where the provider has stored the portlet customization information. This path is used when exporting portlets. When exporting a page, the reference path for the portlet is appended to the preference_store_path to reconstruct the preference path for portlet customizations. If the value of this field is null, no preference store data is exported.

created_on - the date the record was created

created_by - the user who created the record

last_updated_on - the most recent date the record was changed

last_updated_by - the user who most recently changed the record

pass_all_url_params - indicates parameter passing behavior in the portlet. If true, the portlet passes all parameters on the URL to the portlet (as per Oracle Portal 3.0.9). If false, the portlet is only passed parameters intended for that portlet. This is the default behavior in Oracle9iAS Portal 9.0.2 (V2 PDK-Java). The default value for database providers is true, since there is no V2 provider API. This field is available with Oracle9iAS Portal version 9.0.2 or later.

cache_level - indicates a portlet's cache level, one of the values null, wwpro_portlet_metadata.CACHE_LEVEL_SYSTEM, wwpro_portlet_metadata.CACHE_LEVEL_USER, wwpro_portlet_metadata.CACHE_LEVEL_PTL_SESSION

rewrite_urls - indicates whether or not URL rewriting will be performed on the output from a portlet render request

Since:

Oracle Portal 3.0.6.6.5

portlet_runtime_record

type portlet_runtime_record is record (
    portlet_id number,
    provider_id number,
    node_id number,
    reference_path varchar2(100),
    language varchar2(30),
    exec_mode number,
    back_page_url varchar2(32767),
    page_url varchar2(32767),
    refresh_url varchar2(32767),
    page_type varchar2(200),
    has_title_region boolean,
    has_border boolean,
    has_details boolean,
    has_edit boolean,
    has_help boolean,
    has_about boolean,
    has_remove boolean,
    has_collapse boolean,
    is_collapsed boolean,
    portlet_template varchar2(32767),
    caching_key varchar2(55),
    caching_level varchar2(30),
    caching_period number,
    caching_invalidation number
)

A record structure containing the details for a portlet during runtime.

A portlet_runtime_record structure is passed to the show_portlet procedure of provider implementations.

The provider should set the values for caching_key, caching_period, caching_level and caching_invalidation in the show_portlet procedure if caching is enabled for the portlet.

For the Shared Screen show mode in which the portlet shares the the portal page with other portlets, you should use page_url to return to the page from which you came and back_page_url is unnecessary in most cases. For customize, edit defaults, help, and about... modes, you should use page_url to redraw the customize, edit defaults, help, or about... pages and back_page_url to return to the page from which you came.

Fields:

portlet_id - a unique identifier used to locate the portlet in the provider domain

provider_id - a unique identifier used to locate the provider

node_id - the provider's host node ID

reference_path - the unique path (portlet instance ID) used to identify a portlet instance. This path information is used to store and retrieve instance-specific information for the portlet.

language - the language in which the portlet instance is called, for example, 'AMERICAN'

exec_mode - the mode in which the portlet is executed

back_page_url - the URL for the calling page. The value stored in this field is used by portlets to redirect users back to the calling page. The value can be null if there is no calling URL.

page_url - the URL of the page containing the portlet instance that will receive the portlet_runtime_record.

refresh_url - the URL for the calling page. The page is reloaded/built from the database, rather than from cache. This field is available with Oracle9iAS Portal 9.0.2 or later.

page_type - no longer used

has_title_region - determines whether a header is displayed for the portlet as a link

has_border - determines whether a border is displayed around the portlet

has_details - determines whether a title is drawn as a link for the portlet. The portlet eventually passes this to the header rendering routine by passing the entire portlet_runtime_record. This field is available with Oracle9iAS Portal 9.0.2 or later.

has_edit - determines whether a Customize link is displayed for the portlet

has_help - determines whether a Help link is displayed for the portlet

has_about - determines whether an About link is displayed for the portlet

has_remove - determines whether a Remove icon is displayed for the portlet. This field is available with Oracle9iAS Portal 9.0.2 or later.

has_collapse - determines whether a Collapse/Restore link is displayed for the portlet. This field is available with Oracle9iAS Portal version 9.0.2 or later.

is_collapsed - indicates whether the portlet content is collapsed. This field is available with Oracle9iAS Portal 9.0.2 or later.

portlet_template - a string, representing the HTML to render the portlet's custom header and footer. The format is as follows:
<header> #body# <footer>
This field is available with Oracle9iAS Portal 9.0.2 or later.

caching_key - a unique ID (set by the portlet) to indicate when the portlet content changes so the cache can be updated. For example, if the portlet has a version number and its content changes only between versions, then the version number could be included in the key. The mod_plsql uses the complete URL to determine the cache hit, therefore the caching key should not contain any values contained in the URL as part of its argument.

caching_level - indicates the level of caching that the portlet implements: SYSTEM or USER. It is set by the portlet and used for both caching by key and expiration based caching. With system-level caching, mod_plsql checks only the URL and the language setting for a cache hit. With user-level caching, mod_plsql checks the URL, language and user ID for a cache hit.

caching_period - the time in minutes before the cache expires. The value zero (0) indicates that the portlet should never be cached. If caching_period is specified, caching_key is ignored.

caching_invalidation - determines whether Web cache is used for invalidation. This field is available with Oracle9iAS Portal 9.0.2 or later.

Since:

Oracle Portal 3.0.6.6.5

portlet_table

type portlet_table is table of portlet_record index by binary_integer

A table structure containing a list of portlet_records. A portlet_table structure is returned after calling the portlet listing functions.

Since:

Oracle Portal 3.0.6.6.5

API_VERSION

API_VERSION constant integer := API_VERSION_1

The version of the API to which the portlet conforms.

API_VERSION_1

API_VERSION_1 constant integer := 1

Version 1 of the API.

CACHE_LEVEL_FIRST

CACHE_LEVEL_FIRST constant number := 0

CACHE_LEVEL_LAST

CACHE_LEVEL_LAST constant number := CACHE_LEVEL_PTL_SESSION

CACHE_LEVEL_PTL_SESSION

CACHE_LEVEL_PTL_SESSION constant number := 2

CACHE_LEVEL_SYSTEM

CACHE_LEVEL_SYSTEM constant number := CACHE_LEVEL_FIRST

CACHE_LEVEL_USER

CACHE_LEVEL_USER constant number := 1

CONTENT_TYPE_HTML

CONTENT_TYPE_HTML constant integer := 1

CONTENT_TYPE_MOBILE

CONTENT_TYPE_MOBILE constant integer := 4

CONTENT_TYPE_XML

CONTENT_TYPE_XML constant integer := 2

COOKIE_DELIMITER

COOKIE_DELIMITER constant varchar2(10) := '; '

Indicates cookie delimiter.

COOKIE_NAME_CONTENT_DELIMITER

COOKIE_NAME_CONTENT_DELIMITER constant varchar2(10) := '='

Indicates cookie content delimiter.

CURRENCY_TYPE

CURRENCY_TYPE constant varchar2(8) := 'CURRENCY'

DATE_TYPE

DATE_TYPE constant varchar2(4) := 'DATE'

EXTERNAL_PORTLET

EXTERNAL_PORTLET constant integer := 1

Indicates the SHOW behavior style to be EXTERNAL_PORTLET.

INTEGER_TYPE

INTEGER_TYPE constant varchar2(7) := 'INTEGER'

LIST_COMPONENT

LIST_COMPONENT constant integer := 2

Indicates the list type required when a portlet list is returned.

LIST_PORTLET

LIST_PORTLET constant integer := 1

Indicates the list type required when a portlet list is returned.

MODE_LINK

MODE_LINK constant integer := 8

MODE_PREVIEW

MODE_PREVIEW constant integer := 7

MODE_SHOW

MODE_SHOW constant integer := 1

MODE_SHOW_ABOUT

MODE_SHOW_ABOUT constant integer := 2

MODE_SHOW_DETAILS

MODE_SHOW_DETAILS constant integer := 6

MODE_SHOW_EDIT

MODE_SHOW_EDIT constant integer := 3

MODE_SHOW_EDIT_DEFAULTS

MODE_SHOW_EDIT_DEFAULTS constant integer := 5

MODE_SHOW_HELP

MODE_SHOW_HELP constant integer := 4

NO_INVALIDATION

NO_INVALIDATION constant integer := 0

Indicates no Web cache invalidation.

NUMBER_TYPE

NUMBER_TYPE constant varchar2(6) := 'NUMBER'

PORTLET_PARM_DATAITEM

PORTLET_PARM_DATAITEM constant varchar2(8) := 'DATAITEM'

PORTLET_PARM_DISPLAY

PORTLET_PARM_DISPLAY constant varchar2(11) := 'DISPLAYITEM'

PORTLET_PARM_PARAMETER

PORTLET_PARM_PARAMETER constant varchar2(9) := 'PARAMETER'

STRING_TYPE

STRING_TYPE constant varchar2(6) := 'STRING'

USE_INVALIDATION

USE_INVALIDATION constant integer := 1

Indicates Web cache invalidation used.

copy_portlet

procedure copy_portlet(
    p_copy_portlet_info in copy_portlet_record
) 

Copies a portlet's customization and default settings from a portlet instance to a new portlet instance.

Any user can use this procedure.

Notes:

The register_portlet procedure is called prior to this procedure.

A portlet instance is the display of a portlet on a single page. The same portlet may be displayed multiple times on the same page. Each time a portlet is added to a page, OracleAS Portal 10G generates a unique portlet instance ID that is the instance's reference path.

This procedure is called from the provider framework when a page containing the portlet is copied.

Example:

   example_provider.copy_portlet
   (
       p_copy_portlet_info => copy_portlet_record
   );
 

Parameters:

p_copy_portlet_info - specifies the information to be copied:

• provider_id
• portlet_id
• source path
• destination path

Exceptions:

PROVIDER_EXECUTION_EXCEPTION - if the provider cannot be executed

PROVIDER_VALIDATION_EXCEPTION - if invalid information about the provider is returned

PORTLET_EXECUTION_EXCEPTION - if there is a generic problem with the portlet that prevents the portlet from being executed

Since:

Oracle Portal 3.0.6.6.5

deregister_portlet

procedure deregister_portlet(
    p_portlet_instance in portlet_instance_record
) 

Allows a portlet to perform instance-level cleanup, such as the removal of end-user customizations.

Any user can use this procedure.

Notes:

An audit record is created each time this procedure is used.

It is the caller's responsibility to remove the provider schema, if necessary.

A portlet instance is the display of a portlet on a single page. The same portlet may be displayed multiple times on the same page. Each time a portlet is added to a page, OracleAS Portal 10G generates a unique portlet instance ID that is the instance's reference path.

This procedure is called from the provider framework when a portlet is removed from a page, or when a page containing the portlet is deleted.

Example:

Calling code:

   wwpro_api_provider.deregister_portlet
   (
       p_portlet_instance => portlet_instance_rec
   );
 

Provider call:

   example_provider.deregister_portlet
   (
       p_portlet_instance => portlet_instance_rec
   );
 

Parameters:

p_portlet_instance - a record containing the properties of a portlet instance

Exceptions:

PROVIDER_NOT_FOUND_EXCEPTION - if provider cannot be located

PROVIDER_EXECUTION_EXCEPTION - if provider cannot be executed

PROVIDER_SECURITY_EXCEPTION - if provider does not allow the user to run it

PORTLET_VALIDATION_EXCEPTION - if provider has given invalid information about the portlet

PORTLET_SECURITY_EXCEPTION - if the portlet does not allow the user to run it

PORTLET_EXECUTION_EXCEPTION - if there is a generic problem with the portlet that prevents the portlet from being executed

Since:

Oracle Portal 3.0.6.6.5

deregister_provider

procedure deregister_provider(
    p_provider_id in integer
) 

Deregisters a provider. OracleAS Portal 10G calls this procedure when a provider is deregistered, via either the OracleAS Portal 10G UI or APIs. The deregister_provider procedure lets the provider do provider-level cleanup.

Any user can use this procedure.

Example:

Calling code:

   wwpro_api_provider.deregister_provider
   (
       p_provider_id => 1348
   );
 

Provider call:

   provider_owner.example_provider.deregister_provider
   (
       p_provider_id => 1348
   );
 

Parameters:

p_provider_id - a unique identifier for the provider

Exceptions:

PROVIDER_VALIDATION_EXCEPTION - if invalid information about the provider is returned

PROVIDER_NOT_FOUND_EXCEPTION - if provider cannot be located

PROVIDER_EXECUTION_EXCEPTION - if provider cannot be executed

PROVIDER_SECURITY_EXCEPTION - if provider does not allow the user to run it

PORTLET_VALIDATION_EXCEPTION - if provider has given invalid information about the portlet

PORTLET_SECURITY_EXCEPTION - if user does not have correct privileges to run the portlet

PORTLET_EXECUTION_EXCEPTION - if there is a generic problem with the portlet that prevents the portlet from being executed

Since:

Oracle Portal 3.0.6.6.5

describe_portlet_parameters

function describe_portlet_parameters(
    p_provider_id in integer,
    p_portlet_id in integer,
    p_language in varchar2
) return portlet_parameter_table

Returns the portlet parameter table. OracleAS Portal 10G calls this function when it needs to know the parameters that the portlet understands.

When called, the portlet should return a list of the parameters that it understands in the table: wwpro_api_provider.portlet_parameter_table.

Any user can use this function.

Example:

Calling code:

   l_parameter_list := wwpro_api_provider.describe_portlet_parameters
   (
       p_provider_id   => 178,
       p_portlet_id    => 14,
       p_language      => wwnls_api.AMERICAN
   );
 

Portlet call:

   l_parameter_list := example_provider.describe_portlet_parameters
   (
       p_provider_id   => 178,
       p_portlet_id    => 14,
       p_language      => wwnls_api.AMERICAN
   );
 

Parameters:

p_provider_id - a unique identifier for the provider

p_portlet_id - a unique identifier used to locate the portlet in the provider domain. A null value is not permitted.

p_language - the identifier for the native language in which the strings are returned to OracleAS Portal 10G. A null value is not permitted.

Returns:

a table that contains all the parameters that the specified portlet understands

Exceptions:

PROVIDER_NOT_FOUND_EXCEPTION - if provider cannot be located

PROVIDER_EXECUTION_EXCEPTION - if provider cannot be executed

PROVIDER_VALIDATION_EXCEPTION - if provider has given invalid information about the portlet

PORTLET_VALIDATION_EXCEPTION - if provider has given invalid information about the portlet

PORTLET_SECURITY_EXCEPTION - if the portlet does not allow the user to run it

PORTLET_EXECUTION_EXCEPTION - if there is a generic problem with the portlet that prevents the portlet from being executed

Since:

Oracle Portal 3.0.6.6.5

do_login

procedure do_login(
    p_provider_id in integer,
    p_browser_cookies in cookie_table,
    p_provider_cookies out cookie_table
) 

Allows a provider to do initialization or login-based processing before a portlet is executed.

For example, a provider may have a special 'login' style setup to determine whether their service has been previously used in the user's session. Depending on the outcome, some provider-specific login processing can take place, such as producing a cookie. Cookies can then be provided to each of the provider's portlets via the do_login procedure as they are executed.

Notes:

Cookies produced by this procedure are supplied to each portlet when executed.

This procedure cannot be used to produce Web output. It can only be used to access and set cookies.

OracleAS Portal 10G may call this procedure once per page request. The flag login_frequency of the provider record determines how often this procedure is called during an OracleAS Portal 10G session.

Any user can use this procedure.

Example:

Calling code:

   wwpro_api_provider.do_login
   (
       p_provider_id       => 135,
       p_browser_cookies   => l_browser_cookies,
       p_provider_cookies  => l_provider_cookies
   );
 

Provider call:

   example_provider.do_login
   (
       p_provider_id       => 135,
       p_browser_cookies   => l_browser_cookies,
       p_provider_cookies  => l_provider_cookies
   );
 

Parameters:

p_provider_id - the ID for the provider

p_browser_cookies - browser cookies retrieved from the HTTP header

p_provider_cookies - provider-specific cookies created by the provider

Exceptions:

PROVIDER_VALIDATION_EXCEPTION - if invalid information about the provider is returned

PROVIDER_NOT_FOUND_EXCEPTION - if provider cannot be located

PROVIDER_EXECUTION_EXCEPTION - if provider cannot be executed

PROVIDER_SECURITY_EXCEPTION - if provider does not allow the user to run it

Since:

Oracle Portal 3.0.6.6.5

get_api_version

function get_api_version(
    p_provider_id in integer
) return integer

Returns the API version of the provider's implementation.

Note: At the moment all pl/sql providers must return wwpro_api_provider.API_VERSION_1.

Any user can use this function.

Example:

   l_version := wwpro_api_provider.get_api_version
   (
       p_provider_id => 19834
   );
 

Parameters:

p_provider_id - a unique identifier for the provider

Returns:

the expected API version to OracleAS Portal 10G

Since:

Oracle Portal 3.0.6.6.5

get_portlet

function get_portlet(
    p_provider_id in integer,
    p_portlet_id in integer,
    p_language in varchar2 default null
) return portlet_record

Returns details of the specified portlet in portlet_record record structure.

The provider can delegate a call to the portlet implementation to return the portlet record or directly fill in the details for the portlet record.

Any user can use this function.

Example:

Calling code:

   l_portlet_record := wwpro_api_provider.get_portlet
   (
       p_provider_id   =>178,
       p_portlet_id    =>14,
       p_language      =>wwnls_api.AMERICAN
   );
 

Provider call:

   l_portlet_record := example_provider.get_portlet
   (
       p_provider_id   => 178,
       p_portlet_id    =>14,
       p_language      =>wnls_api.AMERICAN
   );
 

Parameters:

p_provider_id - a unique identifier used to identify the provider. A null value is not permitted.

p_portlet_id - a unique identifier that locates the portlet within the provider domain. A null value is not permitted.

p_language - the native language in which provider translatable strings are returned

Returns:

a portlet record as wwpro_api_provider.portlet_record

Exceptions:

PROVIDER_VALIDATION_EXCEPTION - if invalid information about the provider is returned

PROVIDER_NOT_FOUND_EXCEPTION - if provider cannot be located

PROVIDER_EXECUTION_EXCEPTION - if provider cannot be executed

PORTLET_VALIDATION_EXCEPTION - if provider has given invalid information about the portlet

Since:

Oracle Portal 3.0.6.6.5

get_portlet_list

function get_portlet_list(
    p_provider_id in integer,
    p_start_row in integer,
    p_row_count in integer,
    p_language in varchar2 default null,
    p_security_level in boolean default true,
    p_type in integer default list_portlet
) return portlet_table

Returns a list of portlets available from a provider.

The value of the p_security_level parameter indicates whether security checks will be performed to determine whether a portlet will be returned in the list. When a portlet repository refresh operation retrieves the master list of portlets implemented by the provider, the parameter p_security_level has a value of false. A value of false indicates to the provider that no portlet security check is required and that a master list of all of the portlets implemented by the provider must be returned.

The master list of portlets returned is used to populate the portlet repository for that provider. If the value of p_security_level is true, then it is up to the provider implementation to decide whether portlet security should be performed. If portlet security is implemented, the provider may return a different list of portlets depending on the currently logged on user.

For example, a provider serves portlets 'A', 'B', and 'C'. Because of different user privileges, in response to a wwpro_api_provider.get_portlet_list call, the provider might return 'A' and 'B' as portlets for one user and 'A' and 'C' as portlets for another user.

Notes:

The provider can use the procedures and functions in the context package wwctx_api to get the user logged in and to determine which portlets that user can see.

The provider can call the get_portlet function to return information about individual portlets and to populate the portlet table.

Because a provider can change the security of a given portlet at any time, callers of this API that store the returned portlet ID should be prepared to receive either a PORTLET_NOT_FOUND_EXCEPTION or a PORTLET_SECURITY_EXCEPTION when attempting to invoke the procedures and functions of the portlet.

Any user can use this function.

Example:

Calling code:

   l_portlet_table := wwpro_api_provider.get_portlet_list
   (
       p_provider_id    => 137,
       p_start_row      => 1,
       p_row_count      => 100,
       p_language       => wwnls_api.AMERICAN,
       p_security_level => false
   );
 

Provider call:

   l_portlet_table := example_provider.get_portlet_list
   (
       p_provider_id    => 137,
       p_start_row      => 1,
       p_row_count      => 100,
       p_language       => wwnls_api.AMERICAN,
       p_security_level => false
   );
 

Parameters:

p_provider_id - a unique identifier for the portlet provider

p_start_row - the number for the first row of the requested data table

p_row_count - the maximum number of rows to be returned

p_language - the national language name in which the strings are returned to the caller of this API

p_security_level - indicates whether user-level security is in use

p_type - indicates the type of the list to be returned (portlet or component), as specified by a list constant

Returns:

a list of portlets available from a provider

Exceptions:

PROVIDER_VALIDATION_EXCEPTION - if invalid information about the provider is returned

PROVIDER_NOT_FOUND_EXCEPTION - if provider cannot be located

PROVIDER_EXECUTION_EXCEPTION - if provider cannot be executed

Since:

Oracle Portal 3.0.6.6.5

is_portlet_runnable

function is_portlet_runnable(
    p_portlet_instance in portlet_instance_record
) return boolean

Determines if a portlet can be run. It can be used to determine if a user can execute the portlet. It runs before exposing a portlet instance.

This function may be called in two different situations:

• To check if a user can view a portlet in the Portlet Repository.
• To check if a user can view a portlet displayed on a page. The call is made by the show_portlet procedure in MODE_SHOW.

Notes:

The portlet may use the context package wwctx_api to get the current user, then determine if the user can execute the portlet using a portlet-specific security mechanism.

OracleAS Portal 10G may call this function to determine if links, menus, and other visual cues for the specified portlet instance should be displayed.

A portlet instance is the display of a portlet on a single page. The same portlet may be displayed multiple times on the same page. Each time a portlet is added to a page, OracleAS Portal 10G generates a unique portlet instance ID that is the instance's reference path.

Any user can use this function.

Example:

Calling code:

   can_run := wwpro_api_provider.is_portlet_runnable
   (
       p_portlet_instance => l_portlet_instance
   );
 

Provider call:

   can_run := example_provider.is_portlet_runnable
   (
       p_portlet_instance => portlet_instance_rec
   );
 

Parameters:

p_portlet_instance - a record containing properties of a portlet instance

Exceptions:

PROVIDER_VALIDATION_EXCEPTION - if invalid information about the provider is returned

PROVIDER_NOT_FOUND_EXCEPTION - if provider cannot be located

PROVIDER_EXECUTION_EXCEPTION - if provider cannot be executed

PROVIDER_SECURITY_EXCEPTION - if portlet does not allow the user to run it

PORTLET_EXECUTION_EXCEPTION - if there is a generic problem with the portlet that prevents the portlet from being executed

Since:

Oracle Portal 3.0.6.6.5

register_portlet

procedure register_portlet(
    p_portlet_instance in portlet_instance_record
) 

Registers the use of the portlet every time the portlet is placed on 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.

Notes:

The reference_path field of the p_portlet_instance parameter can be used as a key for instance level initializations.

A portlet instance is the display of a portlet on a single page. The same portlet may be displayed multiple times on the same page. Each time a portlet is added to a page, OracleAS Portal 10G generates a unique portlet instance ID that is the instance's reference path.

Because OracleAS Portal 10G provides every portlet instance with a unique reference path to its containing page, portlet developers can use the reference_path as part of the key for storing end-user customization information.

Any user can use this procedure.

Example:

Calling code:

   wwpro_api_provider.register_portlet
   (
       p_portlet_instance => portlet_instance_rec
   );
 

Provider call:

   example_provider.register_portlet
   (
       p_portlet_instance => portlet_instance_rec
   );
 

Parameters:

p_portlet_instance - a record containing the properties of a portlet instance

Exceptions:

PROVIDER_VALIDATION_EXCEPTION - if invalid information about the provider is returned

PROVIDER_NOT_FOUND_EXCEPTION - if provider cannot be located

PROVIDER_EXECUTION_EXCEPTION - if provider has given invalid information about the portlet

PROVIDER_SECURITY_EXCEPTION - if the portlet does not allow the user to run it

PORTLET_EXECUTION_EXCEPTION - if there is a generic problem with the portlet that prevents the portlet from being executed

Since:

Oracle Portal 3.0.6.6.5

register_provider

procedure register_provider(
    p_provider_id in integer
) 

Allows providers to do provider-level initializations.

The registration may be via the OracleAS Portal 10G UI or API function wwpro_api_provider_registry.register_provider.

Any user can use this procedure.

Example:

Calling code:

   wwpro_api_provider.register_provider
   (
       p_provider_id => 1348
   );
 

Provider call:

   provider_owner.example_provider.register_provider
   (
       p_provider_id => 1348
   );
 

Parameters:

p_provider_id - a unique identifier for the provider

Exceptions:

PROVIDER_VALIDATION_EXCEPTION - if invalid information about the provider is returned

PROVIDER_NOT_FOUND_EXCEPTION - if provider cannot be located

PROVIDER_EXECUTION_EXCEPTION - if provider cannot be executed

PORTLET_VALIDATION_EXCEPTION - if provider has given invalid information about the portlet

PORTLET_SECURITY_EXCEPTION - if user does not have correct privileges to run the portlet

PORTLET_EXECUTION_EXCEPTION - if there is a generic problem with the portlet that prevents the portlet from being executed

Since:

Oracle Portal 3.0.6.6.5

show_portlet

procedure show_portlet(
    p_portlet_record in out portlet_runtime_record
) 

Displays portlet content based on a show mode.

OracleAS Portal 10G calls this procedure to render a portlet on a page. When called the portlet should produce the necessary HTML or XML/XSL to display itself on the OracleAS Portal 10G page. This procedure may be called in one of eight different modes.

The page produced should contain the restricted set of HTML markup that is legal to place inside an HTML table cell, i.e. no HEAD or BODY tags as these are applied by OracleAS Portal 10G.

Notes:

The provider may delegate calls to individual portlet implementations.

If you choose to implement multiple portlets in a single package, calls should be delegated to that package.

You are responsible for determining the appropriate level of security and auditing.

A single portlet can be placed as separate instances on many pages. Each instance is assigned its own reference path by the containing page.

The reference_path parameter can by used by the portlet as part of the key for storing end-user customization information.

More than one instance of a portlet can be displayed on the same page.

Because the portlet_id indicates each specific portlet's page and position on the page, portlet developers can use it to implement multiple portlets with a single PL/SQL package.

The page rendered must contain only HTML markup appropriate for an HTML table cell. OracleAS Portal 10G applies the HTML, HEAD, and BODY tags.

Any user can use this procedure.

Example:

Calling code:

   wwpro_api_provider.show_portlet
   (
       l_portlet_record
   );
 

Provider call:

   example_provider.show_portlet
   (
       l_portlet_record
   );
 

Parameters:

p_portlet_record - a portlet record structure that contains information for the requested portlet

Exceptions:

PROVIDER_VALIDATION_EXCEPTION - if invalid information about the provider is returned

PROVIDER_NOT_FOUND_EXCEPTION - if provider cannot be located

PROVIDER_EXECUTION_EXCEPTION - if provider cannot be executed

PROVIDER_SECURITY_EXCEPTION - if provider does not allow the user to run it

PORTLET_VALIDATION_EXCEPTION - if the provider has given invalid information about the portlet

PORTLET_EXECUTION_EXCEPTION - if there is a generic problem with the portlet that prevents the portlet from being executed

Since:

Oracle Portal 3.0.6.6.5