Locking Items with JavaScript WebDAV Library

Locking prevents the item from being modified by other users and supported by any Class 2 WebDAV server.

Probing Locks Support

Item can support exclusive, shared locks or do not support any locks. If you set exclusive lock other users will not be able to set any locks. If you set shared lock other users will be able to set shared lock on the item. To find out what locks are supported by the item use HierarchyItem.SupportedLocks property.

var webDavSession = new ITHit.WebDAV.Client.WebDavSession();
var sFileAbsolutePath = 'http://localhost:87654/myfile.txt';
var fCallback = function() {};

webDavSession.OpenFileAsync(sFileAbsolutePath, function(oAsyncResult) {

    /** @typedef {ITHit.WebDAV.Client.File} oFile */
    var oFile = oAsyncResult.Result;

    if (oFile.SupportedLocks.length === 0) {
        console.log('Locks are not supported.');
    }

    for (var i = 0, l = oFile.SupportedLocks.length; i < l; i++) {
        if (oFile.SupportedLocks[i] === ITHit.WebDAV.Client.LockScope.Exclusive) {
            console.log('Item supports exclusive locks.');
        }
        if (oFile.SupportedLocks[i] === ITHit.WebDAV.Client.LockScope.Shared) {
            console.log('Item supports shared locks.');
        }
    }

    fCallback(oAsyncResult);
}); 

Locking Items

To lock the item use HierarchyItem.LockAsync method. While locking you can pass to the server the following additional information about the lock:

  • Specify if the lock is shared or exclusive.
  • Specify if the lock applied only to this item or to the entire subtree.
  • Name of the user that applies lock.
  • A Time when the lock expires. To specify that lock should never expire pass -1.
var webDavSession = new ITHit.WebDAV.Client.WebDavSession();
var sFileAbsolutePath = 'http://localhost:87654/myfile.txt';
var fCallback = function() {};

webDavSession.OpenFileAsync(sFileAbsolutePath, function(oFileAsyncResult) {

    /** @typedef {ITHit.WebDAV.Client.File} oFile */
    var oFile = oFileAsyncResult.Result;

    if (oFile.SupportedLocks.length === 0) {
        console.log('Locks are not supported.');
        return;
    }

    oFile.LockAsync(ITHit.WebDAV.Client.LockScope.Shared, false, 'User 1', -1, function(oAsyncResult) {

        /** @typedef {ITHit.WebDAV.Client.LockInfo} oLockInfo */
        var oLockInfo = oAsyncResult.Result;

        if (oAsyncResult.IsSuccess) {
            console.log('Locks token is: ' + oLockInfo.LockToken.LockToken);
        }

        fCallback(oAsyncResult);
    });
}); 

If the lock was successfully applied the server will return lock token and the actual lock time. The lock token is a string (usually GUID) uniquely identifying the lock. You will pass this lock token back to the server when updating or unlocking the item.

The lock time applied by the server may be different from the one requested by the client.

To modify the locked item, you must pass the lock token with an update request. All API methods that modify item content or properties provide overloaded instance to pass the lock token:

var oNS = ITHit.WebDAV.Client;
var session = new oNS.WebDavSession();
var item = session.OpenResource("http://server/Storage/img5.gif");
var destFolder = session.OpenFolder("http://server/Sales/");

var lockInfo = item.Lock(oNS.LockScope.Shared, false, "User 1", -1);
item.CopyTo(destFolder, "Copy of " + item.DisplayName, false, false);
item.Unlock(lockInfo.LockToken.LockToken); 

Getting the List of Item Locks

To get the list of locks applied to the item use the HierarchyItem.ActiveLocks property.

var webDavSession = new ITHit.WebDAV.Client.WebDavSession();
var sFileAbsolutePath = 'http://localhost:87654/myfile.txt';
var fCallback = function() {};
webDavSession.OpenFileAsync(sFileAbsolutePath, function(oFileAsyncResult) {
    /** @typedef {ITHit.WebDAV.Client.File} oFile */
    var oFile = oFileAsyncResult.Result;
    // Infinite lock
    oFile.LockAsync(ITHit.WebDAV.Client.LockScope.Shared, false, "User 1", -1, function(oInfiniteLockAsyncResult) {
        /** @typedef {ITHit.WebDAV.Client.LockInfo} oInfiniteLockInfo */
        var oInfiniteLockInfo = oInfiniteLockAsyncResult.Result;
        // Minute lock
        oFile.LockAsync(ITHit.WebDAV.Client.LockScope.Shared, false, "User 2", 60, function(oMinuteLockAsyncResult) {
            /** @typedef {ITHit.WebDAV.Client.LockInfo} oMinuteLockInfo */
            var oMinuteLockInfo = oMinuteLockAsyncResult.Result;
            // Refresh item from the server to read locks
            oFile.RefreshAsync(function(oAsyncResult) {
                for (var i = 0, l = oFile.ActiveLocks.length; i < l; i++) {
                    /** @typedef {ITHit.WebDAV.Client.LockInfo} oLockInfo */
                    var oLockInfo = oFile.ActiveLocks[i];
                    var sTimeOut = oLockInfo.TimeOut === -1 ? "Infinite" : oLockInfo.TimeOut + ' sec';
                    // Show item locks
                    console.log([
                        oLockInfo.Owner,
                        oLockInfo.LockToken.Href,
                        oLockInfo.LockToken.LockToken,
                        oLockInfo.LockScope,
                        oLockInfo.Deep,
                        sTimeOut
                    ].join(' '));
                }
                fCallback(oFile, oInfiniteLockInfo, oMinuteLockInfo);
            });
        });
    });
});