8 Creating PL/SQL Portlets

8.1.1 Portlet Show Modes

Just like a Java portlet, a PL/SQL portlet has a variety of Show modes available to it. A Show mode is an area of functionality provided by a portlet. The available Show modes are described more fully in Chapter 6, "Creating Java Portlets":

• Shared Screen mode is described in Section 6.1.1.1, "Shared Screen Mode (View Mode for JPS)"

• Edit mode is described in Section 6.1.1.2, "Edit Mode (JPS and OracleAS Portal)".

• Edit Defaults mode is described in Section 6.1.1.3, "Edit Defaults Mode (JPS and OracleAS Portal)".

• Preview mode is describe in Section 6.1.1.4, "Preview Mode (JPS and OracleAS Portal)".

• Full Screen mode is described in Section 6.1.1.5, "Full Screen Mode (OracleAS Portal)".

• Help mode is described in Section 6.1.1.6, "Help Mode (JPS and OracleAS Portal)".

• About mode is described in Section 6.1.1.7, "About Mode (JPS and OracleAS Portal)".

• Link mode is described in Section 6.1.1.8, "Link Mode (OracleAS Portal)".

To check for the selected Show mode, you can use the constants in the wwpro_api_provider package. These constants are listed with their corresponding Show mode in Table 8-1.

MODE_SHOW

MODE_SHOW_EDIT

MODE_SHOW_EDIT_DEFAULTS

MODE_SHOW_PREVIEW

MODE_SHOW_DETAILS

MODE_SHOW_HELP

MODE_SHOW_ABOUT

MODE_SHOW_LINK

8.1.2 Recommended Portlet Procedures and Functions

The primary goal of the portlet's code is to generate the HTML output that displays on a page for all of the Show modes required by OracleAS Portal. Although it is possible to implement the portlet as a set of separate PL/SQL stored program units, organizing the portlet's code into a PL/SQL package is the best way of encapsulating related portlet code and data as a single unit in the database. You also achieve better database performance and ease of portlet maintenance.

As you may recall from Section 2.4, "Deployment Type", requests from OracleAS Portal for a particular portlet go through the portlet's provider. To communicate with its portlets, the provider contains a set of required methods that make calls to the portlet code.

When implementing a portlet as a PL/SQL package, it is a good idea to organize the portlet code in parallel with the provider code. For example, when the provider needs to retrieve information about one of its portlets, it uses its get_portlet function. Hence, it makes sense for the portlet to contain a get_portlet_info function that returns the requested information when called by the provider's get_portlet function. Similarly, it is logical for the provider's show_portlet procedure to call the portlet's show procedure, which produces the HTML output for a requested Show mode and returns it to the provider.

Table 8-2 describes the recommended procedures and functions for a PL/SQL portlet to communicate effectively with the database provider.

get_portlet_info

show

register

deregister

is_runnable

copy

describe_parameters

8.1.3 Guidelines for Mobile Portlets

OracleAS Portal is capable of rendering its pages for both HTML and non-HTML (mobile) devices. When designing a portlet for a mobile device, you must consider some additional guidelines. The guidelines for mobile portlets are described fully in Section 6.1.3, "Guidelines for Mobile Portlets".

For information on how to build mobile-enabled portlets, refer to Section 8.12, "Enhancing Portlets for Mobile Devices".

8.2.1 Creating the Input XML File

The source XML file starts and ends with the <provider> and </provider> tags, and can include one or more portlet definitions. Each portlet definition is bracketed by the <portlet> and </portlet> tags. A portlet definition includes the XML tags that specify values for the portlet record attributes and enable the links in the portlet header. For example, the <name> tag specifies the portlet name in the provider domain and the <title> tag specifies the portlet display name or title. When set to true, the <showEdit> tag enables the Edit mode for the portlet and the corresponding link in the portlet header. Table 8-3 lists the available XML tags for PL/SQL Generator input.

provider

portlet

id

name

title

shortTitle

description

defaultLocale

timeout

timeoutMsg

showEdit

showEditDefault

showDetails

showPreview

hasHelp

hasAbout

language

contentType

wwpro_api_provider.CONTENT_TYPE_HTML
wwpro_api_provider.CONTENT_TYPE_XML
wwpro_api_provider.CONTENT_TYPE_MOBILE

apiVersion

callIsRunnable

callGetPortlet

acceptContentType

text/html,text/vnd.oracle.mobilexml

hasShowLinkMode

mobileOnly

preferenceStorePath

createdOn

createdBy

lastUpdatedOn

lastUpdatedBy

passAllUrlParams

cacheLevel

wwpro_api_provider.CACHE_LEVEL_SYSTEM
wwpro_api_provider.CACHE_LEVEL_USER
wwpro_api_provider.CACHE_LEVEL_PTL_SESSION

rewriteUrls

Following is a sample of the input XML for the PL/SQL Generator. Mandatory information is shown in bold.

<!-- This is a sample provider.xml file for the PLSQL Generator 1.2 -->
<provider>
    <portlet>
        <id>1</id>
        <name>Test_Portlet</name>
        <title>Test Portlet Title</title>
        <shortTitle>Short portlet title</shortTitle>
        <description>This is a Test portlet</description>
        <timeout>30</timeout>
        <timeoutMsg>Test Portlet Timed Out</timeoutMsg>
        <showEdit>true</showEdit>
        <showEditDefault>true</showEditDefault>
        <showDetails>true</showDetails>
        <showPreview>true</showPreview>
        <hasHelp>true</hasHelp>
        <hasAbout>true</hasAbout>
        <language>en</language>
        <contentType>wwpro_api_provider.CONTENT_TYPE_HTML</contentType>
        <apiVersion>wwpro_api_provider.API_VERSION_1</apiVersion>
        <callIsRunnable>true</callIsRunnable>
        <callGetPortlet>true</callGetPortlet>
        <acceptContentType>'text/html'</acceptContentType>
        <hasShowLinkMode>false</hasShowLinkMode>
        <mobileOnly>false</mobileOnly>
        <passAllUrlParams>true</passAllUrlParams>
        <cacheLevel>wwpro_api_provider.CACHE_LEVEL_USER</cacheLevel>
        <rewriteUrls>true</rewriteUrls>
    </portlet>
</provider>

8.2.2 Running the PL/SQL Generator

After you have created a valid XML input file, you can run the PL/SQL Generator to generate the provider and portlet packages in the form of a SQL file:

1. If you have not already done so, install the PL/SQL Generator according to the instructions that came with the download.

2. From your browser, go to the URL for the PL/SQL Generator. It should look something like the page shown in Figure 8-1.

   Figure 8-1 PL/SQL Generator Page

   
   Description of "Figure 8-1 PL/SQL Generator Page"
   
   

