Package wwpro_api_provider_registry

This package contains methods to register and deregister providers and to do related tasks. Note: Register and Edit functions are secure. Users must have All Provider Manage or All Provider Publish rights to use them.

Scope:

Public

Since:

Oracle Portal 3.0.6.6.5

node_provider_rec_table

type node_provider_rec_table is table of node_provider_record index by binary_integer

A table structure containing a list of node_provider_records. A provider_table structure is returned after calling the provider listing functions.

node_provider_record

type node_provider_record is record (
    id number(9),
    name varchar2(200),
    display_name long,
    node_id number,
    timeout number,
    timeout_msg_id number,
    timeout_msg long,
    implementation_style number,
    implementation_owner varchar2(30),
    implementation_name varchar2(2000),
    language varchar2(30),
    enable_distribution boolean,
    login_frequency char(1),
    http_url varchar2(1024),
    same_cookie_domain boolean,
    require_proxy boolean,
    require_session_data boolean,
    is_offline boolean,
    http_app_type varchar2(30),
    http_app_id varchar2(80),
    provider_key varchar2(80),
    node_name varchar2(200),
    dad_name varchar2(64),
    db_link varchar2(120),
    local boolean,
    http_listener_host varchar2(120),
    http_listener_port number,
    created_on date,
    created_by varchar2(256),
    last_updated_on date,
    last_updated_by varchar2(256),
    service_id varchar2(1000),
    midtier_proxy_hostname varchar2(2000),
    midtier_proxy_portnumber number,
    dbtier_proxy_hostname varchar2(2000),
    dbtier_proxy_portnumber number
)

A record structure containing properties of a provider and its corresponding node.

Fields:

id - this identifier for the provider is allocated by Oracle Portal and is unique for each provider and also across a distributed Oracle Portal system. Note that a null value is not permitted.

name - a name for the provider. This provider name is not translated, can be used during searching, and is presented in the UI when Oracle Portal is required to list providers. Note that the name returned is not sensitive to the language and a null value is not permitted.

display_name - a translatable string for the provider name. This string is sensitive to the language parameter. Oracle Portal can use this name when displaying provider information.

node_id - a unique identifier for the node (Oracle Portal installation). Note that the node ID is unique across distributed provider nodes.

timeout - the default number of seconds that the Oracle Portal should try to connect to this provider before displaying a timeout message. Note that Oracle Portal first attempts to retrieve a timeout value from the portlet, then from the provider. If both attempts fail, it uses the Oracle Portal default timeout value.

timeout_msg_id - the NLS message ID for the provider's timeout message. Note that Oracle Portal first attempts to retrieve a timeout message ID from the portlet, then from the provider. If both attempts fail, it uses the Oracle Portal default timeout message ID.

timeout_msg - the message string to be presented when the execution timeout occurs. Oracle Portal first attempts to retrieve a timeout message from the portlet, then from the provider. If both attempts fail, it uses the Oracle Portal default timeout message. Note that if the timeout_msg_id is null, this string is added to the NLS tables and its NLS ID is used as the value for the timeout_msg_id.

implementation_style - the implementation style used by the provider. The supported styles are database providers and Web providers. Database providers are represented by wwpro_api_provider_registry.DATABASE_IMPL and wwpro_api_provider_registry.PLSQL_ IMPL. Web providers are represented by wwpro_api_provider_registry.WEB_IMPL and wwpro_api_provider_registry.HTTP_IMPL. Note that a null value is not permitted.

implementation_owner - the database schema that contains the provider's implementation packages. This field is only valid for database providers. Note that a null value is not permitted.

implementation_name - the name of the provider's implementation package. If the implementation_style is PLSQL_IMPL, this represents the name of the PL/SQL package that implements the provider methods. This field is only valid for database providers. Note that a null value is not permitted.

language - the language in which the translatable strings are returned. Note that a null value is not permitted.

enable_distribution - a flag that indicates if a provider can be registered on remote nodes. Note that an enable_distribution value for providers on remote nodes is always TRUE.

login_frequency - indicates how often Oracle Portal should login with the provider. For database providers, this flag determines the frequency of calls made to the do_login API. For Web providers, this flag determines the frequency of calls made to initSession. Note that:
wwpro_api_provider_registry.LOGIN_ FREQUENCY_ALWAYS - Oracle Portal performs a login operation every time a portlet, from this provider, is requested to be viewed.
wwpro_api_provider_ registry.LOGIN_FREQUENCY_ONCE - Oracle Portal performs a login operation only the first time a portlet, from this provider, is requested to be viewed in the same user session.
wwpro_api_ provider_registry.LOGIN_FREQUENCY_NEVER - Oracle Portal does not perform any login with the provider.
(Web providers only) wwpro_api_provider_ registry.LOGIN_FREQUENCY_PUBLIC - indicates that the initSession method is not called. In addition, no user information is passed to any of the provider calls.

