| Oracle Repository API and Model Reference Guide |
See also:
This release of Oracle Repository introduces the concept of 'element level versioning'. In previous releases, objects could be removed from the repository by performing either a delete or a 'force' delete operation. 'Force' delete was a more powerful form of delete that bypassed checks which would normally prevent the deletion of an object.
In this release of Oracle Repository, the fact that elements may be versioned has implications for the action of deleting objects. A repository object that is under version control typically consists of a number of different versions. These versions might be checked out for update, or more typically, 'checked-in' and cannot be updated - they are 'frozen snapshots' of the object's states over time.
Normally, one would not want to remove object versions once they are checked in, but
(usually to recover storage space) the need may arise from time to time, for the following
reasons:
Users may also want to remove other objects for the following reasons:
Note that the repository can still (as in previous releases) contain non-versioned objects; indeed, a mixture of versioned and non-versioned objects may be present, and delete and 'force' delete operations can still be performed. These operations behave in the same way for non-versioned data as they always did.
This release introduces the wastebasket feature, which is like the 'recycle bin' provided by some operating systems. It enables users to undo delete or purge operations. When an object version is removed from the repository, it is not immediately physically deleted. Instead, it is placed in the workarea's wastebasket. Users may then be able to restore the object from the wastebasket at a later date. Users can empty (or 'clean up') the wastebasket, resulting in the physical deletion of all objects in the wastebasket. There is a separate wastebasket for each workarea in the repository. There is also a 'global wastebasket', containing the contents of all the workarea wastebaskets, together with any deleted or purged objects that were not part of any workarea.
Note: Secondary objects (that is, objects that are not PACs, such as COLUMN) do not get stored in the wastebasket when they are deleted.
To remove an object version from the repository (purge, force_purge), the target must be in the current context workarea and in no other workarea. Removal of the object also affects any other objects in the context workarea that reference it, depending on the delete rule established for the property that implements the reference.
Delete rule for the property on the referencing object |
Result |
|---|---|
| Block | The delete operation is prevented. |
| Cascade | The referencing object is also deleted. |
| Nullify | The referencing property is nullified. |
These rules (or blocking constraints) are defined in the repository's meta model, and can be seen in the 'Deletion Rules' section of the Element Type Definition pages.
Notes:
In the case of PAC objects, the target of a delete or purge operation is always a specific version of an object (a non-versioned object is considered to have a single version). Deleting an individual SAC element means removing it from its owning PAC.
Delete operations can only be performed when there is a context workarea set. A delete operation may be performed on either a versioned object, or a non-versioned object (the outcome of the operation is different). To perform a delete operation, the container for the object being deleted must be checked out (or non-versioned).
To perform a delete operation the current user must have delete access on the object being deleted (that is, delete access right on the owning container and on the current workarea).
If the target is not under version control, there is only one 'version' of the object in the repository, and this version is private to the workarea. Delete removes this version from currently visible containers and from the workarea, and places it into the wastebasket from where it can be restored. It is removed from the repository when the wastebasket is emptied.
Performing a delete operation on a non-versioned object is very similar to the concept of delete in previous versions of Oracle Repository. The object is removed from the repository (that is, placed in the workarea's wastebasket) if, within the context of the workarea no other objects reference the object with a 'blocking' foreign key relationship. Other referencing objects in the workarea may be cascade deleted, or have their references to the object nullified.
For an object under version control, the action of the delete operation depends on the checkin status of the target:
If the target is checked out, delete removes the checked out version of the object from currently visible containers and from the workarea, and places it into the wastebasket. Containers and versions of the object outside the current context workarea are not affected. In this respect, checked-out objects and non-versioned objects are treated the same.
When an object version is checked out, a private copy is made. That copy is private to the workarea. When a request is made to delete a checked-out object, it is this copy that is removed from the workarea, and what appears in the user's view of the repository (the workarea) is the original checked-in version from which the checkout was made. The same result can be obtained by an undo checkout operation, except that delete does not replace the checked out version with the checked in version in the workarea.
Note: Some applications may elect to prevent users from deleting checked-out objects, thus promoting the undo_checkout operation instead. The Repository Object Navigator is an example.
If the target is checked in, delete adjusts the container membership so the version no longer appears in the currently visible version (or future versions) of containers previously connected to it, including its owning container. Containers outside the current context workarea are not affected. Because the object version is not in itself being removed from the repository, it does not get put into the wastebasket. The operation may be prevented by blocking constraints, and secondary cascade deletes/nullifies will be performed. (Note that the cascade delete of a checked-in object will also result in that object being removed from its container). The object version can be brought back into the user's view by including an older version of the object's owning container into the workarea.
A delete operation cannot be performed on a checked-in root container, because it has no owning container from which it can be removed. To remove such a root container, or a checked-out object version, from the repository, purge or force_purge must be used.
Delete operations can also be performed on secondary access control objects (SACs); for example, a column can be deleted from a table. Blocking checks, and secondary deletes and updates are performed as for versions of primary objects. However, the secondary object can really be considered as a property of the primary object version. To delete a secondary object, its primary (owning) object version must be checked out (or non-versioned). The user must have update access to the primary object version.
Notes:
The purge operation completely removes versions of objects from the repository (typically versions judged to be irrelevant or obsolete). The version is removed from the object's version history and placed into the wastebasket. In contrast, a delete operation on a checked-in object version just removes that version from currently visible containers, not from the repository.
A purge operation can be performed whether or not a context workarea is set.
A container can be purged only if it is empty (that is, if it is not the owning container of any other objects).
Note that a purge request for a non-versioned object is handled as a delete request.
To perform a purge operation when there is a context workarea set, the API caller must have DEL access to the object being purged, and have the purge system privilege. (Removing versions from an object's history is considered a drastic operation, with the potential to destroy information important; for this reason, some organizations may wish to restrict access to this function to certain privileged users). When an object version is purged and there is a context workarea set, checks for blocking constraints are made.
The following factors also determine whether an object version can be purged:
When an object version is purged from within the context workarea, the version is removed from the workarea, and placed in the workareas wastebasket. The object version cannot be included into any workareas (unless it is restored from the wastebasket).
Purge also applies when there is no context workarea set, and when the target is not in
any workarea. In this case, there is no need to perform integrity checks. This is likely
to be quite a common scenario, because object versions not used in any workarea are likely
to be the versions which are irrelevant or obsolete.
To purge an object version when there is no context workarea set, the API caller must have
the DEL access right on the container of the object being purged, and have the
GLOBAL_PURGE system privilege.
When there is no context workarea set:
Secondary access controlled (SAC) objects cannot be independently versioned, and a legitimate purge operation for SACs would have no meaning. Therefore if the purge operation is applied to a SAC object, it acts in the same way as a delete operation. SACs do not have an independent life history in the repository: there would be nothing to store in the wastebasket.
The force_delete and force_purge operations are more drastic in their potential effects than the delete and purge operations. To perform these operations, the user must have the additional system privilege 'force'. These operations ignore any blocking constraints caused by references from objects in the current context workarea to the object version being deleted (or purged).
A 'force' purge operation performed on a target that is not used in any workarea is the same as a purge operation.
Note that 'force' delete and 'force' purge operations can still be blocked if:
In addition to purging single specific versions of an object, the API provides two further purge operations: purge_object and purge_insignificant_versions.
The purge_object operation removes all versions of an object from the repository (the versions are put into the Global Wastebasket). The operation can be performed in, or outside of, the current context workarea. If the operation is performed in the current context workarea, secondary updates are performed on objects in the workarea (only the currently visible versions of referencing objects will be cascade purged). The operation will be blocked if any version of the object is used in a workarea other than the current context (or simply any workarea, if no context is set).
The purge_insignificant_versions operation is used to 'trim' the version history of an object. It can be used either on a specific branch of an object's version history, or on the whole version history of the object. Any 'insignificant' nodes in the object's history are purged (and put into the global wastebasket). A version (node on a branch) is defined as insignificant if it is:
Normally, one would not want to delete/purge a checked-out object - one would undo the checkout, and revert to the original checked-in version. However, delete or purge of checked-out objects is possible, because a checked-out object may reference another object, and be cascade deleted or cascade purged. A delete or purge operation performed on a checked-out object version behaves as a delete operation on a non-versioned object.
The main points about purge and delete operations are:
The following table summarizes processing of requests to 'remove' object versions:
Method |
Result |
Pre-requisites |
Notes |
|---|---|---|---|
| delete | Has two effects:
May be blocked by references from other objects. Object is no longer visible in any previously connected containers, or in future versions of previously connected containers. |
Caller must have the DEL access right on the workarea and to
object's container. Object's container (if it is under version control) must be checked out. Object must not be a checked-in root container. If a container, object must be empty. |
If checked in, removes container membership; object not
placed in the wastebasket. If checked out or not under version control, moves object to the wastebasket. |
| force_delete | As for delete, but blocking constraints are ignored. | Caller must have the FORCE and DELETE system privileges, and the DEL access right on the workarea and the object's container. | |
| purge | As for delete, but:
|
Caller must have the PURGE system privilege, and the DEL
access right on the workarea and to the object's container. If the object is in the current context workarea, it must not be included in any other workarea. Object must not be used in any configuration. Object must not be a significant version. Cannot be a SAC element. |
Moves object version to the wastebasket. |
| force_purge | As for purge, but blocking constraints are ignored. | Caller must have the PURGE and FORCE system privileges. | |
| purge_object | Removes all versions of an object from the repository into the global wastebasket. | Caller must have the PURGE system privilege, and the DEL access right on the workarea and to the object's container. | Moves object versions to the global wastebasket. |
| purge_insignificant_version | Any 'insignificant' nodes in the object's history are purged and put into the global wastebasket. | Caller must have the GLOBAL PURGE system privilege, and the DEL access right on the object being purged. | Moves object versions to the global wastebasket. |
Purge can be used whether or not there is a context workarea set. However, if there is a context workarea set, an object cannot be purged if it is used in any other workarea, apart from the current context workarea.
To delete an object (that is, remove it from the currently visible versions of its currently visible containers), there must be a context workarea set.
The deletion of configurations is not governed by whether or not there is a context workarea set.
A restore operation moves a specific object version back to the workarea from the wastebasket. Any caller with access to the object version can perform a restore operation on it.
The following table summarizes processing of requests to restore object versions from a repository wastebasket.
| Kind of request | Result |
|---|---|
If:
|
OK. The object version is restored into the container. |
| If the version of the container that held the object is no longer checked out in the workarea. | Not OK. |
| If the object to be restored is a container. | Contents of the container do not also get restored. |
| If, when the original object version was deleted, cascade deletes were also processed. | The objects that were cascade deleted do not also get restored. |
| If, when the original object version was deleted, references to other objects were nullified, deleted, or caused other objects to be deleted. | The references are not re-instated. The objects that were deleted do not also get restored. |
| If restoring an object would cause a name conflict with other objects in the repository at the time of the restore operation. | Not OK. |
When a checked in object is deleted from its owning container, the object is not removed from the repository; what happens is that the FOLDER_MEMBER link to the owning container is deleted. If a series of multiple deletes results in the object not being owned by any container and the object is not purged, the object is said to be orphaned; it cannot be purged, since no user can navigate to it.
SDD_LOST_AND_FOUND is a view of the repository containing details of orphaned objects. Information about this view can be obtained using DESCRIBE, and it can be queried (but not updated) using SQL.
System elements are defined in the repository as part of installation. Attempting to delete a system element generates an error.
The special folder SYSTEM FOLDER is a system element and cannot be deleted. However, it can be copied and versioned (though no version of the supplied SYSTEM FOLDER can be deleted).