3. Click Browse and select the source XML file for the Source XML File field. Refer to Section 8.2.1, "Creating the Input XML File" for more information on creating the XML file.

4. In the Provider Name field, enter the name of the provider. The provider name must not contain any spaces. The generator uses the value entered in this field for the provider package name.

5. Click Generate to generate the SQL file that contains the installable PL/SQL code for the provider and portlet packages. When the browser prompts you to save or open the file, choose Save.

6. In the Save dialog box, change the file extension to .sql and revise the file name as you wish.

7. Save the file.

8.2.3 Publishing the Generated PL/SQL Portlet

After you have run the PL/SQL Generator and obtained a SQL file, you still need to perform the following tasks to make the provider and portlets available to OracleAS Portal:

• Installing the Packages in the Database

• Registering the Database Provider

• Adding Your Portlet to a Page

8.3.1 Implementing the Portlet Package

To modify helloworld_portlet.pks and helloworld_portlet.pkb to create your own portlet package, perform the following steps:

1. Make copies of the package specification, helloworld_portlet.pks, and body, helloworld_portlet.pkb.

2. Rename the copies to my_first_portlet.pks and my_first_portlet.pkb, respectively.

3. Open my_first_portlet.pks in an editor and change the name of the package to my_first_portlet:

   CREATE OR REPLACE
   package my_first_portlet
   is
   ...
   
   end my_first_portlet;
   
   

4. Open my_first_portlet.pkb in an editor and repeat the change that you made in the previous step; that is, change the name of the package to my_first_portlet.

5. In my_first_portlet.pkb, find the function named get_portlet_info and modify it as follows:

   function get_portlet_info
   (
        p_provider_id in integer
       ,p_language in varchar2
   )
   return wwpro_api_provider.portlet_record
   is
       l_portlet      wwpro_api_provider.portlet_record;
   begin
       l_portlet.id := starter_provider.PORTLET_FIRST;
       l_portlet.provider_id := p_provider_id;
       l_portlet.title := 'My First Portlet';
       l_portlet.name := 'My_First_Portlet';
       ...
   
   

6. In my_first_portlet.pkb, find the procedure named show and modify it as follows:

   procedure show
   (
      p_portlet_record        wwpro_api_provider.portlet_runtime_record
   )
   is
       l_portlet      wwpro_api_provider.portlet_record;
       l_text_name in varchar2(100);
       l_text in varchar2(200);
   begin
   ...
           /*
           Display the content of the portlet in the show mode.
           Use the wwui_api_portlet.portlet_text() API when
           generating the content of the portlet so that the
           output uses the portlet CSS.
           */
           htp.p(wwui_api_portlet.portlet_text(
                p_string   =>  'Hello World - Mode Show'
               ,p_level    =>  1
               ));
           /*
           Add the functionality you want here. In this case we are adding
           a welcome message addressed to the current user.
           */
           l_text_name := 'Welcome to my first portlet ' || wwctx_api.get_user;
           l_text := wwui_api_portlet.portlet_text(
               p_string   =>  l_text_name,
               p_level    =>  1        );
           htp.p(l_text);        htp.para;
           if (p_portlet_record.has_border) then
               wwui_api_portlet.close_portlet;
           end if;
   ...
   
   

7. Save my_first_portlet.pkb.

8.3.2 Implementing the Provider Package

After you implement the portlet package, you must add your portlet to a provider. To modify starter_provider.pks and starter_provider.pkb to add your new portlet to a provider, perform the following steps:

1. Make copies of the package specification, starter_provider.pks, and body, starter_provider.pkb.

2. Rename the copies to starter_provider2.pks and starter_provider2.pkb, respectively.

   
   

   Note: If you want to create a new, empty provider, remove all references to the hello world and snoop portlets from starter_provider2.pks and starter_provider2.pkb before performing the steps that follow.

   
   

3. Open starter_provider2.pks in an editor.

4. Add a constant called PORTLET_FIRST. This constant is used as the identifier for the portlet within the provider. Hence, the constant's value must be unique within the provider.

   CREATE OR REPLACE
   package STARTER_PROVIDER
   is
     /**
       * This package is used as an example to show how providers can be created
       * in the portal system.
       *
       * This provider contains the following portlets:
       *
       * Hello World (PORTLET_HELLOWORLD)
       * Snoop (PORTLET_SNOOP)
       *
       */
       PORTLET_HELLOWORLD constant integer := 1;
       PORTLET_SNOOP      constant integer := 2;
       PORTLET_FIRST      constant integer := 3;
   
   

5. Save starter_provider2.pks.

6. Open starter_provider2.pkb in an editor.

7. In starter_provider2.pkb, add a call for the new portlet's get_portlet_info function in the get_portlet function of the provider package. This step entails adding the call my_first_portlet.get_portlet_info in the get_portlet function. The get_portlet function allows the portal to retrieve information for the portlet when necessary.

   function get_portlet
        p_provider_id in integer
       ,p_portlet_id in integer
       ,p_language in varchar2
   )
   return wwpro_api_provider.portlet_record
   is
   begin
       if (p_portlet_id = PORTLET_HELLOWORLD) then
           return helloworld_portlet.get_portlet_info(
                p_provider_id  => p_provider_id
               ,p_language     => p_language
               );
       elsif (p_portlet_id = PORTLET_SNOOP) then
           return snoop_portlet.get_portlet_info(
                p_provider_id  => p_provider_id
               ,p_language     => p_language
               );
       elsif (p_portlet_id = PORTLET_FIRST) then
           return my_first_portlet.get_portlet_info(
                p_provider_id  => p_provider_id
               ,p_language     => p_language
               );
       else
           raise wwpro_api_provider.PORTLET_NOT_FOUND_EXCEPTION;
       end if;
   end get_portlet;
   
   

8. In starter_provider2.pkb, add the new portlet to the list of portlets returned by the provider. This step entails adding the new portlet to the get_portlet_list function of the provider. The get_portlet_list function tells the portal which portlets the provider implements.

   function get_portlet_list
   ...
   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
                   );
               l_cnt := l_cnt + 1;
               l_portlet_list(l_cnt) := get_portlet(
                    p_provider_id  => p_provider_id
                   ,p_portlet_id   => PORTLET_FIRST
                   ,p_language     => p_language
                   );
       else
           if (helloworld_portlet.is_runnable(
                p_provider_id     =>  p_provider_id
               ,p_reference_path  =>  null)
           ) 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
                   );        end if;
           if (snoop_portlet.is_runnable
                p_provider_id     =>  p_provider_id
               ,p_reference_path  =>  null)
           ) then
               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
                       );
           end if;
           if (my_first_portlet.is_runnable(
                p_provider_id     =>  p_provider_id
               ,p_reference_path  =>  null)
           ) then
               l_cnt := l_cnt + 1;
               l_portlet_list(l_cnt) := get_portlet(
                    p_provider_id  => p_provider_id
                   ,p_portlet_id   => PORTLET_FIRST
                   ,p_language     => p_language
                   );
           end if;
       end if;
       return l_portlet_list;
   end get_portlet_list;
   
   