http_url - the URL Oracle Portal uses to make calls to the Web provider, as defined during provider registration. This field is only valid for Web providers, i.e. the implementation_style is HTTP_IMPL (or WEB_IMPL).

same_cookie_domain - indicates whether the Web provider is in the same cookie domain as Oracle Portal.

require_proxy - a flag that indicates if a proxy server is required to make a URL connection. This field is only valid for Web providers. Note that a proxy server provides access to content from servers outside a firewall. If a proxy server is required, you can identify the proxy server in the Services portlet by clicking Global Settings.

require_session_data - a flag that indicates whether session information is to be sent to the provider. This field is only valid for Web providers.

is_offline - a flag that indicates whether the provider is off-line. Note that a provider must be online during registration. Therefore, if is_offline is set to 'true' an will error occur.

http_app_type - a value provided by one of two constants that indicates if the Web provider being registered requires its own ID for the user to be communicated to it from the Single Sign-On Server or the Oracle Portal's ID for the user. Valid http_app_type values are: EXTERNAL_SECURED - the Web provider requires its own ID for the user. PORTAL - the Web provider accepts the Oracle Portal's ID for the user.

http_app_id - the ID used to register the external application with the Single Sign-On Server. Note that if the http_app_type is EXTERNAL_SECURED, this field stores the external application ID. Otherwise this field is null.

provider_key - a key passed to the Web provider. The provider uses it to look up and track use of the provider's encryption key, and to keep track of Oracle Portal using their system.

node_name - the unique name for the node that the provider belongs to

dad_name - for a provider that exists on a remote node, this is the remote Oracle Portal's DAD

db_link - a unique name for the database link

local - a flag that indicates if the provider exists on the local node or on a remote node

http_listener_host - not used. Oracle Portal 9.0.2 or later.

http_listener_port - not used. Oracle Portal 9.0.2 or later.

created_on - the date that the provider was registered with the Portal installation. Note that this value is filled in by functions returning a provider_record.

created_by - the user who registered this provider with the Portal installation. Note that this value is filled in by functions returning a provider_record.

last_updated_on - the date this provider was last updated in Oracle Portal. Note that this value is filled in by functions returning a provider_record.

last_updated_by - the user who last updated the provider. Note that this value is filled in by functions returning a provider_record.

service_id - the service ID for the provider. This uniquely identifies the provider within a portal when the provider is accessed via the Federated Portal Adapter.

midtier_proxy_hostname - the host name of the proxy to be used for calls to the provider originating from the middle tier

midtier_proxy_portnumber - the port number of the proxy to be used for calls to the provider originating from the middle tier

dbtier_proxy_hostname - the host name of the proxy to be used for calls to the provider originating from the database

dbtier_proxy_portnumber - the port number of the proxy to be used for calls to the provider originating from the database.

Since:

Oracle Portal 3.0.6.6.5

provider_id_table

type provider_id_table is table of number index by binary_integer

A table structure containing a list of provider IDs.

provider_record

type provider_record is record (
    id number(9),
    name varchar2(200),
    display_name long,
    node_id number,
    timeout number,
    timeout_msg_id number,
    timeout_msg long,
    implementation_style number,
    implementation_owner varchar2(30),
    implementation_name varchar2(2000),
    language varchar2(30),
    enable_distribution boolean,
    login_frequency char(1),
    http_url varchar2(1024),
    same_cookie_domain boolean,
    require_proxy boolean,
    require_session_data boolean,
    is_offline boolean,
    http_app_type varchar2(30),
    http_app_id varchar2(80),
    provider_key varchar2(80),
    encryption_key varchar2(80),
    existing_provider_id number(9),
    created_on date,
    created_by varchar2(256),
    last_updated_on date,
    last_updated_by varchar2(256),
    provider_group_id varchar2(32),
    service_id varchar2(1000),
    midtier_proxy_hostname varchar2(2000),
    midtier_proxy_portnumber number,
    dbtier_proxy_hostname varchar2(2000),
    dbtier_proxy_portnumber number
)

A record structure containing the details for a provider. This record type is used when registering or editing a provider.

Fields:

id - this identifier for the provider is allocated by Oracle Portal and is unique for each provider. Note that a null value is not permitted.

