Error Handling

Server-side PL/SQL packages post errors to two error stacks. Some package methods also throw exceptions that may need to be handled by the calling client application code.

Exceptions and the contents of the error stacks reach Java clients via JDBC. Java clients can use the CWException class to manage the retrieval and display of error messages.

Handling CDAPI Error Events In PL/SQL Clients

Callers of the Repository API should base error handling on the CDAPI 'activity' model. CDAPI activities enable the caller of API to group sets of operations into transactions, and within each activity examine and handle any errors generated so far within the scope of that activity.

To start a transaction, the caller sets up a savepoint to be rolled back to if necessary (that is, if a serious error means that the set of operations in the transaction must be halted).

The Activity mechanism works in conjunction with:

• Two error stacks:
  • CDAPI stack, which contains information and messages posted by CDAPI <element type> packages.
  • SQL stack, containing error events and messages posted by PL/SQL and Oracle DBMS
    
    
• The CI_VIOLATIONS table, which contains events of two types: warning and error (serious). Errors posted in the CI_VIOLATIONS table cause the currently 'active' activity to halt, until any such errors have been corrected by the caller. The usual strategy is for the caller to iteratively fix the errors by getting and responding to the corresponding messages from the error stacks.

  During an activity, the caller can examine the table for warnings, and if there are any outstanding warnings posted there, examine one or both of the error stacks and process the messages currently on the stacks.

The caller can obtain the entire stack or can pop each message off stack and handle them in some way (for example, roll back if serious, or re-input data).

Some API calls must be made within the scope of a CDAPI activity, but it is recommended that Activities be used to structure all use of the API .

Following is a summary of the methods in the CDAPI package for working with CDAPI Activities.

• open_activity is a request to start a new activity (transaction).
  
  
• abort_activity is a request to abandon the current activity and roll back to a savepoint. Aborts the activity and any sub-activities. Aborting the outermost activity aborts all the inner activities.
  
  
• close_activity is a request to close the 'current' activity. Will not be closed if there are outstanding messages on either stack. If successful, removes outstanding warning events from the stacks. Closes the activity and any sub-activities. Closing the outermost activity closes all the inner activities.
  
  
• validate_activity A way to check the progress of operations part-way through an activity. Tells whether messages have been placed in the CI_VIOLATIONS view by the DBMS.
  
  
• clear_stack
  
  
• get_message get_stack instantiate_mess instantiate_message pop_message. These methods require the caller to reconstruct the returned message; however, they enable the caller to access the individual parameters and isolate or report the particular element or object that is the subject of the message.
  
  
• pop_instantiated_message Pops the topmost message off the stack, already formatted.
  
  
• stacksize Returns the size of the CDAPI stack
  
  
• violations_to_stack Causes any events placed in the CI_VIOLATIONS table to be pushed onto the CDAPI message stack, from where they can be retrieved as message text.

Beginning An Activity

See also

CDAPI Activities
For details of error messages, see the Error Message lists available from the product Start menu, documentation entry.

An activity (that is, a CDAPI transaction) must be opened before methods can be called to manipulate elements in the repository. This is done with a call to CDAPI.open_activity.

After an activity has been opened, calls can be made to perform element operations, close or abort the activity, or open new sub-activities.

A top-level activity can be closed and a new top-level activity opened as many times as desired within an API session without the need to rerun CDAPI.initialize (). 

Validating An Activity

At any time during an activity, a call can be made to CDAPI.validate_activity to perform all of the deferred checks that are pending against the current activity, and calculate values for text strings that are substituted into the NLS messages whenever a constraint is violated. CDAPI.validate_activity populates the CI_VIOLATIONS view so that it contains a row for each outstanding constraints violation. The call to CDAPI.validate_activity must be made before the CI_VIOLATIONS view can be queried to retrieve a list of outstanding constraint violations against the current activity.

Closing an activity triggers a call to CDAPI.validate_activity.

Ending An Activity

Each activity that is opened must be terminated with a call to either of the following:

• CDAPI.close_activity, to close the activity and commit it to the database.
  
  
• CDAPI.abort_activity, to roll back all database changes performed during the activity.

A call to close an activity will not succeed if there are outstanding constraint violations, and the user will remain in the current activity.

Note: CDAPI.close_activity involves an implicit call to CDAPI.validate_activity. However, if the activity closes, there is no way of retrieving any WARNING violations that may have been raised during that activity. Therefore, it is safest to call CDAPI.validate_activity explicitly, review all constraint violations reviewed, then make a call to CDAPI.close_activity.

Errors may be generated by violations that are trapped by the database, by the repository, and by SQL.

Errors and warnings raised by the CDAPI can be trapped and inspected via a call to the CDAPI.validate_activity method, which scans violations that were posted to internal tables during the course of a CDAPI activity. Errors that occur during an activity that require the current operation to terminate cause an error to be posted on the message stack and an exception to be raised to the caller. The exception raised by the CDAPI is always apierror (defined in the package CDAPI).

Examples of error conditions that automatically cause exceptions are:

• Access control violations:
  Since access privileges are established when 'CDAPI.initialize ()' is called, an event which always takes place outside the scope of an activity; it is never possible to correct these errors from within the activity.
  
  
• Non-cascading delete referential integrity violations:
  It is no longer possible to reference an element that has been deleted, nor is it possible currently to correct certain situations once the offending element has been deleted, so this causes an error.
  
  
• Operations that would cause a referential integrity constraint defined at the DDL level to be violated:
  NOT NULL constraints and unique index constraints cause processing to abort when written through to SQL, so they are trapped within API and reported as errors, which appears cleaner to the user.

When the code that implements a method encounters an error condition, the following happens:

1. The call to the method fails.
   
   
2. The method raises an exception and pushes an error on the API stack. An error may also be pushed onto the SQL stack.
   
   
3. The method returns.

It is the responsibility of the caller to catch the exception and handle the error condition appropriately. Callers on client computers connected via JDBC are notified of error conditions as described for Java clients.

See also the example of how to trap and handle errors.

Handling Errors in Java Clients

Java clients must employ a strategy similar to the following for handling API errors:

1. Implement a handler for the CWException exception type. A CWException object obtains message text from the client-side error message file, and contains methods for manipulating the message.
   
   
2. Use the ShowAlert method of CWException to display error stack in a dialog.
   
   
3. Use the getAlerts method of CWException to return the entire error stack as an enumerator
   
   
4. Alternatively, handle the error in some other way appropriate to the needs of the calling application. For details of error messages, see the Error Message lists available from the product Start menu, documentation entry.

Notes on Error Handling

• Some packages catch exceptions and handle them by returning NULL in parameters (or as the return value in the case of a function). For example:

  jr_name.get_rid_vid('ROOT_FOLDER/SUB_FOLDER/File.txt',el_irid,el_ivid); 

  In this case. If no objects match the specified path, el_irid and el_ivid contain nulls on return. Therefore nulls do not necessarily mean there was an 'error' in specifying the call.

• Java Clients get exceptions and message notifications via JDBC. The throwable class CWException can be used to manage the display and handling of exceptions by Java clients.