9. In starter_provider2.pkb, modify the is_portlet_runnable function to add a call to the is_runnable function of the new portlet.

   function is_portlet_runnable
   (
       p_portlet_instance in wwpro_api_provider.portlet_instance_record
   )
   return boolean
   is
   begin
       if (p_portlet_instance.portlet_id = PORTLET_HELLOWORLD) then
           return helloworld_portlet.is_runnable(
                p_provider_id     =>  p_portlet_instance.provider_id
               ,p_reference_path  =>  p_portlet_instance.reference_path
               );
       elsif (p_portlet_instance.portlet_id = PORTLET_SNOOP) then
           return snoop_portlet.is_runnable(
                p_provider_id     =>  p_portlet_instance.provider_id
               ,p_reference_path  =>  p_portlet_instance.reference_path
               );
       elsif (p_portlet_instance.portlet_id = PORTLET_FIRST) then
           return my_first_portlet.is_runnable(
                p_provider_id     =>  p_portlet_instance.provider_id
               ,p_reference_path  =>  p_portlet_instance.reference_path
               );
       else
           raise wwpro_api_provider.PORTLET_NOT_FOUND_EXCEPTION;
       end if;
   end is_portlet_runnable;
   
   

10. Repeat step 9 according to the information in Table 8-4.

    Table 8-4 Changes to starter_provider2.pkb

    Procedure/Function	Addition
    procedure register_portlet	elsif (p_portlet_instance.portlet_id = PORTLET_FIRST) then my_first_portlet.register(p_portlet_instance)
    procedure deregister_portlet	elsif (p_portlet_instance.portlet_id = PORTLET_FIRST) then my_first_portlet.deregister (p_portlet_instance)
    function describe_portlet_parameters	elsif (p_portlet_id = PORTLET_FIRST) then return my_first_portlet.describe_parameters (p_provider_id, p_language);
    procedure show_portlet	elsif (p_portlet_record.portlet_id = PORTLET_FIRST) then my_first_portlet.show(p_portlet_record)
    procedure copy_portlet	elsif (p_copy_portlet_info.portlet_id = PORTLET_FIRST) then my_first_portlet.copy(p_portlet_record)

    
    

11. Save and close starter_provider2.pkb.

12. Log in to OracleAS Portal as you normally would.

13. From the Portal Builder, click the Administer tab then the Portlets tab.

14. From the Portlet Repository portlet, click Display Portlet Repository.

15. Browse the repository and find the starter provider (typically it will appear in the Portlet Staging Area of the repository). It should contain its two original portlets: hello world and snoop.

16. From a command line prompt, start SQL*Plus and connect as the owner of the starter provider schema.

17. Compile the new and modified PL/SQL packages in the following order:

    • starter_provider2.pks

    • my_first_portlet.pks

    • starter_provider2.pkb

    • my_first_portlet.pkb

18. If any compilation errors occur, fix and recompile them until all of the packages compile successfully.

19. From the Portlet Repository portlet, click Display Portlet Repository.

20. Browse the repository and find the starter provider again. It should now contain your new portlet, my_first_portlet, in addition to its original portlets.

    
    

    Note: If you make changes to an existing provider or the portlet record, you need to refresh your provider before seeing the changes reflected in your OracleAS Portal instance.

    
    

8.3.3 Adding Your Portlet to a Page

Your portlet should now be available for adding to pages like any other portlet in the Portlet Repository. To add your portlet to a page, follow the instructions in Oracle Application Server Portal User's Guide.

8.4.1 Implementing a Preference Store

OracleAS Portal provides a set of APIs for storing and retrieving individual preferences for each unique portlet instance in a persistent manner. It provides a unique identifier for each individual, a preference store automatically mapped by user, and access mechanisms for storing and retrieving personalization information in your PL/SQL portlets.

By default, when you enable end-user personalization, Customize appears on the title bar of your portlet. This link displays a form where users can choose settings for that portlet.

End-user personalization options are available through the wwpre_api_name and wwpre_api_value packages.

8.4.2 Implementing a Session Store

The services example, located in ..\pdkplsql\pdk\plsql\svcex in PDK-PL/SQL (pdkplsql.zip), illustrates how you can implement a session store. The objective is to achieve the following functionality:

• When a user invokes this portlet, it displays text that reads: "This portlet has rendered x times in this session." x is the number of times the portlet has been rendered.

• Every time the user invokes the portlet, the counter increases by 1.

• Clicking Details in the portlet enables the user to reset the counter via Clear. After clearing the counter, the counter starts again from zero.

8.5.1 Passing Private Parameters

You can use either GET or POST HTML submission methods when passing private portlet parameters. The GET method uses the URL to pass the parameters, whereas the POST method places the parameters in an HTTP message body. For both methods, you must specify the portlet instance on the portal page, how the parameter is called, and the value of the parameter.

There are two types of private portlet parameters:

• Qualified parameters ensure that a private portlet parameter is not read by any other portlet on the page. The reference path, which is assigned when the portlet is added to a page, is the unique prefix of the parameter. For example, http://page_url?277_MAP_368673.region=Europe. The qualified parameter's reference path is 277_MAP_368673, the name is region, and the value is Europe. For private parameters, we strongly recommend that you always use qualified parameters.

• Unqualified parameters have no information about the portlet instance and can be read by any portlet on the page. For example, http://page_url?region=Europe. The unqualified parameter's name is region and its value is Europe. For private parameters, we strongly recommend that you avoid unqualified parameters.

8.5.2 Passing Page Parameters and Mapping Public Portlet Parameters

Public portlet parameters enhance the flexibility of your portlets by enabling page designers to reuse your portlets on multiple pages. As a result, page designers do not have to ask you to make changes to the portlet code when adding the portlet to different pages. By using public portlet parameters, any portlet on a page can easily receive its value from the mapped page parameter, regardless of the portlet parameter name.

For example, suppose you have a page parameter named dept_id. Three portlets need this value, but one portlet calls it dept, another calls it deptno, and still another department_id. Mapping the page parameter enables all three portlets to receive the value from the dept_id parameter and place it in the appropriate portlet parameter. Furthermore, the page designer may set a default value (for example, department 20) that can be customized by users (for example, department 30) and applied to all three portlets.