name - a name for the provider. This provider name is not translated, can be used during searching, and is presented in the UI when Oracle Portal is required to list providers. Note that the name returned is not sensitive to the language and a null value is not permitted.

display_name - a translatable string for the provider name. This string is sensitive to the language parameter. Oracle Portal can use this name when displaying provider information.

node_id - a unique identifier for the Oracle Portal installation. Note that only the local node ID can be passed. Also, note that if null, node_id defaults to the local installation.

timeout - number the default number of seconds that Oracle Portal should try to connect to this provider before displaying the timeout message. Note that Oracle Portal first tries to retrieve a timeout value from the portlet, then from the provider. If both attempts fail, it uses the Oracle Portal default timeout value.

timeout_msg_id - the NLS message ID for the provider's timeout message. Note that Oracle Portal first tries to retrieve a timeout message ID from the portlet, then from the provider. If both attempts fail, it uses the Oracle Portal default timeout message ID.

timeout_msg - the message string to be presented when the execution timeout occurs. The timeout message may not contain mobile (mobileMXL) or desktop (HTML) markup. Note that if the timeout_msg_id is null, this string is added to the NLS tables and its NLS ID is used as the value for the timeout_msg_id.

implementation_style - the implementation style used by the provider. Note that a null value is not permitted.

implementation_owner - the database schema that contains the provider's implementation packages. This field is only valid for database providers. Note that a null value is not permitted.

implementation_name - the name of the provider's implementation package. If the implementation_style is PLSQL_IMPL, this represents the name of the PL/SQL package that implements the provider methods. This field is only valid for database providers. Note that a null value is not permitted.

language - a constant that specifies the language for the returned translatable strings. Note that a null value is not permitted.

enable_distribution - not used, Oracle9iAS Portal 9.0.2 or later

login_frequency - how often Oracle Portal should login with the provider. For database providers, this flag determines the frequency of calls made to the do_login API. For Web providers, this flag determines the frequency of calls made to initSession. The valid values for this field are the Provider Login Frequency constants.

http_url - the URL Oracle Portal uses to make calls to the Web provider, as defined during provider registration. This field is only valid for Web providers, i.e. the implementation_style is HTTP_IMPL (or WEB_IMPL).

same_cookie_domain - indicates whether the Web provider is in the same cookie domain as Oracle Portal.

require_proxy - indicates if a proxy server is required to make a URL connection. This field is only valid for Web providers. Note that a proxy server provides access to content from servers outside a firewall. If a proxy server is required, you can identify the proxy server in the Services portlet by clicking Global Settings.

require_session_data - indicates whether session information is to be sent to the provider. This field is only valid for Web providers.

is_offline - indicates whether the provider is off-line. Note that a provider must be online during registration. Therefore, if is_offline is set to 'true' an will error occur.

http_app_type - a value provided by one of two constants that indicates if the Web provider being registered requires its own ID for the user to be communicated to it from the Single Sign-On Server or the Oracle Portal's ID for the user. Valid http_app_type values are: EXTERNAL_SECURED - the Web provider requires its own ID for the user, and PORTAL - the Web provider accepts the Oracle Portal's ID for the user.

http_app_id - the ID used to register the external application with the Single Sign-On Server. Note that if the http_app_type is EXTERNAL_SECURED, this field stores the external application ID, otherwise this field is null.

existing_provider_id - The current provider ID. Use this value with the edit_provider procedure to identify the provider that will have its ID changed. When existing_provider_id contains an ID, edit_provider updates the provider ID to match the value in the ID field of the provider_record. When existing_provider_id is null, the value in the provider_record ID field is used to determine which provider should be updated.

provider_key - a key passed to the Web provider. The provider uses it to look up and track the use of the provider's encryption key, and to track Oracle Portal when using their system.

encryption_key - an encryption key that is shared with the Web provider. This key is used to encrypt and decrypt data communicated to the provider. Note that if an encryption key value exists, a provider key value also must exist.

created_on - the date the provider was registered with Oracle Portal. Note that this value is used by functions returning a provider_record.

created_by - the user who registered this provider with Oracle Portal. Note that this value is filled in by functions returning a provider_record.

last_updated_on - the date the provider was last updated by Oracle Portal. Note that this value is used by functions returning a provider_record.

last_updated_by - the user who last updated the provider. Note that this value is filled in by functions returning a provider_record.

provider_group_id - the ID of the provider group (if any) to which this provider belongs.

service_id - the service ID for the provider. This uniquely identifies the provider within a portal when the provider is accessed via the Federated Portal Adapter.

midtier_proxy_hostname - the host name of the proxy to be used for calls to the provider originating from the middle tier

