Skip Headers
Oracle® XML DB Developer's Guide
11g Release 1 (11.1)

B28369-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

24 Managing Resource Versions

This chapter describes how to create and manage versions of Oracle XML DB resources.

This chapter contains these topics:

Overview of 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 PL/SQL package DBMS_XDB_VERSION to put a resource under version-control and retrieve different versions of the resource.

Oracle XML DB Versioning Features

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.

Oracle XML DB Versioning Terms Used in This Chapter

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

Table 24-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

A version-controlled resource (VCR) is an Oracle XML DB resource that is under version control.

Version resource

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.

Checked-out resource

An Oracle XML DB resource created when a version-controlled resource is checked out.

checkOut, checkIn, unCheckOut

Operations for updating Oracle XML DB resources. Version-controlled resources must be checked out before they are changed. Use checkIn to make the change permanent. Use unCheckOut to cancel the change.


Oracle XML DB Resource ID and Path Name

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.

Example 24-1 Using DBMS_XDB_VERSION.GetResourceByResId To Retrieve a Resource

DECLARE 
  resid DBMS_XDB_VERSION.resid_type;
  res XMLType;
BEGIN 
  resid := DBMS_XDB_VERSION.makeVersioned('/home/QUINE/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:

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.

See "Version Resource ID or VCR Version".

Example 24-2 Using DBMS_XDB_VERSION.makeVersioned To Create a VCR

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

PL/SQL function 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" .

Function makeVersioned does not auto-commit; you must perform a COMMIT.

Version Resource ID 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 resource ID is returned by a few methods in package DBMS_XDB_VERSION, as described in the following sections.

Resource ID of a New Version

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.

Example 24-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/QUINE/versample.html');
  -- Obtain the resource
  res := DBMS_XDB_VERSION.GetResourceByResId(resid);
END;
/

Example 24-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/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"

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)

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:

  1. Check out the VCR, passing the VCR path name to Oracle XML DB.

  2. 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 RESOURCE_VIEW or PATH_VIEW, or through any protocol such as WebDAV.)

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

Procedure DBMS_XDB_VERSION.checkOut

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.

Example 24-5 VCR Check-Out

For example:

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

Procedure DBMS_XDB_VERSION.checkIn

In Oracle9i release 2 (9.2) and higher, the VCR check-in operation is executed by calling DBMS_XDB_VERSION.checkIn. Procedure 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.

Example 24-6 VCR Check-In

For example:

-- Resource '/home/QUINE/versample.html' is checked in.
DECLARE 
  resid DBMS_XDB_VERSION.RESID_TYPE;
BEGIN
  resid := DBMS_XDB_VERSION.checkIn('/home/QUINE/versample.html');
END;
/

Procedure DBMS_XDB_VERSION.unCheckOut

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.

Example 24-7 VCR unCheckOut

For example:

-- Resource '/home/QUINE/versample.html' is unchecked out.
DECLARE
 resid DBMS_XDB_VERSION.RESID_TYPE;
BEGIN
  resid := DBMS_XDB_VERSION.unCheckOut('/home/QUINE/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. For example, you can use RESOURCE_VIEW, 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 and Security of a VCR

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.

Version Resource

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.

ACLs of Version-Controlled Resources Are the Same as the First Versions

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

Table 24-2 DBMS_XDB_VERSION Functions and Procedures

Function/Procedure Description

FUNCTION makeVersioned

makeVersioned(pathname VARCHAR2) RETURN DBMS_XDB_VERSION.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, then 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 a VCR, and neither an exception nor a warning is raised. It is not permitted to call makeVersioned for a folder, version resource, or ACL. An exception is raised if the resource does not 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 cannot check out the same VCR at the same time. If this happens, then one user must rollback. As a result, it is a good idea for you to commit the check-out 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 does not exist

FUNCTION checkIn

checkIn (pathname VARCHAR2) RETURN DBMS_XDB_VERSION.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. Procedure checkIn does not have to take the same path name that was passed to check-out operation. However, the check-in path name and the check-out path name must be of the same resource for the operations to function correctly.

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.

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. Procedure unCheckOut does not have to take the same path name that was passed to check-out operation. However, the unCheckOut path name and the check-out path name must be of the same resource for the operations to function correctly. If the resource has been renamed, then the new name must be used for 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, then the new path name must be used to check in the resource.

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

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), because 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 not permitted.

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


Guidelines for Using Oracle XML DB Versioning

This section describes guidelines for using Oracle XML DB versioning.