This chapter describes how to create and manage versions of Oracle XML DB resources.
This chapter contains these topics:
Oracle XML DB versioning provides a way to create and manage different versions of a resource in Oracle XML DB. When you update a resource such as a table or column, Oracle XML DB stores the pre-update contents as a separate resource version.
Oracle XML DB provides PL/SQL package
DBMS_XDB_VERSION to put a resource under version-control and retrieve different versions of the resource.
Versioning helps you keep track of changes to resources in Oracle XML DB Repository. The following sections discuss these features in detail. Oracle XML DB versioning features include the following:
Version control on a resource. You can turn version control on or off for an Oracle XML DB Repository resource. See "Creating a Version-Controlled Resource (VCR)".
Updating process of a version-controlled resource. When Oracle XML DB updates a version-controlled resource (VCR), it creates a new version of the resource. This new version will not be deleted from the database when you delete the version-controlled resource. See "Updating a Version-Controlled Resource (VCR)".
Loading a VCR is similar to loading a resource in Oracle XML DB using the path name. See "Creating a Version-Controlled Resource (VCR)".
Loading a version of the resource. To load a version of a resource, you must first find the resource object id of the version and then load the version using that id. The resource object id can be found from the resource version history or from the version-controlled resource itself. See "Oracle XML DB Resource ID and Path Name".
Note:Oracle XML DB supports version control for Oracle XML DB resources. It does not support version control for user-defined tables or data in Oracle Database.
Oracle does not guarantee that the resource object ID of a version is preserved across check-in and check-out. Everything but the resource object ID of the last version is preserved.
Oracle XML DB supports versioning of XML schema-based resources only if the schema tables have no associated triggers or constraints.
Table 24-1 lists the Oracle XML DB versioning terms used in this chapter.
|Oracle XML DB Versioning Term||Description|
When a record or history of all changes to an Oracle XML DB resource is stored and managed, the resource is said to be put under version control.
Versionable resource is an Oracle XML DB resource that can be put under version control.
A version resource is a version of the Oracle XML DB resource that is put under version control. A version resource is a read-only Oracle XML DB resource. It cannot be updated or deleted.
An Oracle XML DB resource created when a version-controlled resource is checked out.
Operations for updating Oracle XML DB resources. Version-controlled resources must be checked out before they are changed. Use
A resource ID is a unique system-generated ID for an Oracle XML DB resource. It helps identify resources that do not have path names. For example, a version resource is a system-generated resource and does not have a path name. You can use PL/SQL function
GetResourceByResId to retrieve resources given the resource object ID. The first version ID is returned if a resource is versioned.
Oracle XML DB does not automatically keep a history of updates because not all Oracle XML DB resources need this. You must send a request to Oracle XML DB to put an Oracle XML DB resource under version control. In this release, all Oracle XML DB resources are versionable resources except for the following:
Folders (directories or collections)
Access control list (ACL), the list of access control entries (ACEs) that determines which principals have access to a given resource or resources.
When a version-controlled resource is created, the first version resource of the VCR is created, and the VCR is a reference to this newly-created version.
/home/QUINE/versample.html' is turned into a version-controlled resource.
DECLARE resid DBMS_XDB_VERSION.RESID_TYPE; BEGIN resid := DBMS_XDB_VERSION.makeVersioned('/home/QUINE/versample.html'); END; /
makeVersioned returns the resource ID of the first version of the version-controlled resource. This version is represented by a resource ID – see "Resource ID of a New Version" .
makeVersioned does not auto-commit; you must perform a
Oracle XML DB does not provide path names for version resources. However, it does provide a version resource ID. Version resources are read-only resources.
The version resource ID is returned by a few methods in package
DBMS_XDB_VERSION, as described in the following sections.
When a VCR is checked out and updated for the first time, a copy of the existing resource is created. The resource ID of the latest version of the resource is never changed — you can always access the latest version using the original resource ID. You can obtain the resource ID of the old version by getting the predecessor of the current resource.
The following example shows how to get the resource ID of the new version after checking in
-- Declare a variable for resource id DECLARE resid DBMS_XDB_VERSION.RESID_TYPE; res XMLType; BEGIN -- Get the id as user checks in. resid := DBMS_XDB_VERSION.checkIn('/home/QUINE/versample.html'); -- Obtain the resource res := DBMS_XDB_VERSION.GetResourceByResId(resid); END; /
DECLARE resid1 DBMS_XDB_VERSION.RESID_TYPE; resid2 DBMS_XDB_VERSION.RESID_TYPE; BEGIN -- Put a resource under version control. resid1 := DBMS_XDB_VERSION.makeVersioned('/home/QUINE/versample.html'); -- Check out VCR to update its contents DBMS_XDB_VERSION.checkOut('/home/QUINE/versample.html'); -- Use RESOURCE_VIEW to update versample.html UPDATE RESOURCE_VIEW SET RES = SYS.XMLTYPE.createXML( '<Resource xmlns="http://xmlns.oracle.com/xdb/XDBResource.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/xdb/XDBResource.xsd http://xmlns.oracle.com/xdb/XDBResource.xsd"> <Author>Jane Doe</Author> <DisplayName>versample</DisplayName> <Comment>Has this got updated or not ?? </Comment> <Language>en</Language> <CharacterSet>ASCII</CharacterSet> <ContentType>text/plain</ContentType> </Resource>') WHERE equals_path(RES, '/home/QUINE/versample.html') = 1'; -- Check in the change resid2 := DBMS_XDB_VERSION.checkIn('/home/QUINE/versample.html'); -- The latest version can be obtained by resid2 and its predecessor -- can be obtained by using getPredecessor() or getPredsbyResId() functions. -- resid1 is no longer valid. END; / -- Delete the VCR DELETE FROM RESOURCE_VIEW WHERE equals_path(RES, '/home/QUINE/versample.html') = 1'; -- Once the preceding delete is done, any reference to the resource -- (that is, check-in, check-out, and so on, results in -- ORA-31001: Invalid resource handle or path name "/home/QUINE/versample.html"
VCR also has a path name as any regular resource. Accessing a VCR is the same as accessing any other resources in Oracle XML DB.
Updating a VCR requires more steps than updating a resource that is not version-controlled. Before updating the contents and metadata properties of a VCR, check out the resource. The resource must then be checked in to make the update permanent. You must explicitly commit the SQL transaction.
To update a VCR follow these steps:
Check out the VCR, passing the VCR path name to Oracle XML DB.
Update the VCR. You can update either the contents or the metadata properties of the VCR. A new VCR version is not created until check-in, In particular, an update or a deletion operation does not permanently take effect until after check-in. (You can perform an update using SQL through
PATH_VIEW, or through any protocol such as WebDAV.)
Check in the VCR or cancel its check-out. If the resource is not checked out, then the previous version is copied onto the current version. The previous version is then deleted.
In Oracle9i release 2 (9.2) and later, the VCR check-out operation is executed by calling
DBMS_XDB_VERSION.checkOut. If you want to commit an update of a resource, then it is a good idea to commit after check-out. If you do not commit right after checking out, then you may have to rollback your transaction at a later point, and the update is lost.
In Oracle9i release 2 (9.2) and higher, the VCR check-in operation is executed by calling
checkIn takes the path name of a resource. This path name does not have to be the same as the path name that was passed to check-out, but the check-in and check-out path names must be of the same resource.
In Oracle9i release 2 (9.2) and later, a check-out is cancelled by calling
DBMS_XDB_VERSION.unCheckOut. This path name does not have to be the same as the path name that was passed to check-out, but the check-in and check-out path names must be of the same resource.
After checking out a VCR, all Oracle XML DB user interfaces for updating contents and properties of a regular resource can be applied to a VCR. For example, you can use
PATH_VIEW, or WebDAV.
See Also:Chapter 25, "SQL Access Using RESOURCE_VIEW and PATH_VIEW" for details on updating an Oracle XML DB resource.
Access control of a VCR or version resource is the same as for a resource that is not version-controlled. When you request access to these resources, the access control list (ACL) is checked.
When a regular resource is converted to a VCR using
makeversion, the first version resource is created, and the ACL of this first version resource is the same as the ACL of the original resource. When a checked-out resource is checked in, a new version is created, and the ACL of this new version is the same as the ACL of the checked-out resource. After a version resource is created, its ACL cannot be changed.
When a VCR is created by
makeversioned, the ACL of the VCR is the same as the ACL of the first version of the resource. When a resource is checked in, a new version is created, and the VCR will have the same contents and properties including ACL property with this new version.
Table 24-2 describes the subprograms in
Turns a regular resource whose path name is given into a version controlled resource. If two or more path names are bound with the same resource, then a copy of the resource will be created, and the given
Checks out a VCR before updating or deleting it.
Checks in a checked-out VCR.
This is not an auto-commit SQL operation. Procedure
If the resource has been renamed, then the new name must be used to check in because the old name is either invalid or bound with a different resource at the time being. Exception is raised if the path name does not exist. If the path name has been changed, then the new path name must be used to check in the resource.
Checks in a checked-out resource.
Given a version resource or a VCR, gets the predecessors of the resource by
Getting predecessors by
Given a version resource or a VCR, gets the predecessors of the resource by
Note: The list of predecessors only contains one element (immediate parent), because Oracle does not support branching in this release. The following function
Given a version resource or a VCR, gets the successors of the resource by
Given a version resource or a VCR, get the successors of the resource by
Given a resource object ID, gets the resource as an
This section describes guidelines for using Oracle XML DB versioning.
You cannot change a VCR to no longer be version-controlled.
You can access an old copy of a VCR after updating it. The old copy is the version resource of the last one checked-in, hence:
If you have the version ID or path name, then you can load it using that ID.
If you do not have its ID, then you can call getPredecessors() to get the ID.
Only data in Oracle XML DB resources can be put under version control.
When a resource is turned into a VCR, a copy of the resource is created and placed into the version history. A flag marks the resource as a VCR. Earlier in this chapter it states that a version-controlled resource is an Oracle XML DB resource that is put under version control where a VCR is a reference to a version Oracle XML DB resource. It is not physically stored in the database. In other words no extra copy of the resource is stored when the resource is versioned, that is, turned into a VCR.
Versions are stored in the same object-relational tables as resources. Versioning works for non-schema-based resources. It works also for XML schema-based resources, if the schema tables have no associated triggers or constraints.
The documentation states that a version resource is a system-generated resource and does not have a path name. However you can still access the resource using the navigational path.
When the VCR resource is checked out, no copy of the resource is created. When it is updated the first time, a copy of the resource is created. You can make several changes to the resource without checking it in. You will get the latest copy of the resource. Even if you are a different user, you will get the latest copy.
Updates cannot be made to a checked out version by more than one use. Once the check-out happens and the transaction is committed, any user can edit the resource.
When a checked-out resource is checked in, the original previously checked-out version is added to the version history.
Resource metadata is maintained for each version. Versions are stored in the same tables. Versioning works only for non-schema-based resources or XML schema-based resources if the schema tables have no associated triggers or constraints.