Oracle9iAS Portal Developer Kit (PDK)
Implementing Error Handling in PL/SQL Portlets

Introduction

Oracle9iAS Portal provides a set of APIs for generating your error messages and presenting these errors in standard ways in your PL/SQL portlets. For an introductory overview of Error Handling Services, please refer to the Primer on Error Handling.

Error handling services are available through the wwerr_api and wwerr_api_error_ui packages.

Assumptions

• You have already installed the Services Example downloaded from the PDK and understand the steps required to display a PL/SQL portlet on a portal page.
• You have read the Primer on Error Handling document for an introduction to this service.

How to use Error Handling

The general model for working with the error handling can be described as follows:

1. On detecting erroneous conditions, add the error message by name, with the appropriate domain and sub-domain combination, using the wwerr_api_error.add method. This adds the error message to the stack.
2. At the end of a routine, or as per your requirement, expose the error messages using the wwerr_api_error_ui calls.
   • To display full screen messages, use the methods show_html, show_xml or show_text depending on the output type you desire.
   • To display inline messages, use the methods show_inline_html, show_inline_xml or show_inline_text depending on the output type you desire.

Note: Remember to seed the NLS strings for your error messages. The document on Implementing NLS Service describes how string definitions are loaded into the database.

The standard UI for error messages also provides a navigation link to go back to the previous page. It also includes a 'Help' icon to link to the specified Help URL.

Implementing Error Handling

1. From the downloaded Services Example, review the services_portlet.pkb file which is the package body for this portlet. An excerpt is provided below.
2. The domain, and sub-domain definitions for your error messages are provided aliases at the start. This code segment is highlighted below. You may choose your own domain and sub-domain names too instead.
3. Scroll the file to the section that contains the procedure get_portlet_info. The portlet performs the security check of calling is_portlet_runnable here, and on erroneous condition makes a call to wwerr_api_error.add for pushing securityerr error message on the stack. This code segment is highlighted below.

   CREATE OR REPLACE package body SERVICES_PORTLET is -- Constants -- DOMAIN constant varchar2(30) := 'provider'; SUBDOMAIN constant varchar2(32) := 'services'; 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 -- Perform the Security Check if not is_runnable(p_provider_id, null) then wwerr_api_error.add(DOMAIN, SUBDOMAIN, 'securityerr', 'services_portlet.get_portlet_info'); raise wwpro_api_provider.PROVIDER_SECURITY_EXCEPTION; end if; ... end SERVICES_PORTLET; /

4. There is a similar error message in the security check of the show procedure.
5. Additionally the portlet checks for any other kind of execution mode and generates appropriate error message for invalid display mode.
6. You can also add general error messages in the exception handler for other errors as shown below.

   CREATE OR REPLACE package body SERVICES_PORTLET is ... procedure show ( p_portlet_record wwpro_api_provider.portlet_runtime_record ) is l_portlet wwpro_api_provider.portlet_record; begin -- Perform the Security Check if not is_runnable(p_provider_id, null) then wwerr_api_error.add(DOMAIN, SUBDOMAIN, 'securityerr', 'services_portlet.show'); raise wwpro_api_provider.PROVIDER_SECURITY_EXCEPTION; end if; ... if (p_portlet_record.exec_mode = wwpro_api_provider.MODE_SHOW) then ... elsif (p_portlet_record.exec_mode = wwpro_api_provider.MODE_PREVIEW) then /* Display the preview page for the portlet. */ ... else wwerr_api_error.add(DOMAIN, SUBDOMAIN, 'invaliddispmode', 'services_portlet.show'); raise wwpro_api_provider.PROVIDER_EXECUTION_EXCEPTION; end if; EXCEPTION when others then wwerr_api_error.add(DOMAIN, SUBDOMAIN, 'generalerr', 'services_portlet.show'); raise wwpro_api_provider.PROVIDER_EXECUTION_EXCEPTION; end show; end SERVICES_PORTLET; /

7. Error handling is also implemented in the save_prefs and save_default_prefs procedures as illustrated below. It checks whether the error stack is not empty, and then calls the wwerr_api_error.show_html call to display the error in full screen mode.

   CREATE OR REPLACE package body SERVICES_PORTLET is ... procedure save_prefs ( ... ) ... return wwpro_api_provider.portlet_record is l_portlet wwpro_api_provider.portlet_record; begin ... exception when INVALID_TEXT_EXCEPTION then ... 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; ... end SERVICES_PORTLET; /

View Portlet functionality

1. Create a page and add the Services portlet to your page. Take note to view the error messages you generated by creating the error conditions. Click on the 'Customize' button and enter invalid text in the Portlet title text (for example '#?!*%') and notice the full screen error message.