| Oracle Repository API and Model Reference Guide |
The CDAPI provides a transaction management feature (the 'activity model') that extends the capabilities of SQL. The CDAPI equivalent of a transaction is an 'activity'. During an activity, constraints defined against element types are allowed to become temporarily violated without the activity being halted: a failed activity does not force a rollback. All CDAPI package methods must be called within the context of an activity.
The API allows constraints to be defined across multiple element types. As part of the activity mechanism, the API distinguishes between warning violations and error violations. Warning violations are for information purposes only. An activity can be closed if only warning violations are outstanding. Warning violations provide a way for the API to give notice that an unusual condition was encountered. Error violations prevent the caller from closing the current activity. Either all the error violations must be fixed and the activity closed, or the activity must be aborted.
The API also distinguishes between constraints on an element that involve only its own properties (internal constraints) and constraints defined against the element that involve references to properties in other elements (external constraints).
Checking of internal constraints is performed when a specific operation is performed. Checking of other constraints is deferred until a call is made to close or validate the activity.
The caller typically opens an activity (setting a savepoint), performs a related group
of operations, requests to close the activity. When a top-level activity terminates
normally, all database operations in the activity are committed. If the caller aborts the
activity, operations are rolled back to the savepoint established when the activity was
opened. If any constraint violations occur, these are recorded internally by the API. If
any of these constraint violations are errors (as opposed to warnings), the caller cannot
close the activity, but must either:
A call to close an activity can fail because of error constraint violations. Failure of a close activity statement does not automatically roll back the activity. The current activity is still open, which allows the caller to correct the violations. Subsequent calls to close the activity can be performed until there are no constraint violations and the activity can close successfully. Alternatively, the activity can be rolled back(aborted) at any time.
A caller using the CDAPI activity mechanism can check for all errors and warnings using:
cdapi.validate_activity (act_status OUT VARCHAR2, act_warnings OUT VARCHAR2);
The validate_activity method can be called to assess current violations in the activity (including deferred constraints).
Activities can be nested to form a hierarchy. The first activity opened in an API session is the top-level activity. This top-level outermost activity may recursively open inner activities. Each opened inner activity can consist of multiple operations and inner activities. Regardless of whether the inner activity is closed successfully or aborted, the API guarantees that the inner activity will not introduce any new constraint violations to its enclosing activity. If an inner activity is aborted, a 'rollback to savepoint' call is made, rolling back all operations performed during the inner activity. Successful closure of a sub-activity returns the session context to the super-activity. Successful closure of a top-level activity performs an implicit COMMIT.
Only the constraints that are affected by the operations performed in a sub-activity are checked when the sub-activity is closed. If any constraint violations were raised in the inner activity that were also outstanding against the same elements in the outer activity, these must be corrected before the inner activity is allowed to close successfully. All other constraint violations generated by outer activities are left to be checked when the appropriate outer activity is closed.
Subsequent requests to close the activity will re-check all changes made in sub-activities. There may be a performance penalty attached to the use of nested activities, because until the final close activity operation (which performs a commit) the uncommitted data may have been made invalid by other transactions that may have been committed.
For the same reason, the validate_activity call when followed directly by a call to close_activity, will cause all potential error violations to be checked twice. Callers that are not interested in handling warning messages should just call close_activity.
The CDAPI.activity method returns the ID of the 'current' activity, and can be used to track current activity.
When the API detects that a constraint has been violated, it records specific details about the constraint and the context in which it was violated. This information is available to the API session through the CI_VIOLATIONS view. Each row in the view represents an instance of a constraint violation. The CI_VIOLATIONS view contains the following columns:
Name Null? Type ELEMENT NUMBER (38) FACILITY VARCHAR2 (3) CODE NUMBER (5) P0 VARCHAR2 (240) ... ... P7 VARCHAR2 (240) POK VARCHAR2 (240) WARNING VARCHAR2 (1)
ELEMENT contains the IRID of the element that the violation concerns. FACILITY and CODE identify the error (for example, CDA-1000).
The columns P0 through P7 hold values for the parameters that will be substituted into the National Language Support (NLS) text string if the message is instantiated. The POK column is for internal use only.
A 'Y' in the WARNING column specifies that the violation is a warning and not an error.
If a statement-level constraint is violated, a row is placed in CI_VIOLATIONS view immediately. Subsequent CDAPI calls may cause this row to be removed (for instance, if the element that caused the error is deleted). Deferred constraint violations are checked only during close_activity and validate_activity; therefore it is only worthwhile examining the rows in CI_VIOLATIONS after a call to one of these functions. Close_activity does not complete successfully if there are rows in CI_VILOATIONS.
The instantiate_message method is provided in the CDAPI package to facilitate the retrieval of violation information and package the information into a formatted message string prefixed by the message facility and message code.
In specific cases the API must pass information back to the calling process other than through the CI_VIOLATIONS view. Packages provided by the CDAPI may place error message information on an internal stack. Methods on the CDAPI package (for example, pop_instantiated message) are provided to enable callers to retrieve individual messages or ranges of messages from this stack.
If database errors occur, PL/SQL exceptions are raised, and can be inspected using the procedure dbms_utility.format_error_stack.
A caller can perform API operations to correct any constraints violations that occur during an activity. This may include, for example, updating NAME property values to avoid uniqueness conflicts, or updating an element to provide a mandatory property value.
In very specific cases, a constraint violation may be encountered which prevents
continuation of the operation. In such cases, an ERROR violation is posted and a
user-defined PL/SQL exception is raised. This results in a rollback of all processing
performed by the current operation, but leaves the activity otherwise unaffected. For all
cases other than invalid_ref and locked_element, the exception raised is cdapi.apierror. A
message is posted to the stack and cdapi.apierror is raised if:
