14
Oracle XML DB Versioning

This chapter describes how to create and manage versions of Oracle XML DB resources. It contains the following sections:

• Introducing Oracle XML DB Versioning
• Creating a Version-Controlled Resource (VCR)
• Access Control and Security of VCR
• Frequently Asked Questions: Oracle XML DB Versioning

Introducing Oracle XML DB Versioning

Oracle XML DB versioning provides a way to create and manage different versions of a resource in Oracle XML DB. In previous releases of Oracle9i database, after a resource (table, column,...) is updated, its previous contents and properties are lost. Oracle XML DB versioning prevents this loss by storing a version of the resource in the database to keep the old resource contents and properties when an update is issued.

Oracle XML DB provides a PLSQL package, DBMS_XDB_VERSION to put a resource under version-control and retrieve different versions of the resource.

Oracle XML DB Versioning Features

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 an Oracle9i database.

  See Also: Oracle9i XML API Reference - XDK and Oracle XML DB

Oracle XML DB Versioning Terms Used in This Chapter

Table 14-1 lists the Oracle XML DB versioning terms used in this chapter.

Table 14-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. It is not physically stored in the database.
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 uncheckout to void the change.

Oracle XML DB Resource ID and Path Name

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 14-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);

Creating a Version-Controlled Resource (VCR)

Oracle XML DB does not automatically keep a history of updates since 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)
• ACL

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.

See "Version Resource or VCR Version".

Example 14-2 DBMS_XDB_VERSION.makeVersioned(): Creating a Version-Controlled Resource (VCR)

Resource '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, which is discussed in "Resource ID of a New Version" .

MakeVersioned() is not an auto-commit SQL operation. You have to commit the operation.

Version Resource or VCR Version

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.

Resource ID of a New Version

When a VCR is checked in, a new version resource is created, and its resource ID is returned to the you. Because the VCR is just a reference to this new version resource, the resource ID of the version can also be found by calling method DBMS_XDB.getResourceID() whose input is the VCR path name.

Example 14-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 '/home/index.html':

-- 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 14-4 Oracle XML DB: Creating and Updating a Version-Controlled Resource (VCR)

-- Variable definitions.
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');

-- Checkout 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';

-- Checkin the change
resid2 := DBMS_XDB_VERSION.Checkin('/home/SCOTT/versample.html');
end;
/

-- At this point, you can download the first version with the resource object 
ID, 
-- resid1 and download the second version with resid2.

-- Checkout to delete the VCR
DBMS_XDB_VERSION.Checkout('/home/SCOTT/versample.html');

-- Delete the VCR
delete from resource_view where any_path = '/home/SCOTT/versample.html';