midtier_proxy_portnumber - the port number of the proxy to be used for calls to the provider originating from the middle tier

dbtier_proxy_hostname - the host name of the proxy to be used for calls to the provider originating from the database

dbtier_proxy_portnumber - the port number of the proxy to be used for calls to the provider originating from the database

Since:

Oracle Portal 3.0.6.6.5

provider_table

type provider_table is table of provider_record index by binary_integer

A table structure containing a list of provider_records.

DATABASE_IMPL

DATABASE_IMPL constant integer := 2

ENABLE_DISTRIBUTION_NO

ENABLE_DISTRIBUTION_NO constant number := 0

Deprecated. as of Oracle9iAS Portal 9.0.2

ENABLE_DISTRIBUTION_YES

ENABLE_DISTRIBUTION_YES constant number := 1

Deprecated. as of Oracle9iAS Portal 9.0.2

HTTP_APP_TYPE_EXTERNAL

HTTP_APP_TYPE_EXTERNAL constant varchar2(30) := 'EXTERNAL_SECURED'

HTTP_APP_TYPE_PORTAL

HTTP_APP_TYPE_PORTAL constant varchar2(30) := 'PORTAL'

HTTP_IMPL

HTTP_IMPL constant integer := 3

IS_PROV_OFF_NO

IS_PROV_OFF_NO constant number := 0

IS_PROV_OFF_YES

IS_PROV_OFF_YES constant number := 1

LOGIN_FREQUENCY_ALWAYS

LOGIN_FREQUENCY_ALWAYS constant char(1) := 'A'

LOGIN_FREQUENCY_NEVER

LOGIN_FREQUENCY_NEVER constant char(1) := 'N'

LOGIN_FREQUENCY_ONCE

LOGIN_FREQUENCY_ONCE constant char(1) := 'O'

LOGIN_FREQUENCY_PUBLIC

LOGIN_FREQUENCY_PUBLIC constant char(1) := 'P'

PLSQL_IMPL

PLSQL_IMPL constant integer := 2

RAISE_PROVIDER_EXCPT

RAISE_PROVIDER_EXCPT constant integer := 0

Do not suppress exception caused by calls to provider functions.

REQ_PROXY_NO

REQ_PROXY_NO constant number := 0

REQ_PROXY_YES

REQ_PROXY_YES constant number := 1

REQ_SESS_DATA_NO

REQ_SESS_DATA_NO constant number := 0

REQ_SESS_DATA_YES

REQ_SESS_DATA_YES constant number := 1

SAME_COOKIE_DOMAIN_NO

SAME_COOKIE_DOMAIN_NO constant number := 0

SAME_COOKIE_DOMAIN_YES

SAME_COOKIE_DOMAIN_YES constant number := 1

SUPPRESS_PROVIDER_EXCPT

SUPPRESS_PROVIDER_EXCPT constant integer := 1

Suppress exception caused by calls to provider functions.

WEB_IMPL

WEB_IMPL constant integer := 3

add_portlet_to_repository

procedure add_portlet_to_repository(
    p_provider_id in integer,
    p_portlet_id in integer
) 

Adds portlets to the portlet repository. It can be used by portlet providers to dynamically add portlets.

Note: A user must have at least the Manage Items privilege on the provider folder within the portlet repository to execute this function.

Example

   wwpro_api_provider_registry.add_portlet_to_repository
   (
         p_provider_id => 5,
         p_portlet_id  => 22
   );
 

Parameters:

p_provider_id - a unique identifier for a provider that is allocated by Oracle Portal. Note that a null value is not permitted.

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

Exceptions:

wwpro_api_provider.ADD_PORTLET_EXCEPTION - if an unexpected exception occurs

Since:

Oracle Portal 3.0.8

deregister_provider

procedure deregister_provider(
    p_id in integer,
    p_supress_exception in integer default raise_provider_excpt
) 

Removes a provider's registration record from Oracle Portal, given the provider ID. Call this procedure to remove one or more providers' registration records from the provider registry, given a provider ID. When called, deregister_provider calls the provider's deregister procedure. The portlet repository is updated.

Notes:

When the implementation type is PL/SQL, this overloaded API does not remove the provider schema or provider implementation packages. The caller must remove these separately, if required.

Providers may also be removed using the deregister_provider (owner) procedure.

Providers marked as 'non-deleteable' are not removed.

Deleting a provider disables all portlet instances for that provider. To reinstate a deleted provider, use the wwpro_api_provider_registry.register_provider function with the original provider ID. The provider's disabled portlets are then restored.