The general model for passing public and page parameters is as follows:

1. Enable public parameters in the portlet record by setting pass_all_url_params to false. This ensures that the portlet is only passed parameters intended for that portlet.

2. Declare the public parameters in the provider's describe_portlet_parameters function. For each of the portlets that belong to the provider, this procedure should return a list of the parameters that the portlet accepts in the form of a PL/SQL table of records of the type:

   type portlet_parameter_table is table ofportlet_parameter_record index by binary_integer;
   
   

3. Provide descriptive information for the parameters in the portlet's describe_parameters function. For example:

   function describe_parameters
      (p_provider_id in integer, p_language in varchar2)
   return wwpro_api_provider.portlet_parameter_table
      is
   l_params wwpro_api_provider.portlet_parameter_table;
      begin
        l_params(1).name := 'dept_id';
        l_params(1).datatype := wwpro_api_provider.STRING_TYPE;
        l_params(1).description := 'Defines a department ID';
        l_params(1).display_name := 'Department ID';
        return l_params;
   end describe_parameters;
   
   

4. Assign values to the public parameters. Public parameters typically get their values through page parameters. Page parameters are usually assigned default values by the page designer and the user can then customize the value at runtime. Alternatively, page parameter values can be assigned in the calling URL. For more information about how page designers can use page parameters, refer to the Oracle Application Server Portal User's Guide.

8.5.3 Retrieving Parameter Values

Regardless of whether you are using private or public parameters, you use the same APIs to retrieve their values. Portlets obtain their parameters by calling the PL/SQL parameter APIs in the wwpro_api_parameters package:

• wwpro_api_parameters.get_value returns the parameter value that is specified by a given parameter name. Parameter names are not case sensitive, whereas parameter values are case sensitive. For example:

  l_region := wwpro_api_parameters.get_value
     (p_name => 'region',
      p_reference_path => p_portlet_record.reference_path);
  
  

• wwpro_api_parameters.get_values returns an array of parameter values. This function returns all the values that are associated with a single parameter name or an empty list if no matches are found. Some business logic may require multiple selections, when multiple values are passed to the portlet by using the same parameter name. Portlets can take one or more values of the same parameter. For example:

  l_region_values owa.vc_arr;
  ...
  l_region_values := wwpro_api_parameters.get_values
     (p_name = 'region',
      p_reference_path => p_portlet_record.reference_path);
  
  

• wwpro_api_parameters.get_names returns the names of the parameters that are passed on to a specified portlet that is identified by the reference path. The returned list is a PL/SQL table of the owa.vc_ar type that is defined as follows:

  type vc_arr is table of varchar2(32000) index by binary_integer;
  

  
  

  Note: Portlet parameter names should not start with an underscore (_) because those parameters are reserved for internal use by OracleAS Portal and are not passed to the portlet.

  
  

  For example:

  l_names owa.vc_arr;
  ...
  l_names := wwpro_api_parameters.get_names
     (p_reference_path => p_portlet_record.reference_path);
  
  

• wwpro_api_parameters.retrieve returns the names and values of all of the portlet's parameters. For example:

  procedure show_portlet
     ( p_portlet_record in out
           wwpro_api_provider.portlet_runtime_record )
  is
     l_names owa.vc_arr;
     l_values owa.vc_arr;
  ...
  begin
  ...
     wwpro_api_parameters.retrieve (l_names, l_values);
     for i in 1..l_names.count loop
       htp.p('Parameter Name: '||l_names(i));
       htp.p('Parameter Value: '||l_values(i));
       htp.br;
     end loop;
  ...
  end show_portlet;
  

8.6.1 Using Context Information

The general model for working with the session context is as follows:

1. Identify the piece of information you require for your functionality.

2. Use the appropriate method from wwctx_api to get and optionally set this value.

Table 8-5 lists the function calls used to obtain the various pieces of session information.

8.6.2 Using wwctx_api to Obtain Context Information

The services example, located in ..\pdkplsql\pdk\plsql\svcex in PDK-PL/SQL (pdkplsql.zip), illustrates how you can obtain session information using the wwwctx_api package. You can browse through this example as follows to see how the function calls are implemented in a portlet:

1. Open the services_portlet.pkb file in an editor.

2. Find the get_portlet_info function.

3. Notice the usage of wwctx_api.get_user to derive the user information and set that value in the portlet information record:

   ...
       l_portlet.timeout              := null;
       l_portlet.timeout_msg          := null;
       l_portlet.created_on           := to_date('10/19/2000', 'MM/DD/YYYY');
       l_portlet.created_by           := wwctx_api.get_user;
       l_portlet.last_updated_on      := to_date('10/19/2000', 'MM/DD/YYYY');
       l_portlet.last_updated_by      := wwctx_api.get_user;
       l_portlet.has_show_edit_defaults := true;
       l_portlet.has_show_preview     := true;
       l_portlet.preference_store_path := PORTLET_PATH;
   ...
   
   

4. wwctx_api.get_user is used similarly in various places throughout services_portlet.pkb. Search the code for other occurrences of wwctx_api.get_user.

5. Another example of getting context information occurs in the is_runnable function:

   function is_runnable
   (
        p_provider_id in integer
       ,p_reference_path in varchar2
   )
   return boolean
   is
   begin
       --
       -- Portlet security check.  It allows the portlet to be visible
       -- if the user is logged on, i.e. the current session is not a
       -- public session.
       --
       return wwctx_api.is_logged_on;
   end is_runnable;
   
   

6. In the register procedure, wwctx_api.get_nls_language is used to get the language:

       --
       -- Create the names to store the portlet preferences.
       --
       wwpre_api_name.create_name(
           p_path        => PORTLET_PATH
               || p_portlet_instance.reference_path,
           p_name        => PREFNAME_STRING,
           p_description => 'Single custom row in '
               || 'Introductory Example portlet.',
           p_type_name   => 'NLSID',
           p_language    => wwctx_api.get_nls_language);
       wwpre_api_name.create_name(
           p_path        => PORTLET_PATH
               || p_portlet_instance.reference_path,
           p_name        => PREFNAME_TITLE,
           p_description => 'Single custom row in '
               || 'Introductory Example portlet.',
           p_type_name   => 'NLSID',
           p_language    => wwctx_api.get_nls_language);
   
   

7. Close services_portlet.pkb. You can implement session context similarly but based upon your own functional requirements.

8. Optionally, if you want to see this portlet on a page and it is not already in the Portlet Repository, refer to the instructions in Section 8.3.2, "Implementing the Provider Package" for information on how to add it.

9. Once your portlet appears in the repository, you can add it to a page to test it. To add your portlet to a page, follow the instructions in Oracle Application Server Portal User's Guide.

