Implementing Invalidation-Based Caching Improving Portlet Performance with Caching

8-38 Oracle Fusion Middleware Developers Guide for Oracle Portal – Domain is the area of the product where the error occurred. – Subdomain is the subsystem where the error occurred. – Context is the name of the function where the error occurred. The name space uniquely identifies your error message. If it does not do so, a wwc-0000 error message is generated. The default domains include the portal WWC, application WWV, and page groups WWS. Each domain is further classified into subdomains, which define the object types. The portal domain includes the portlet, page, and document object types. The application domain includes object types such as forms, menus, reports, and charts. The page group domain includes object types such as pages, items, categories, and perspectives. If you need to define an error that does not fall within these classifications, you can define your own domain with subdomains for your errors. ■ Message parameters . The other language strings that you create for your errors can take substitution parameters for your messages. The p1, p2, p3... parameters can be used to pass substitution parameters to the error messages. For example, for this string: domain=yahoo, subdomain=provider, name=generalerror, string=Error: 1 an error can be added as follows: wwerr_api_error.addp_domain=yahoo, p_sub_domain=provider, p_name=generalerror, p_context=yahoo.show, p1= sqlerrm; ■ Error display . The wwerr_api_error_ui package provides a means to generate a standard user interface for displaying the errors in Oracle Portal. The error messages can be displayed in the following two ways: – Full screen user interface: These error messages are displayed in a full screen mode. You may want to display full screen errors when the system encounters fatal or show-stopper errors. – Inline user interface: These error messages are displayed within the current page itself. You may use inline errors for minor errors or warnings. Additionally, you can choose the output format of the display HTML, XML, or ASCII text.

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. Guidelines for Error Handling While implementing error handling, keep in mind the following: Creating PLSQL Portlets 8-39 ■ While defining your own error messages, use your own error domain for these messages. Never use the WWC, WWV, or WWS domain for your error messages. You will need to write a small loader script to load these into the other language tables. ■ Avoid unnecessary error messages. If you do not want to do anything in a function, just return null rather than an error. For example, suppose you are coding a copy_portlet procedure for your portlet because the provider calls it for all of its other portlets. If you do not wish the copy_portlet procedure for this particular portlet to do anything, then simply have it return null. If you return errors, it will unnecessarily disrupt the portlet functionality. ■ A maximum of ten error messages is kept on the stack. Beyond ten, messages are ignored when a call to wwerr_api_error.add is made. ■ Use the API as a programmatic way of finding the problem. You can use the non-user-interface format for this purpose. For example, when you programmatically register a provider, the exception block can use get_text_ stack to get the error messages and print them. This approach helps when debugging calls to public APIs since all of them add errors to the stack for exceptions. ■ Remember to seed the other language strings for your error messages. For more information, refer to Section 8.11, Writing Multilingual Portlets . ■ The standard user interface for error messages provides a navigation link back to the previous page. It also includes a Help icon for the specified help URL.

8.9.2 Adding Error Handling

The services example, located in ..\pdkplsql\pdk\plsql\svcex in PDK-PLSQL 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 varchar230 := provider; SUBDOMAIN constant varchar232 := services; PORTLET_PATH constant varchar2256:= oracle.portal.pdk.servicesportlet; PREFNAME_STRING constant varchar230 := services_string; PREFNAME_TITLE constant varchar230 := 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