19 Managing Oracle XML DB Resource Versions

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. 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.

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;
/

Creating a Version-Controlled Resource (VCR)

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.

See "Version Resource or VCR Version".

DECLARE 
  resid DBMS_XDB_VERSION.RESID_TYPE;
BEGIN 
  resid := DBMS_XDB_VERSION.MakeVersioned('/home/SCOTT/versample.html');
END;
/

-- 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;
/

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"

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

-- 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;
/

-- 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;
/

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.

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 DBMS_XDB_VERSION.

Guidelines for Using Oracle XML DB Versioning

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.