8.7.1 Using Security

To implement PL/SQL portlet security, the portal requires the function is_portlet_runnable be implemented by database providers. The actual implementation of this function is up to the application; that is, the security scheme that determines whether the current user has enough privileges to access the portlet is defined by the individual portlet implementation. The portal also requires the function get_portlet_list for database providers to return the set of portlets that are accessible by the current user.

8.7.2 Coding Security

The services example, located in ..\pdkplsql\pdk\plsql\svcex in PDK-PL/SQL (pdkplsql.zip), illustrates how you can implement security. You can browse through this example as follows to see how the security functions are implemented in a portlet:

1. Open the services_provider.pkb file in an editor.

2. Find the is_portlet_runnable function. This function calls the security implementation through the portlet's is_runnable function to check portlet access privileges.

   function is_portlet_runnable
   (
       p_portlet_instance in wwpro_api_provider.portlet_instance_record
   )
   return boolean
   is
   begin
       if (p_portlet_instance.portlet_id = SERVICES_PORTLET_ID) then
           return services_portlet.is_runnable(
                p_provider_id     =>  p_portlet_instance.provider_id
               ,p_reference_path  =>  p_portlet_instance.reference_path
               );
       else
           raise wwpro_api_provider.PORTLET_NOT_FOUND_EXCEPTION;
       end if;
   end is_portlet_runnable;
   
   

3. Find the get_portlet_list procedure. get_portlet_list allows the portlet to be included in the list of portlets implemented by this provider. get_portlet_list first checks the security flag (p_security_level) to find out whether security is enabled. If the flag is set to true, get_portlet_list uses is_runnable to check whether the portlet is accessible. The value of the p_security_level parameter indicates whether to perform security checks before returning a portlet in the list. When a portlet repository refresh operation retrieves the master list of portlets implemented by the provider, p_security_level has a value of false. A value of false means the provider does not need to perform a security check 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 the provider implementation decides whether to perform portlet security checks. If portlet security is implemented, the provider may return a different list of portlets depending on the currently logged on user.

   function get_portlet_list
   ...
       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   => SERVICES_PORTLET_ID
               ,p_language     => p_language
               );
       else
           if (services_portlet.is_runnable(
                p_provider_id     =>  p_provider_id
               ,p_reference_path  =>  null)
           ) then
               l_cnt := l_cnt + 1;
               l_portlet_list(l_cnt) := get_portlet(
                    p_provider_id  => p_provider_id
                   ,p_portlet_id   => SERVICES_PORTLET_ID
                   ,p_language     => p_language
                   );        end if;
   ...
   end get_portlet_list;
   
   

4. Open the services_portlet.pkb file in an editor.

5. Find the show procedure. Before displaying a portlet, the show procedure runs a security check to determine whether the current user is allowed to see the portlet.

   procedure show
   ...
       -- Perform a security check
       if (not is_runnable(
            p_provider_id     =>  p_portlet_record.provider_id
           ,p_reference_path  =>  p_portlet_record.reference_path)
       ) then
           wwerr_api_error.add(
                     DOMAIN, SUBDOMAIN,
                     'securityerr', 'services_portlet.show');
           raise wwpro_api_provider.PORTLET_SECURITY_EXCEPTION;    end if;
   ...
   end show;
   
   

6. Find the is_runnable function. is_runnable is the place where you implement your security checks. In this example, the security check is quite simple. If the user is logged on (that is, not in a public session), then the function returns true and the portlet is displayed to the user. For your own purposes, you could, of course, code much more complex security checks in the is_runnable function.

   function is_runnable
   (
        p_provider_id in integer
       ,p_reference_path in varchar2
   )
   return boolean
   is
   begin
       --
       -- Portlet security check.  It allows the portlet to be visible
       -- if the user is logged on, i.e. the current session is not a
       -- public session.
       --
       return wwctx_api.is_logged_on;
   end is_runnable;
   
   

7. Optionally, if you want to see this portlet on a page and it is not already in the Portlet Repository, refer to the instructions in Section 8.3.2, "Implementing the Provider Package" for information on how to add it.

8. Once your portlet appears in the repository, you can add it to a page to test it. To add your portlet to a page, follow the instructions in Oracle Application Server Portal User's Guide.

8.8.1 Using Caching

The general model for working with portlet caching varies according to the type of caching you choose. To a great extent, the type of caching you choose depends on the portlet content. If the portlet content changes at fairly regular intervals (for example, at the close of business every day), then it probably makes sense to use expiry-based caching. If the portlet content changes at irregular intervals, then validation- or invalidation-based caching is probably best.

8.8.2 Configuring and Monitoring the Cache

The Oracle Application Server Portal Configuration Guide describes how to configure caching as well as how to monitor and tune performance.

8.8.3 Implementing Validation-Based Caching

The caching example, located in ..\pdkplsql\pdk\plsql\cache in PDK-PL/SQL (pdkplsql.zip), illustrates how you can implement validation and expiry-based caching. You can browse through this example as follows to see how the validation-based functions are implemented in a portlet:

1. Open the validcache_portlet.pkb file in an editor.

2. At the very top of the file, notice the aliases for the caching level constants.

   CREATE OR REPLACE
   package body VALIDCACHE_PORTLET
   is
       -- Caching Constants
       CACHE_LEVEL_SYSTEM constant varchar2(10) := 'SYSTEM';
       CACHE_LEVEL_USER   constant varchar2(10) := 'USER';
   
   

3. Find the show procedure. Notice first that the p_portlet_record is an in and out parameter for this procedure.

   procedure show
   (
       p_portlet_record   in out     wwpro_api_provider.portlet_runtime_record
   )
   
   

4. In the procedure's security check, the caching fields of p_portlet_record are set to null if the security check fails.

   begin
       if (not is_runnable(
            p_provider_id      => p_portlet_record.provider_id
           ,p_reference_path   => p_portlet_record.reference_path)
       ) then
           -- Set it to null so that cache does not get used even if exists
           p_portlet_record.caching_level := null;
           p_portlet_record.caching_key := null;
           raise wwpro_api_provider.PORTLET_SECURITY_EXCEPTION;    end if;
   
   

5. After that, the procedure calls the get_cache_key function to get the cache key's value and assign it to a temporary value:

       --
       -- CACHE IS VALID?
       --
       l_cache_key := get_cache_key();
   
   

6. Find the get_cache_key function, which is referenced from the show procedure. This function generates a key for the portlet. You can implement your own logic here based upon your portlet's requirements.

   function get_cache_key return varchar2 is    l_date date;begin    select sysdate into l_date from  dual;    return trim(substr(to_char(l_date, 'YYYY:MM:DD:HH:MI:SS'),1,18));exception    when others then        null;end get_cache_key;
   
   

