Adding Error Handling Implementing Error Handling

Creating PLSQL Portlets 8-41 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 Fusion Middleware Users Guide for Oracle Portal.

8.10 Implementing Event Logging

Oracle Portal can log events that occur during transactions with its objects. It stores these logs in the database, which makes them available through standard SQL calls and reporting tools. You can choose the events you would like to log and organize them categorically based on user-defined domains and subdomains. For the logged events, you can view information about the event, the time the event started and stopped, the host or IP address of the remote user, the browser type, and the language. Event logging services are available through the wwlog_api and wwlog_api_admin packages. These services include the following key features: ■ Event logs are useful for tracking specific usage of the portal. To track such information, you create a log event. Log events require a name space that consists of the following: – Name , which is the event name. – Domain , which is the area of the product where the event occurred. – Subdomain , which is the subsystem that generated the event. The default domains include the portal WWC, application WWV, and page group WWS. Each domain is further classified into subdomains that 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 folders, items, categories, and perspectives. Events themselves could be of types such as add, delete, personalize, hide, copy, execute, and export. If you need to define an event that does not fall within these classifications, you can define your own domain with subdomains for your events. ■ Logs can track information in the following two ways: – Interval logging calculates the elapsed time for the action performed for example, the time taken to render a portlet. – Event logging logs the occurrence of a single step event you care about for example, whenever a user personalizes a portlet. ■ Log switching enables you to set a switch interval that defines how long you want to maintain your existing log records. The log information stored in the database uses two different tables. The log records are purged based on the value entered for the Activity Log Interval in the Configuration tab of Global Settings accessible from the Services portlet in the Portal subtab of the Administer tab. When the log interval in days is reached, the logging switches between the two logging tables in the database for example, A and B. Logs first go into A. When the log interval is reached the first time, the logs are written to B. When the log interval is reached again, the logs go back to A. A is emptied in preparation to store the new log records. If you set your log interval to 14 the default setting, the logs will switch every 14 days, thus preserving for you, at any point in time, records dated between 14 and 28 days old. 8-42 Oracle Fusion Middleware Developers Guide for Oracle Portal

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. Guidelines for Event Logging While implementing event logging, keep in mind the following: ■ Log only what you really care about to improve performance. You dont want to flood the system with log messages that are irrelevant to you. If events are logged in Show mode, then multiple instances of these portlets mean additional hits to the database. ■ Choose your domain, subdomain, and log events carefully. While using the log APIs, do not use the Oracle Portal domains such as WWC, WWV, or WWS for your log messages. Organize your domains and subdomains hierarchically ensuring that they are unique across portlets. If other portlets happen to use the same domains or subdomains, you will see those log messages interspersed with your own. ■ Create log events that show up in the pop-up lists of values monitoring the logs. You can simply create log registry records that filter the events that would actually be logged, either by specifying particular events or using the generic filters with wild cards . Apart from creating log registry records, we recommend that you create log events for events that you want to monitor. This way the lists of values in the user interface show these records for additional functions such as monitoring. ■ Provide required privileges to users or user groups who need to monitor the logs. Any logs created by a user can be viewed by that user, the Portal Administrator, and any user with the Edit privilege on the ANY_LOGS object type.

8.10.2 Adding Event Logging

The services example, located in ..\pdkplsql\pdk\plsql\svcex in PDK-PLSQL 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 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; Creating PLSQL Portlets 8-43 2. Find the save_prefs procedure. This procedure provides personalizable functionality where you can personalize text and the portlet title in Edit mode. save_prefs stores these personalizations 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_numberl_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_numberl_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;