A user must have the All Provider Manage or All Provider Publish privilege to de-register a provider.

Example

   l_provider_id := 92837;
   wwpro_api_provider_registry.deregister_provider
   (
      p_id                => l_provider_id,
      p_supress_exception => wwpro_api_provider_registry
                                .SUPPRESS_PROVIDER_EXCPT
   );
 

Parameters:

p_id - a unique identifier for the portlet provider to be deregistered. Note that a null value is not permitted.

p_supress_exception - indicates whether to suppress failure of provider deregister function. If this parameter is set to RAISE_PROVIDER_EXCPT and a provider raises an exception in its deregister provider function, a wwpro_api_provider.PROVIDER_CALLDEREG_ EXCEPTION exception is raised. If this parameter is set to SUPPRESS_PROVIDER_EXCPT and a call to the providers deregister function fails, the exception is suppressed. RAISE_PROVIDER_EXCPT is the default.

Exceptions:

wwpro_api_provider.PROVIDER_SECURITY_EXCEPTION - if the user has insufficient privileges to run this API

wwpro_api_provider.PROVIDER_REMOVAL_EXCEPTION - if the provider is not found, if an execution is raised, if the provider is not a local provider, or if an attempt is made to deregister a provider marked as non-deleteable

wwpro_api_provider.PROVIDER_CALLDEREG_EXCEPTION - if an exception is raised when calling the provider's deregister method

Since:

Oracle Portal 3.0.6.6.5

deregister_provider

procedure deregister_provider(
    p_owner in varchar2,
    p_supress_exception in integer default raise_provider_excpt
) 

Removes a provider's registration record from Oracle Portal, given the name of the schema that owns the provider. Call this procedure to remove one or more providers' registration records from the provider registry, identifying the provider by schema name. When called, deregister_provider calls the provider's deregister procedure. The portlet repository is updated.

Notes:

When the implementation type is PL/SQL, this overloaded API does not remove the provider schema or provider implementation packages. The caller must remove these separately, if required.

Providers may also be removed using the deregister_provider (id) procedure.

Providers marked as 'non-deleteable' are not removed.

Deleting a provider disables all portlet instances for that provider. To reinstate a deleted provider, use the wwpro_api_provider_registry.register_provider function with the original provider ID. The provider's disabled portlets are then restored.

A user must have the All Provider Manage or All Provider Publish privilege to de-register a provider.

Example

   l_owner       := 'userapp'

   wwpro_api_provider_registry.deregister_provider
   (
      p_owner             => l_owner,
      p_supress_exception => wwpro_api_provider_registry
                               .SUPPRESS_PROVIDER_EXCPT
   );
 

Parameters:

p_owner - the name of the schema that owns the provider

p_supress_exception - indicates whether to suppress failure of the provider deregister function. If this parameter is set to RAISE_PROVIDER_EXCPT and a provider raises an exception in its deregister provider function, a wwpro_api_provider.PROVIDER_CALLDEREG_ EXCEPTION exception is raised. If this parameter is set to SUPPRESS_PROVIDER_EXCPT and a call to the providers deregister function fails, the exception is suppressed. The default is RAISE_PROVIDER_EXCPT.

Exceptions:

wwpro_api_provider.PROVIDER_SECURITY_EXCEPTION - if the user has insufficient privileges to run this API

wwpro_api_provider.PROVIDER_REMOVAL_EXCEPTION - if the provider is not found, if an execution is raised, if the provider is not a local provider, or if an attempt is made to deregister a provider marked as non-deleteable

wwpro_api_provider.PROVIDER_CALLDEREG_EXCEPTION - if an exception is raised when calling the provider's deregister method

Since:

Oracle Portal 3.0.6.6.5

edit_provider

procedure edit_provider(
    p_provider in provider_record
) 

Updates portlet provider settings for a registered provider. Call this procedure to update the properties of a provider registered with Oracle Portal. This procedure only updates local providers, i.e. in the local Oracle Portal installation.

Notes:

A user must have the All Provider Manage or the All Provider Publish privilege to edit a provider record.

Example

   l_provider wwpro_api_provider_registry.provider_record;
   l_provider.id := 849478;
   l_provider.login_frequency := wwpro_api_provider.LOGIN_FREQUENCY_ONCE;

   wwpro_api_provider_registry.edit_provider(l_provider);
 

Parameters:

p_provider - a provider record specifying current provider properties

Exceptions:

wwpro_api_provider.PROVIDER_SECURITY_EXCEPTION - if the user does not have the privilege to execute this procedure

wwpro_api_provider.PROVIDER_NOT_FOUND_EXCEPTION - if the specified provider is not found