7. Now return to the show procedure. Notice how the code checks your portlet_runtime_record parameter for the current values of the caching_key and the caching_level. This same piece of code can compare your caching_key values.

       if p_portlet_record.caching_level = CACHE_LEVEL_SYSTEM then
           if l_cache_key is not null then
               -- Cache exists for the user, overwrite it
               p_portlet_record.caching_level := CACHE_LEVEL_USER;
               p_portlet_record.caching_key := l_cache_key;
           else
               return; -- System cache is still valid.
           end if;
       elsif p_portlet_record.caching_level = CACHE_LEVEL_USER then
           if p_portlet_record.caching_key != l_cache_key then
               -- cache has expired. reset it
               p_portlet_record.caching_key := l_cache_key;
           else 
               return; -- User cache is good as gold
           end if;
       elsif p_portlet_record.caching_level is null then
           if p_portlet_record.caching_key is not null then
               -- Cache does not exists for the user, create it
               p_portlet_record.caching_level := CACHE_LEVEL_USER;
               p_portlet_record.caching_key := l_cache_key;
           else
               -- Define a sytem cache. This can happen only once!
               -- the first time the portlet is rendered.
               p_portlet_record.caching_level := CACHE_LEVEL_SYSTEM;
               p_portlet_record.caching_key := 'MY_INITIAL_CACHE_KEY';   
           end if;
       else 
           p_portlet_record.caching_level := CACHE_LEVEL_SYSTEM;
           p_portlet_record.caching_key := 'MY_INITIAL_CACHE_KEY';
       end if;
   
   

8. Optionally, if you want to see this portlet on a page and it is not already in the Portlet Repository, refer to the instructions in Section 8.3.2, "Implementing the Provider Package" for information on how to add it.

9. Once your portlet appears in the repository, you can add it to a page to test it. To add your portlet to a page, follow the instructions in Oracle Application Server Portal User's Guide.

8.8.4 Implementing Expiry-Based Caching

The caching example, located in ..\pdkplsql\pdk\plsql\cache in PDK-PL/SQL (pdkplsql.zip), illustrates how you can implement expiry-based caching. You can browse through this example as follows to see how the expiry-based functions are implemented in a portlet:

1. Open the expirycache_portlet.pkb file in an editor.

2. At the very top of the file, notice the aliases for the caching level constants.

   CREATE OR REPLACE
   package body VALIDCACHE_PORTLET
   is
       -- Caching Constants
       CACHE_LEVEL_SYSTEM constant varchar2(10) := 'SYSTEM';
       CACHE_LEVEL_USER   constant varchar2(10) := 'USER';
   
   

3. Find the show procedure. Notice first that the p_portlet_record is an in and out parameter for this procedure.

   procedure show
   (
       p_portlet_record   in out     wwpro_api_provider.portlet_runtime_record
   )
   
   

4. In the procedure's security check, the caching fields of p_portlet_record are set to null if the security check fails.

   begin
       if (not is_runnable(
            p_provider_id      => p_portlet_record.provider_id
           ,p_reference_path   => p_portlet_record.reference_path)
       ) then
           -- Set it to null so that cache does not get used even if exists
           p_portlet_record.caching_level := null;
           p_portlet_record.caching_key := null;
           raise wwpro_api_provider.PORTLET_SECURITY_EXCEPTION;    end if;
   
   

5. After that, the procedure sets the value of the caching period in minutes in a temporary variable. The get_cache_key function to get the cache key's value and assign it to a temporary value:

      -- Set the Caching Period to one minute 
      l_cache_period := 1;
   
   

6. Next, notice how the code checks your portlet_runtime_record parameter for the current values of the caching_period and sets the caching_period accordingly. This same piece of code can compare your caching_period values.

      if p_portlet_record.caching_level = CACHE_LEVEL_SYSTEM then
               -- Cache does not exists for the user, create it
               p_portlet_record.caching_level := CACHE_LEVEL_USER;
               p_portlet_record.caching_period := l_cache_period;
      elsif p_portlet_record.caching_level = CACHE_LEVEL_USER then
               -- Cache exists for the user, overwrite it
               p_portlet_record.caching_period := l_cache_period;
      elsif p_portlet_record.caching_level is null then
           if p_portlet_record.caching_period  is not null then
               -- Cache does not exists for the user, create it
               p_portlet_record.caching_level := CACHE_LEVEL_USER;
               p_portlet_record.caching_period := l_cache_period;
           else
               -- Define a sytem cache. This can happen only once!
               p_portlet_record.caching_level := CACHE_LEVEL_SYSTEM;
               p_portlet_record.caching_period := l_cache_period;   
           end if;
      else -- p_portlet_record.caching_level value is messed up!
           p_portlet_record.caching_level := CACHE_LEVEL_SYSTEM;
           p_portlet_record.caching_period := l_cache_period;   end if;
   
   

7. Optionally, if you want to see this portlet on a page and it is not already in the Portlet Repository, refer to the instructions in Section 8.3.2, "Implementing the Provider Package" for information on how to add it.

8. Once your portlet appears in the repository, you can add it to a page to test it. To add your portlet to a page, follow the instructions in Oracle Application Server Portal User's Guide.

8.8.5 Implementing Invalidation-Based Caching

Suppose you have a portlet that displays a map of the world, map_portlet.pkb and map_portlet.pks. You would go about adding invalidation-based functions to it as follows:

1. In the show procedure, you need to add a call to wwpro_api_provider.use_invalidation. This call indicates to OracleAS Portal that the portlet content should be cached by OracleAS Web Cache. Note that we have also specified that the content be cached at the user level and that expiry-based caching be used as well (that is, an expiration interval of one minute has been set).

   procedure show
   ...
       if (p_portlet_record.exec_mode = wwpro_api_provider.MODE_SHOW) then
           p_portlet_record.caching_invalidation := 
             wwpro_api_provider.use_invalidation;
           p_portlet_record.caching_level := 'USER';
           p_portlet_record.caching_period := 1;
   ...
   
   

2. Create a procedure in your map_portlet.pkb file that invalidates the cache. For example:

   procedure map_invalidation
   (  
   p_provider_id in number,
   p_portlet_id in number,
   p_instance_id in varchar2,
   p_page_url in varchar2
   )
   is
   begin
    wwpro_api_invalidation.invalidate_by_instance
     (p_provider_id => p_provider_id,
      p_portlet_id =>  p_portlet_id,
      p_instance_id => p_instance_id,
      p_user => wwctx_api.get_user);
    owa_util.redirect_url(p_page_url);
   end map_invalidation;
   
   

