24 Managing Re source 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
Creating a Version-Controlled Resource (VCR)
Access Control and Security of a VCR
Guidelines for Using Oracle XML DB Versioning

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:

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.

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:

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

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.

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

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.

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.

24 Managing Resource Versions

Overview of Oracle XML DB Versioning

Oracle XML DB Versioning Features

Oracle XML DB Versioning Terms Used in This Chapter

Oracle XML DB Resource ID and Path Name

Creating a Version-Controlled Resource (VCR)

Version Resource ID or VCR Version

Resource ID of a New Version

Accessing a Version-Controlled Resource (VCR)

Updating a Version-Controlled Resource (VCR)

Procedure DBMS_XDB_VERSION.checkOut

Procedure DBMS_XDB_VERSION.checkIn

Procedure DBMS_XDB_VERSION.unCheckOut

Update Contents and Properties

Access Control and Security of a VCR

Guidelines for Using Oracle XML DB Versioning

24 Managing Re source Versions