This topic presents information about the following subjects related to the wwerr_api_error and wwerr_api_error_ui API packages:

Error types and definitions

Exception classes

Declaring errors

Raising exceptions

Handling exceptions

Displaying errors

The error stack is a data table that holds the supporting details for the exceptions as they are raised. Each error added to the error stack consists of an error code, which is used to obtain the translatable error message, and a list of parameters for the error. These parameters are substituted into the error message, which uses special markup characters, when it needs to be printed.

Error messages can be stacked using either their name or their ID, within the scope of their sub-system. Any number of errors may be placed onto the stack.

Every exception raised should be accompanied by an entry in the error stack. Entries should not be put into the error stack unless an exception is raised.

When an exception occurs, the calling routine has two options:

• Handle the exception, perhaps displaying an appropriate UI. Typically this is done by top-level packages. These packages are invoked directly from the browser and display some form of error dialog when an error occurs.

• Pass the exception on, perhaps stacking another error. Typically this is done by Oracle Portal routines doing some work on behalf of the caller.

The error handling API allows a provider to detect and react programmatically to errors that occur during the execution of application code. The cause of these errors can include:

Error Types and Definitions
Invalid user input	This is the most common error. Functions that accept user input should validate the input. Methods that perform this validation should stack errors and raise exceptions that indicate the nature of the problem.
Invalid input arguments	Functions that accept input arguments from calling modules, such as an enumerated constant, should validate the arguments to ensure that no arbitrary actions are performed and no destructive processing is performed in response to the inputs.
Exception Classes
Public	Public exceptions are visible to callers of the error handling API. These declarations belong in the specification of either the package that raises the exception or in one of the packages of the subsystem to which the exception belongs.
Private	Private exceptions are not available to providers.

Declaring Errors

Each package or subsystem that uses the wwerr_api_error should declare the exceptions that it intends to raise. The portlet provider subsystem declares the following exceptions in the package wwpro_api_plug:

• PLUG_NOT_FOUND_EXCEPTION
  

• PLUG_SECURITY_EXCEPTION
  
• PLUG_EXECUTION_EXCEPTION

In PL/SQL, exceptions are defined in the declaration section:

exception <ExceptionName>;

For example:

package wwpro_api_plug is 

exception PLUG_NOT_FOUND_EXCEPTION; 

... 

<procedures and functions...> 

end wwpro_api_plug;

Each exception that is raised may represent a class or set of errors with the supporting detail stored in the error stack. Each error that accompanies the exception must be stored in the NLS translation subsystem to facilitate correct translation of the error text.

Raising Exceptions

Exceptions should be raised in the standard manner. Before an exception is raised, a call should be made to wwerr_api_error.add to add supporting error details to the error stack. These error messages can be stacked using either their names or their IDs within the scope of their subsystem. Exceptions should not be raised outside of the sub-system in which they occur.

Every exception that is raised should be accompanied by an entry in the error stack. Any number of errors may be placed onto the stack, but entries should be placed on the stack only if an exception was raised. Errors are cleared by making a call to wwerr_api_error.clear.

Each error that is added to the error stack consists of an error code used to obtain the translatable error message and a list of parameters for the error. These parameters are substituted into the error message, which uses special markup characters when it needs to be printed.

Code that handles exceptions can inspect supporting details to present the appropriate UI to the user.

Handling Exceptions

Most functions simply stack an error and raise an exception. However, when an exception occurs, the calling routine has two options:

• Pass the exception on, perhaps stacking another error. This is usually done by wwxxx_api_ routines where some work is being done on behalf of the caller.

• Handle the exception and, in some cases, display an appropriate UI.

Displaying Errors

This is usually done by top-level packages or those invoked directly from the browser and display some form of error dialog when an error occurs. Top level packages, and those that are invoked directly from the browser, must handle all exceptions and display some form of error dialog.

For example:

... 

EXCEPTION 

when others then 

wwerr_api_error_ui.show_html; 

END;

The wwerr_api_error_ui package has a number of routines that support a standardized display of error messages. In each case, the output produced is assumed to be embedded within the caller's output.

The default output for each of these will most likely be straightforward and designed for the end-user's use, but will provide a mechanism to obtain the full set of error details for support purposes.