3. In the show procedure, add a link for refreshing the portlet before the code that draws the map. For example:

   /* Draw the Refresh Me link */
   htp.anchor(
     curl => wwctx_api.get_user||
       '.map_invalidation?p_provider_id='||p_portlet_record.provider_id||
       '&p_portlet_id='||p_portlet_record.portlet_id||
       '&p_instance_id='||p_portlet_record.reference_path||
       '&p_page_url='||utl_url.escape(
                       url => p_portlet_record.page_url,
                       escape_reserved_chars => TRUE),
     ctext => wwui_api_portlet.portlet_text(
       p_string =>'Refresh Me',
       p_level => 1)
   );
   
   

4. Optionally, if you want to see this portlet on a page and it is not already in the Portlet Repository, refer to the instructions in Section 8.3.2, "Implementing the Provider Package" for information on how to add it.

5. Once your portlet appears in the repository, you can add it to a page to test it. To add your portlet to a page, follow the instructions in Oracle Application Server Portal User's Guide.

8.9.1 Using Error Handling

In general, you set up error handling as follows:

1. On detecting error conditions, add the error message, with an appropriate domain and sub-domain combination, to the stack using the wwerr_api_error.add procedure.

2. When necessary (for example, at the end of a routine), expose the error messages using the wwerr_api_error_ui procedures. To display full screen messages, use the procedures show_html, show_xml, or show_text depending on your preferred output type. To display inline messages, use the procedures show_inline_html, show_inline_xml, or show_inline_text, depending on the output type you desire.

8.9.2 Adding Error Handling

The services example, located in ..\pdkplsql\pdk\plsql\svcex in PDK-PL/SQL (pdkplsql.zip), illustrates how you can implement error handling. You can browse through the following example to see how the error handling functions are implemented in a portlet:

1. Open the services_portlet.pkb file in an editor.

2. The domain and subdomain definitions for your error messages are provided with aliases in the constants part of your portlet definition.

   DOMAIN           constant varchar2(30) := 'provider';
   SUBDOMAIN        constant varchar2(32) := 'services';
   PORTLET_PATH     constant varchar2(256):= 'oracle.portal.pdk.servicesportlet';
   PREFNAME_STRING  constant varchar2(30) := 'services_string';
   PREFNAME_TITLE   constant varchar2(30) := 'services_title';
   
   

3. Find the show procedure. This procedure performs a security check and, if an error condition arises, it calls wwerr_api_error.add to push the securityerr error message onto the stack.

   procedure show
   (
       p_portlet_record        wwpro_api_provider.portlet_runtime_record
   )
   is
   ...
   begin
       -- Perform a security check
       if (not is_runnable(
            p_provider_id     =>  p_portlet_record.provider_id
           ,p_reference_path  =>  p_portlet_record.reference_path)
       ) then
           wwerr_api_error.add(
                     DOMAIN, SUBDOMAIN,
                     'securityerr', 'services_portlet.show');
           raise wwpro_api_provider.PORTLET_SECURITY_EXCEPTION;
       end if;
   
   

4. The show procedure also checks for any other kind of execution mode and generates an appropriate error message for an invalid display mode.

   if (p_portlet_record.exec_mode = wwpro_api_provider.MODE_SHOW) then
   ...
   elsif (p_portlet_record.exec_mode = wwpro_api_provider.MODE_SHOW_EDIT)
   ...
   else
       wwerr_api_error.add(DOMAIN, SUBDOMAIN,
           'invaliddispmode', 'services_portlet.show');
       raise wwpro_api_provider.PORTLET_EXECUTION_EXCEPTION;
   end if;
   
   

5. Lastly, the show procedure implements a general error message in the exception handler to catch any errors not trapped by the preceding conditions.

   exception
       when others then
           wwerr_api_error.add(
               DOMAIN, SUBDOMAIN,
               'generalerr', 'services_portlet.show');
           raise wwpro_api_provider.PORTLET_EXECUTION_EXCEPTION;
   end show;
   
   

6. Error handling is also implemented in the save_prefs and save_default_prefs procedures. They check whether the error stack is empty and, if it is not, the portlet makes a call to wwerr_api_error.show_html to display the error in full screen mode.

   exception
       when INVALID_TEXT_EXCEPTION then
            l_information := l_user||'%'||l_time
                ||'%INVALID_TEXT_EXCEPTION%'||p_string;
            l_action      := LOG_FAILED;
            wwlog_api.log (p_domain      => DOMAIN,
                           p_subdomain   => SUBDOMAIN,
                           p_name        => l_user,
                           p_action      => l_action,
                           p_information => l_information,
                           p_url         => l_url,
                           p_row_count   => 0,
                           p_elapsed_time=> l_elapsed_time);
            wwerr_api_error.add(DOMAIN, SUBDOMAIN,
                'invalid_text', 'services_portlet.save_prefs');
        if (not wwerr_api_error.is_empty) then
            wwerr_api_error_ui.show_html;
        end if;
   end save_prefs;
   
   

7. Optionally, if you want to see this portlet on a page and it is not already in the Portlet Repository, refer to the instructions in Section 8.3.2, "Implementing the Provider Package" for information on how to add it.

8. Once your portlet appears in the repository, you can add it to a page to test it. To add your portlet to a page, follow the instructions in Oracle Application Server Portal User's Guide.

8.10.1 Using Event Logging

In general, you can set up event logging as follows:

1. Add the event object, with an appropriate domain and subdomain combination, using wwlog_api_admin.add_log_event. Adding the event ensures that lists of values and other user interface components invoked when the user is monitoring the events show this new event in their lists.

2. Register the log event record by using wwlog_api_admin.add_log_registry. The log registry record represents the events you want to log in the future and provides a means to filter the events that need to be logged.

3. Use start_log and stop_log to mark the events you want to log in your code. Alternatively, for entering single step event log information, just call the log method to mark that event.

8.10.2 Adding Event Logging

The services example, located in ..\pdkplsql\pdk\plsql\svcex in PDK-PL/SQL (pdkplsql.zip), illustrates how you can implement event logging. You can browse through this example as follows to see how the event logging functions are implemented in a portlet:

1. Open the services_portlet.pkb file in an editor.

   The domain and subdomain definitions for your log messages are provided with aliases in the constants part of your portlet definition.

   DOMAIN           constant varchar2(30) := 'provider';
   SUBDOMAIN        constant varchar2(32) := 'services';
   PORTLET_PATH     constant varchar2(256):= 'oracle.portal.pdk.servicesportlet';
   PREFNAME_STRING  constant varchar2(30) := 'services_string';
   PREFNAME_TITLE   constant varchar2(30) := 'services_title';
   
   