-- Once the delete above is done, any reference
-- to the resource (that is, checkin, checkout,and so on, results in
-- ORA-31001: Invalid resource handle or path name "/home/SCOTT/versample.html"

Accessing a Version-Controlled Resource (VCR)

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 Version-Controlled Resource (VCR)

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. Here are the steps to update a VCR:

1. Checkout a resource. To checkout a resource, the path name of the resource must be passed to Oracle XML DB.
2. 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.
3. Checkin or uncheckout a resource. When a VCR is checked in, a new version is created, and the VCR has the same contents and properties as the new version. When a VCR is unchecked out, the VCR is unchanged. That is, it will have the same contents and properties with the old version. To checkin or uncheckout a resource, the path name of the resource must be passed to Oracle XML DB. If the path name has been updated since checkout, the new path name must be used. It is illegal to use the old path name.

Checkout

In Oracle9i Release 2 (9.2), the VCR checkout operation is executed by calling DBMS_XDB_VERSION.CheckOut(). If you want to commit an update of a resource, it is a good idea to commit after checkout. If you do not commit right after checking out, you may have to rollback your transaction at a later point, and the update is lost.

Example 14-5 VCR Checkout

For example:

-- Resource '/home/SCOTT/versample.html' is checked out.
DBMS_XDB_VERSION.CheckOut('/home/SCOTT/versample.html');

Checkin

InOracle9i Release 2 (9.2), 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.

Example 14-6 VCR Checkin

For example:

-- Resource '/home/SCOTT/versample.html' is checked in.
declare 
resid DBMS_XDB_VERSION.RESID_TYPE;
begin
   resid := DBMS_XDB_VERSION.CheckIn('/home/SCOTT/versample.html');
end;
/

Uncheckout

InOracle9i Release 2 (9.2), 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.

Example 14-7 VCR Uncheckout

For example:

-- Resource '/home/SCOTT/versample.html' is unchecked out.
declare
resid DBMS_XDB_VERSION.RESID_TYPE;
begin
   resid := DBMS_XDB_VERSION.UncheckOut('/home/SCOTT/versample.html');
end;
/

Update Contents and Properties

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.

Access Control and Security of VCR

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.

Version Resource

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.

VCR's ACL is the Same as the First Version

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 14-2 describes the subprograms in DBMS_XDB_VERSION.

Table 14-2 DBMS_XDB_VERSION Functions and Procedures  

DBMS_XDB_VERSION Function/Procedure	Description
FUNCTION MakeVersioned MakeVersioned(pathname VARCHAR2) RETURN dbms_xdb.resid_type;	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, a copy of the resource will be created, and the given path name will be bound with the newly-created copy. This new resource is then put under version control. All other path names continue to refer to the original resource. pathname - the path name of the resource to be put under version control. return - This function returns the resource ID of the first version (root) of the VCR. This is not an auto-commit SQL operation. It is legal to call MakeVersioned for VCR, and neither exception nor warning is raised. It is illegal to makeversioned for folder, version resource, and ACL. An exception is raised if the resource doesn't exist.
PROCEDURE Checkout Checkout(pathname VARCHAR2);	Checks out a VCR before updating or deleting it. pathname - the path name of the VCR to be checked out. This is not an auto-commit SQL operation. Two users of the same workspace cannot checkout the same VCR at the same time. If this happens, one user must rollback. As a result, it is a good idea for you to commit the checkout operation before updating a resource. That way, you do not loose the update when rolling back the transaction. An exception is raised when: the given resource is not a VCR, the VCR is already checked out the resource doesn't exist
FUNCTION Checkin Checkin(pathname VARCHAR2) RETURN dbms_xdb.resid_type;	Checks in a checked-out VCR. pathname - the path name of the checked-out resource. return - the resource id of the newly-created version. This is not an auto-commit SQL operation. Checkin does not have to take the same path name that was passed to checkout operation. However, the checkin path name and the checkout path name must be of the same resource for the operations to function correctly. If the resource has been renamed, 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, the new path name must be used to checkin the resource.
FUNCTION Uncheckout Uncheckout(pathname VARCHAR2) RETURN dbms_xdb.resid_type;	Checks in a checked-out resource. pathname - the path name of the checked-out resource. return - the resource id of the version before the resource is checked out. This is not an auto-commit SQL operation. UncheckOut does not have to take the same path name that was passed to checkout operation. However, the uncheckout path name and the checkout path name must be of the same resource for the operations to function correctly. If the resource has been renamed, the new name must be used to uncheckout because the old name is either invalid or bound with a different resource at the time being. An exception is raised if the path name does not exist. If the path name has been changed, the new path name must be used to checkin the resource.
FUNCTION GetRoot GetFirst(vh_id dbms_xdb.resid_type) RETURN dbms_xdb.resid_type;	Given the version history, gets the root of all versions. vh_id - the resid of the version history. return - first version resource id. An exception is raised if the vh_id is illegal.
FUNCTION GetPredecessors GetPredecessors(pathname VARCHAR2) RETURN resid_list_type; GetPredsByResId(resid dbms_xdb.resid_type) RETURN resid_list_type;	Given a version resource or a VCR, gets the predecessors of the resource by pathname, the path name of the resource. return - list of predecessors. Getting predecessors by resid is more efficient than by pathname. An exception is raised if the resid or pathname is illegal. Given a version resource or a VCR, gets the predecessors of the resource by resid (resource id) Note: The list of predecessors only contains one element (immediate parent), since Oracle does not support branching in this release. The following function GetSuccessors also returns only one element
FUNCTION GetSuccessors GetSuccessors(pathname VARCHAR2) RETURN resid_list_type; GetSuccsByResId(resid dbms_xdb.resid_type) RETURN resid_list_type;	Given a version resource or a VCR, gets the successors of the resource by pathname, the path name of the resource. return - list of predecessors. Getting successors by resid is more efficient than by path name. An exception is raised if the resid or pathname is illegal. Given a version resource or a VCR, get the successors of the resource by resid (resource id).
FUNCTION GetResourceByResId GetResourceByResId(resid dbms_xdb.resid_type) RETURN XMLType;	Given a resource object ID, gets the resource as an XMLType. resid - the resource object ID return - the resource as an XMLType

Frequently Asked Questions: Oracle XML DB Versioning

Can I Switch a VCR to a Non-VCR?

Answer: No.

How Do I Access the Old Copy of a VCR After Updating It?

Answer: The old copy is the version resource of the last checked-in:

• If you have the version ID or path name, you can load it using that ID.
• If you don't have its ID, you can call getPredecessors() to get the ID.

Can We Use Version Control for Data Other Than Oracle XML DB Data?

Answer: Only Oracle XML DB resources can be put under version control in this release.