wwpro_api_provider.PROVIDER_VALIDATION_EXCEPTION - if the passed values fail validation or if an unexpected error occurs

wwpro_api_provider.PROVIDER_REGISTRTN_EXCEPTION - if an unexpected error occurs

Since:

Oracle Portal 3.0.6.6.5

find_provider

function find_provider(
    p_id in integer,
    p_language in varchar2 default null
) return node_provider_record

Returns a provider record in the language requested, given a provider ID. The provider record is returned in the language requested, if available. * Providers may also be found using the find_provider (name) procedure.

Note: Any user can execute this function.

Example

   l_provider wwpro_api_provider_registry.node_provider_record;

   l_provider := wwpro_api_provider_registry_provider.find_provider
   (
       p_id       => 20,
       p_language => wwnls_api.AMERICAN
   );
 

Parameters:

p_id - a unique identifier for the portlet provider, allocated by Oracle Portal. Note that a null value is not permitted.

p_language - a constant that specifies the language for the returned translatable strings

Returns:

the provider record (node_provider_record) or null if the provider record is not found.

Since:

Oracle Portal 3.0.6.6.5

find_provider

function find_provider(
    p_name in varchar2,
    p_language in varchar2 default null,
    p_node_id in integer default null
) return node_provider_record

Returns a provider record in the language requested, given a provider name. The provider record is returned in the language requested, if available Providers may also be found using the find_provider (id) procedure.

Note: Any user can execute this function.

Example

   l_provider wwpro_api_provider_registry.node_provider_record;

   l_provider := wwpro_api_provider_registry_provider.find_provider
   (
       p_name      => 'GENERAL',
       p_language  => wwnls_api.AMERICAN
   );
 

Parameters:

p_name - the name of the portlet provider. Note that a null value is not permitted.

p_language - a constant that specifies the language for the returned translatable strings

p_node_id - no longer used, Oracle9iAS Portal 9.0.2 or later. Leave null.

Returns:

the provider record (node_provider_record) or null if the provider record is not found.

Since:

Oracle Portal 3.0.6.6.5

get_encryption_key

function get_encryption_key(
    p_provider_id in number
) return varchar2

Returns the shared key for a Web provider.

Note: A user must have the All Provider Manage or the All Provider Publish privilege to edit a provider record.

Example

   l_encrypt_key varchar2(80);
   l_encrypt_key := wwpro_api_provider_registry.get_encryption_key
     (
       p_provider_id => 23613481
   );
 

Parameters:

p_provider_id - a unique identifier for the portlet provider, allocated by Oracle Portal. Note that the value for this parameter cannot be null.

Returns:

the shared key for the specified Web provider

Exceptions:

wwpro_api_provider.PROVIDER_SECURITY_EXCEPTION - if the user does not have the necessary privileges to execute the API

wwpro_api_provider.PROVIDER_RETRIEVAL_EXCEPTION - if an unexpected error occurs while retrieving the shared key

Since:

Oracle Portal 3.0.6.6.5

get_provider

function get_provider(
    p_id in integer,
    p_language in varchar2 default null
) return node_provider_record

Returns a provider record, in the language requested, if available, and raises an exception if no provider is found. Call this function to search for a provider in Oracle Portal and, if found, return a node_provider record. This API is similar to the find_provider function, but raises an exception if no provider is found. The find_provider function does not raise an exception if no provider is found.

Note: Any user can execute this function.

Example

   l_provider wwpro_api_provider_registry.node_provider_record;
   l_provider := wwpro_api_provider_registry.get_provider
   (
       p_id       => 20,
       p_language => wwnls_api.AMERICAN
   );
 

Parameters:

p_id - a unique identifier for the portlet provider, allocated by Oracle Portal. Note that a null value is not permitted.

p_language - a constant that specifies the language for the returned translatable strings

Returns:

a node_provider_record

Exceptions:

wwpro_api_provider.PROVIDER_NOT_FOUND_EXCEPTION - if the node_provider_record is not found

Since:

Oracle Portal 3.0.6.6.5

get_provider_list

function get_provider_list(
    p_name in varchar2,
    p_start_row in integer default 1,
    p_row_count in integer default 100,
    p_language in varchar2 default null
) return node_provider_rec_table

Returns a provider name or a list of all portlet providers that match a specified name. You can include the SQL matching (wild card) characters % and _ in the name string.

Note: Any user can execute this function.

Example

   l_provider_list := wwpro_api_provider_registry.get_provider_list
   (
       p_name      => 'Portal%',
       p_start_row => 1,
       p_row_count => 10,
       p_language  => wwnls_api.AMERICAN
   );
 