2. Find the save_prefs procedure. This procedure provides customizable functionality where you can personalize text and the portlet title in Edit mode. save_prefs stores these customizations in the database. While saving the changes, you should also log them. Hence, this procedure provides an ideal example of implementing the logging service. A single step event is logged using wwlog_api.log. The first instance of wwlog_api.log logs the event of personalizing text. The second instance logs the event of personalizing the portlet title.

   procedure save_prefs
   ...
   begin
   ...
       if (l_prefs.string_id is null or to_number(l_prefs.string_id) = 0)
       then
           l_action := LOG_INSERT;
   ...
       else  -- string exists in at least one language so update it
           l_action := LOG_UPDATE;
   ...
       end if;
   -- Log this transaction
   l_information := l_user||'%'||l_time||'%completed%'||p_string;
           wwlog_api.log (p_domain      => DOMAIN,
                          p_subdomain   => SUBDOMAIN,
                          p_name        => l_user,
                          p_action      => l_action,
                          p_information => l_information,
                          p_url         => l_url,
                          p_row_count   => l_row_count,
                          p_elapsed_time=> l_elapsed_time);
   ...
       if (l_prefs.title_id is null or to_number(l_prefs.title_id) = 0)
       then
          l_action := LOG_INSERT;
   ...
       else
          l_action := LOG_UPDATE;
   ...
   -- Log this transaction       l_information := l_user||'%'||l_time||'%completed%'||p_title;
          wwlog_api.log (p_domain      => DOMAIN,
                          p_subdomain   => SUBDOMAIN,
                          p_name        => l_user,
                          p_action      => l_action,
                          p_information => l_information,
                          p_url         => l_url,
                          p_row_count   => l_row_count,
                          p_elapsed_time=> l_elapsed_time);
   ...
   end save_prefs;
   
   

3. The save_prefs procedure also logs an event with wwlog_api.log when an exception occurs.

   exception
       when INVALID_TEXT_EXCEPTION then
            l_information := l_user||'%'||l_time
                ||'%INVALID_TEXT_EXCEPTION%'||p_string;
            l_action      := LOG_FAILED;
            wwlog_api.log (p_domain      => DOMAIN,
                           p_subdomain   => SUBDOMAIN,
                           p_name        => l_user,
                           p_action      => l_action,
                           p_information => l_information,
                           p_url         => l_url,
                           p_row_count   => 0,
                           p_elapsed_time=> l_elapsed_time);
   ...
   
   

4. Optionally, if you want to see this portlet on a page and it is not already in the Portlet Repository, refer to the instructions in Section 8.3.2, "Implementing the Provider Package" for information on how to add it.

5. Once your portlet appears in the repository, you can add it to a page to test it. To add your portlet to a page, follow the instructions in Oracle Application Server Portal User's Guide.

8.11.1 Using Multilingual Support

In general, you can set up multilingual support as follows:

1. Load your string definitions into the database using the string equivalents for each language you intend to use. For this purpose, call the wwnls_api.add_string or wwnls_api.set_string with an appropriate domain, subdomain, error message name, and error text combination.

2. Retrieve the strings you require with wwnls_api.get_string for the language that you desire.

8.11.2 Adding Multilingual Support

To add multilingual support, you need to perform the following tasks:

• Loading Language Strings

• Retrieving Language Strings

8.12.1 Accessing the DeviceClass Header

To further facilitate the creation of mobile-enabled portlets, you can access information in the DeviceClass header, which is sent to all portlets, via owa_util.get_cgi_env('x-oracle-device.class'). You can use the values of this header to determine the complexity of the OracleAS Wireless XML rendition of the portlet. For example, the PDA rendition could contain considerably richer content than the microbrowser rendition. The voice rendition could contain extra tags for voice commands and links to sound files, which play instead of the text-to-speech system.

Table 8-7 describes the values available in the header.

voice

microbrowser

pdabrowser

pcbrowser

8.13.1 Registration Prerequisites

In order to register a provider programmatically with wwpro_api_provider_registry.register_provider, the following requirements must be met:

• You must first install the provider as described in Section 8.2.3.1, "Installing the Packages in the Database".

• You must have the necessary privileges to execute wwpro_api_provider_registry.register_provider. As it is a secure API, a security check determines whether the user calling it has the necessary privileges. At a minimum, you must have wwsec_api.ANYPROVIDER_PUBLISH. If you have the privileges to execute the API, you also have sufficient privileges to set the OracleAS Portal session via wwctx_api.set_context.

8.13.2 Provider Record Input

The wwpro_api_provider_registry.register_provider API requires the provider_record as input. When you pass the provider_record to register_provider, all of the fields are not required. Table 8-8 indicates which fields are required for Web and database providers. If a field is not applicable for a particular type of provider, it is shown as NA.

name

implementation_style

wwpro_api_provider_registry.
   DATABASE_IMPL;

implementation_owner

implementation_name

login_frequency

http_app_type

wwpro_api_provider_registry.HTTP_APP_TYPE_EXTERNAL

wwpro_api_provider_registry.HTTP_APP_TYPE_PORTAL

http_url

require_url

encryption_key

8.13.3 Registration Example

The following sample SQL script illustrates the usage of wwpro_api_provider_registry.register_provider.

set serveroutput on size 1000000
set define on
declare
    l_prov_rec     wwpro_api_provider_registry.provider_record;
    l_prov_id      integer;
begin
    l_prov_rec.name                 := 'CacheProvider';
    l_prov_rec.display_name         := 'Cache Provider';
    l_prov_rec.timeout              := 10;
    l_prov_rec.timeout_msg          := 'The provider timed out';
    l_prov_rec.implementation_style := wwpro_api_provider_registry.DATABASE_IMPL;
    l_prov_rec.implementation_owner := '&&2';
    l_prov_rec.implementation_name  := 'cache_provider';
    l_prov_rec.language             := wwctx_api.get_nls_language;
    l_prov_rec.enable_distribution  := true;
    l_prov_rec.login_frequency      := wwpro_api_provider_registry.LOGIN_
                                         FREQUENCY_NEVER;
    l_prov_rec.created_on           := sysdate;
    l_prov_rec.created_by           := '&&1';
    l_prov_rec.last_updated_on      := sysdate;
    l_prov_rec.last_updated_by      := '&&1';
    l_prov_id := wwpro_api_provider_registry.register_provider(l_prov_rec);
    commit;
    dbms_output.put_line('Cache Provider successfully registered');
exception
    when others then
        dbms_output.put_line('ERROR: Could not register Cache Provider');
        dbms_output.put_line('SQLERRM: ' || SQLERRM);
        rollback;
end;
/