|Oracle® XML DB Developer's Guide
10g Release 1 (10.1)
Part Number B10790-01
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 a PL/SQL package,
DBMS_XDB_VERSION to put a resource under version-control and retrieve different versions of the resource. Versioning is currently only available for XML non-schema based resources.
Oracle XML DB versioning helps keep track of all changes on version-controlled Oracle XML DB resources (VCR). The following sections discuss these features in detail. Oracle XML DB versioning features include the following:
Version control on a resource. You have the option to turn on or off version control on an Oracle XML DB resource. See "Creating a Version-Controlled Resource (VCR)".
Updating process of a version-controlled resource. When Oracle XML DB updates a version-controlled resource, it also creates a new version of the resource, and this version will not be deleted from the database when the version-controlled resource is deleted by you. See "Updating a Version-Controlled Resource (VCR)".
Loading a version-controlled resource is similar to loading any other regular 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:In this release, Oracle XML DB versioning 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 checkin and checkout. Everything but the resource object ID of the last version is preserved.
Oracle XML DB does not support versioning of XML schema-based resources.
See Also:Oracle XML API Reference
Table 19-1 lists the Oracle XML DB versioning terms used in this chapter.
Table 19-1 Oracle XML DB Versioning Terms
|Oracle XML DB Versioning Term||Description|
|Version control||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||Versionable resource is an Oracle XML DB resource that can be put under version control.|
|Version-controlled resource (VCR).||Version-controlled resource is an Oracle XML DB resource that is put under version control. Here, a VCR is a reference to a version Oracle XML DB resource.|
|Version resource.||Version resource is a version of the Oracle XML DB resource that is put under version control. Version resource is a read-only Oracle XML DB resource. It cannot be updated or deleted. However, the version resource will be removed from the system when the version history is deleted from the system.|
|Checked-out resource.||It is an Oracle XML DB resource created when version-controlled resource is checked out.|
|Checkout, checkin, and uncheckout.||These are operations for updating Oracle XML DB resources. Version-controlled resources must be checked out before they are changed. Use the checkin operation to make the change permanent. Use |
Oracle XML DB resource ID is a unique system-generated ID for an Oracle XML DB resource. Here resource ID helps identify resources that do not have path names. For example, version resource is a system-generated resources and does not have a path name. The function
GetResourceByResId() can be used to retrieve resources given the resource object ID.
Example 19-1 DBMS_XDB_VERSION. GetResourceByResId(): First version ID is Returned When Resource'home/index.html' is Makeversioned
DECLARE resid DBMS_XDB_VERSION.RESID_TYPE; res XMLType; BEGIN resid := DBMS_XDB_VERSION.MakeVersioned('/home/SCOTT/versample.html'); -- Obtain the resource res := DBMS_XDB_VERSION.GetResoureceByResId(resid); END; /
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 that determines which principals have access to a given resource or resources.
When a Version-Controlled Resource (VCR) is created the first version resource of the VCR is created, and the VCR is a reference to the newly-created version.
Example 19-2 DBMS_XDB_VERSION.MakeVersioned(): Creating a Version-Controlled Resource (VCR)
/home/SCOTT/versample.html' is turned into a version-controlled resource.
DECLARE resid DBMS_XDB_VERSION.RESID_TYPE; BEGIN resid := DBMS_XDB_VERSION.MakeVersioned('/home/SCOTT/versample.html'); END; /
MakeVersioned() returns the resource ID of the very first version of the version-controlled resource. This version is represented by a resource ID, that is discussed in "Resource ID of a New Version" .
MakeVersioned() is not an auto-commit SQL operation. You have to commit the operation.
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 ID is returned by a couple of methods in package
DBMS_XDB_VERSION, that are 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 obtain the resource ID of the old version by getting the predecessor of the current resource.
Example 19-3 Retrieving the Resource ID of the New Version After Check In
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/SCOTT/versample.html'); -- Obtain the resource res := DBMS_XDB_VERSION.GetResourceByResId(resid); END; /
Example 19-4 Oracle XML DB: Creating and Updating a Version-Controlled Resource (VCR)
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/SCOTT/versample.html'); -- Check out to update contents of the VCR DBMS_XDB_VERSION.Checkout('/home/SCOTT/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 any_path = '/home/SCOTT/versample.html'; -- Check in the change resid2 := DBMS_XDB_VERSION.Checkin('/home/SCOTT/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 any_path = '/home/SCOTT/versample.html'; -- 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/SCOTT/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.
The operations on regular Oracle XML DB resources do not require the VCR to be checked-out. Updating a VCR requires more steps than for a regular Oracle XML DB resource:
Before updating the contents and properties of a VCR, check out the resource. The resource must be checked in to make the update permanent. All of these operations are not auto-commit SQL operations. You must explicitly commit the SQL transaction. To update a VCR follow these steps:
Checkout a resource. To checkout a resource, the path name of the resource must be passed to Oracle XML DB.
Update the resource. You can update either the contents or the properties of the resource. These features are already supported by Oracle XML DB. A new version of a resource is not created until the resource is checked in, so an update or deletion is not permanent until after a checkin request for the resource is done. You can perform the update using SQL through RESOURCE_VIEW or PATH_VIEW, or through any protocol such as WebDAV.
Checkin or uncheckout a resource. If the resource is unchecked out, then the older version of the resource, obtained through the predecessor, is copied onto the current version. The older version is deleted.
In Oracle9i release 2 (9.2) and higher, the VCR checkout 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 checkout. 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 checkin operation is executed by calling
DBMS_XDB_VERSION.CheckIn(). 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 checkout, but the checkin and checkout path names must be of the same resource.
In Oracle9i release 2 (9.2) and higher, uncheckout is executed by calling
DBMS_XDB_VERSION.UncheckOut(). This path name does not have to be the same as the path name that was passed to checkout, but the checkin and checkout 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. In other words, you can use
PATH_VIEW, or WebDAV, for example.
See Also:Chapter 20, " SQL Access Using RESOURCE_VIEW and PATH_VIEW " for details on updating an Oracle XML DB resource.
Access control on VCR and version resource is the same as for a regular resource. Whenever you request access to these resources, ACL is checked.
When a regular resource is
makeversioned, the first version resource is created, and the ACL of this first version 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 exactly the same as the ACL of the checked-out resource. After version resource is created, its ACL cannot be changed and is used the same way as the ACL of a regular resource.
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 19-2 describes the subprograms in
Table 19-2 DBMS_XDB_VERSION Functions and Procedures
||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.
If the resource has been renamed, then the new name must be used to checkin 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 checkin 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 switch a VCR to a non-VCR.
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 in this release.
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 the resources. In this release, versioning only works for XML non-schema-based resources, hence no unique constraints are violated.
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 checkout happens and the transaction is committed, any user can edit the resource.
When a checked out resource is checked in the original version checked out is placed into version history.
Properties for resources are maintained for each version. Versions are stored in the same tables. In this release, versioning only works for XML non-schema-based resources, hence no constraints are violated.