Parameters:

p_name - a name string to be used as a search pattern

p_start_row - a number for the first row in the requested table. It allows for pagination. The default is 1.

p_row_count - maximum number of rows for the requested table. It allows for pagination. The default is 100.

p_language - a constant that specifies the language for the returned translatable strings

Returns:

node_provider_rec_table, a list of all portlet providers that match the search string

Since:

Oracle Portal 3.0.6.6.5

is_null

function is_null(
    p_node_provider in node_provider_record
) return boolean

Determines if a provider record has content. Call this function to determine if a provider record has content. The function checks the ID and the name fields for content.

Note: Any user can execute this function.

Example

   l_is_null := wwpro_api_node_provider_registry.is_null
   (
       p_node_provider
   );
 

Parameters:

p_node_provider - the node_provider record

Returns:

TRUE if both p_node_provider.id and p_node_provider.name are null. Otherwise, it returns FALSE.

Since:

Oracle Portal 3.0.6.6.5

node_provider_to_provider

function node_provider_to_provider(
    p_node_provider in node_provider_record
) return provider_record

Convert a node_provider_record to a provider_record. Some of the APIs in wwpro_api_provider_registry return node_provider_record structures and some provider_record structures. Some of the them take as input the provider_record structure. This API is provided as a utility in cases where the output of one such API needs to be passed as input to another one. For example when find_provider and edit_provider need to be called. The find_provider API returns a node_provider_record and the edit_provider accepts a provider_record as input.

Example

     declare
         l_node_provider
             wwpro_api_provider_registry.node_provider_record;
         l_provider wwpro_api_provider_registry.provider_record;
     begin

         l_node_provider :=
             wwpro_api_provider_registry.find_provider(
                 p_id => '84934884'
             );

         l_provider :=
             wwpro_api_provider_registry.node_provider_to_provider(
                 p_node_provider => l_node_provider
             );

         l_provider.timeout := 200;

         wwpro_api_provider_registry.edit_provider(
             p_provider => l_provider
         );

     end;
 

Parameters:

p_node_provider - the node_provider_record record structure to convert to a provider_record structure

Returns:

the provider_record structure resulted from node_provider_record

print_provider

procedure print_provider(
    p_id in integer,
    p_language in varchar2 default wwctx_api . get_nls_language
) 

Prints, as dbms_output, the specified provider information.

Notes: Any user can execute this procedure.

DBMS_OUTPUT is an Oracle database package that can be used to display the values of variables within a PL/SQL block.

Example

   wwpro_api_provider_registry.procedure print_provider
   (
       p_id       => 787,
       p_language => wwnls_api.AMERICAN
   );
 

Parameters:

p_id - a unique identifier for the portlet provider, allocated by Oracle Portal. Note that the value for this parameter cannot be null.

p_language - a constant that specifies the language for the returned translatable strings

Since:

Oracle Portal 3.0.6.6.5

provider_exist

function provider_exist(
    p_name in varchar2,
    p_node_id in integer default null
) return boolean

Determines whether a provider of a particular name exists.

Note: Any user can execute this function.

Example

   if wwpro_api_provider_registry.provider_exist(p_name =>'Example')
   then
       dbms_output.put_line('Provider Example exists');
   end if;
 

Parameters:

p_name - A name string to be used as a search pattern. For example:

        l_p_exist boolean;
        l_p_exist := wwpro_api_provider_registry.provider_exist('EXAMPLE');
        l_p_exist := wwpro_api_provider_registry.provider_exist('EXample');
        l_p_exist := wwpro_api_provider_registry.provider_exist('example');
                     

All the above return the same value. Note that the search is not case sensitive. The search does not provide for wild character searches, e.g. *.

p_node_id - not used in Oracle9iAS Portal 9.0.2 or later. Leave null.

Returns:

TRUE if p_name exists. Otherwise, it returns FALSE.

Since:

Oracle Portal 3.0.8

refresh_portlet_repository

procedure refresh_portlet_repository

Refreshes the portlet repository. It will contact each provider and update the portlet repository accordingly.

Notes: Executing this function may take some time.

A user must have at least the Manage Items privilege on the provider folder within the portlet repository to execute this function.

Example

   wwpro_api_provider_registry.refresh_portlet_repository
 

Exceptions:

wwpro_api_provider.REFRESH_REPOSITORY_EXCEPTION - if an unexpected error occurs.

Since:

Oracle Portal 3.0.8

register_provider

function register_provider(
    p_provider_rec in provider_record
) return integer

Registers a portlet provider and returns the provider ID. Call this function to register a portlet provider with Oracle Portal and return the provider's ID. When a provider is added to the provider repository, its associated portlets are also added to the portlet repository.

When this API is executed as the Portal schema owner, the Portal user is assumed to be the Portal schema owner who has the necessary privileges to register a provider. However, when the API is executed in a provider schema the Portal user is assumed to be PUBLIC and does not have the necessary privileges to register a provider. In this case, you must first call wwctx_api.set_context to establish an authenticated session within the current SQL*Plus session. You must provide a valid username/password as authentication takes place with the Single Sign-On Server.

Notes:

A user must have the All Provider Manage or All Provider Publish privilege to register the provider.

You can determine the current language settings with the wwnls_api.get_language function.

Implementation Name and Implementation Owner are only valid for PL/SQL implementations.

HTTP URL, Require Proxy, HTTP Application Type, Provider Key, Encryption Key and HTTP Application ID are only valid for HTTP implementations.

If a timeout message ID passed into the provider record is null but the message field has a value, the value is used as the timeout message.

Example

 declare
   l_provider_id integer;
   l_provider_rec wwpro_api_provider_registry.provider_record;
 begin
   l_provider_rec.name    := 'Portal Provider';
   l_provider_rec.node_id := null;
   l_provider_rec.timeout := 1 ;
   l_provider_rec.timeout_msg := 'Component took too long to execute';
   l_provider_rec.implementation_style
                  := wwpro_api_provider_registry.PLSQL_IMPL;
   l_provider_rec.implementation_owner := PORTAL;
   l_provider_rec.implementation_name := 'PORTAL_DEMO_PROVIDER';
   l_provider.language := wwnls_api.AMERICAN;
   l_provider_rec.enable_distribution
                  := wwpro_api_provider_registry.ENABLE_DISTRIBUTION_NO;
   l_provider_rec.login_frequency
                  := wwpro_api_provider_registry.LOGIN_FREQUENCY_ALWAYS;

   l_provider_id  := wwpro_api_provider_registry.register_provider
   (p_provider_rec => l_provider_rec);

   wwpro_api_provider_registry.print_provider(
   l_provider_id,wwnls_api.AMERICAN);
 end;
 

Parameters:

p_provider_rec - the record for the provider to be registered

Returns:

a provider ID and stores the timeout message string in the NLS subsystem in the specified language

Exceptions:

wwpro_api_provider.PROVIDER_SECURITY_EXCEPTION - if the user does not have the correct privilege to register a provider

wwpro_api_provider.PROVIDER_VALIDATION_EXCEPTION - if implementation_style is not wwpro_api_provider_registry.PLSQL_IMPL, wwpro_api_provider_registry.DATABASE_IMPL, wwpro_api_provider_registry.HTTP_IMPL, or wwpro_api_provider_registry.WEB_IMPL

wwpro_api_provider.PROVIDER_VALIDATION_EXCEPTION - if the implementation style is PLSQL_IMPL and implementation_name is not the name of a database package in the implementation_owner schema

wwpro_api_provider.PROVIDER_VALIDATION_EXCEPTION - if the implementation style is PLSQL_IMPL and the implementation_owner is not a valid database user

wwpro_api_provider.PROVIDER_VALIDATION_EXCEPTION - if the status of the implementation package is invalid

wwpro_api_provider.PROVIDER_VALIDATION_EXCEPTION - if passed values fail validation or if an unexpected error occurs. Query the error stack to determine why the validation failed.

wwpro_api_provider.PROVIDER_CALLREG_EXCEPTION - if an unexpected error occurs while calling the providers registration method

wwpro_api_provider.PROVIDER_REGISTRTN_EXCEPTION - if an unexpected error occurs while attempting to register the provider

Since:

Oracle Portal 3.0.6.6.5

remove_portlet_from_repository

procedure remove_portlet_from_repository(
    p_provider_id in integer,
    p_portlet_id in integer
) 

Deletes portlets from the portlet repository. It can also be used by portlet providers to dynamically remove portlets.

Note: A user must have at least the manage items privilege on the provider folder within the portlet repository to execute this function.

Example

   wwpro_api_provider_registry.delete_portlet_from_repository
   (
       p_provider_id => 5,
       p_portlet_id  => 22
   );
 

Parameters:

p_provider_id - a unique identifier for a provider that is allocated by Oracle Portal. Note that a null value is not permitted.

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

Exceptions:

wwpro_api_provider.DELETE_PORTLET_EXCEPTION - if an unexpected error occurs

Since:

Oracle Portal 3.0.6.6.5