NAME

Net::DAV::LockManager - Provides support for WebDAV locking

VERSION

This document describes Net::DAV::LockManager version 1.305.

SYNOPSIS

    use Net::DAV::LockManager;

    my $mgr = Net::DAV::LockManager->new();
    if ( my $lock = $mgr->lock({ 'path' => '/foo/bar', 'owner' => 'fred' }) ) {
        # Fred has access.
        # Fred changes file.
        $mgr->unlock({
            'path' => '/foo/bar', 'owner' => 'fred', 'token' => $lock->{'token'}
        });
    }

DESCRIPTION

The "Net::DAV::LockManager" class provides the ability to handle resource locking in the style needed by WebDAV. It does not perform OS-level locking, but only locking in the mind of the LockManager.

The current implementation only supports exlusive locking. However, it does support indirect locks and expiration of locks. It also maintains the lock tokens and manages ownership independent of OS-level ownership.

INTERFACE

new()

Create a new "Net::DAV::LockManager" object to manage locking.

can_modify( $hashref )

Return true if the path supplied in the hash ref can be modified by the user specified in the hash ref. The hash ref supplies the following named parameters.

path: Required parameter specifying the path as a string.
owner: Required parameter specifying the user that wishes to modify the resource.
token: Optional parameter specifying the token returned when the resource (or an ancestor) was locked. This parameter may be either a single token as a string or an array reference containing token strings.

lock( $hash_ref )

Lock the path supplied in the hash ref based on the parameters in the hash ref.

path: Required parameter specifying the path as a string.
owner: Required parameter specifying the user that wishes to lock the resource.
timeout: Optional parameter specifying a number of seconds in the future to expire the lock. This is considered a request and the the actual timeout may be different.
If not supplied, a default timeout of 15 minutes is used.
depth: Optional parameter specifying the depth the locking effect. As per the WebDAV specification RFC 4918, two values are accepted 0 and infinity. A value of 0 applies only to the specified resource. The depth of infinity applies to a collection and all of its descendants.
The default value of this parameter is infinity.
scope: Optional parameter specifying the scope of the lock. The WebDAV specification supports two values: exclusive and shared. The "LockManager" only supports explusive at this time.
The default value is exclusive.
token: Optional parameter specifying the token returned when an ancestor of the the specified resource was locked. This parameter may be either a single token as a string or an array reference containing token strings.

Returns a "Net::DAV::Lock" object describing the lock on success and "undef" on failure.

refresh_lock( $hash_ref )

Updates the timeout value on the lock specified by the supplied hash ref. The hash ref contains the following named parameters.

path: Required parameter specifying the path as a string.
owner: Required parameter specifying the user that wishes to lock the resource. This name must match the owner of the lock.
token: Required parameter specifying the token returned when the resource (or an ancestor) was locked. This parameter may be either a single token as a string or an array reference containing token strings.
timeout: Optional parameter specifying a number of seconds in the future to expire the lock. This is considered a request and the the actual timeout may be different.
If not supplied, a default timeout of 15 minutes is used.

Returns a "Net::DAV::Lock" object describing the lock on success and "undef" on failure.

unlock( $hash_ref )

Unlock the resource specified by the hash ref. The hash ref specifies the resource to unlock and the credentials needed to access it. The named parameters in the hash are

path: Required parameter specifying the path as a string.
owner: Required parameter specifying the user that wishes to lock the resource. This name must match the owner of the lock.
token: Required parameter specifying the token returned when the resource was locked. This parameter may be either a single token as a string or an array reference containing token strings.

Returns true on success, false otherwise.

find_lock( $hash_ref )

Find the lock that pretects the resource listed in $hash_ref. Returns the "Net::DAV::Lock" object representing the lock, or "undef" if none is found.

The hash reference contains the path to the resource that we want to check.

path: Required parameter specifying the path as a string.

list_all_locks( $hash_ref )

List all the locks that pretect the resource listed in $hash_ref. Returns an array of "Net::DAV::Lock" objects representing the locks.

The hash reference contains the path to the resource that we want to check.

path: Required parameter specifying the path as a string.

DIAGNOSTICS

Most of the methods perform parameter validation and "die" on error. This is based on the idea that this is a mostly internal module that should be being called from non-user code. Therefore, it is the client code's responsibility to get the parameters right.

"Parameter should be a hash reference.": All methods of this class take a hash reference to support named and optional parameters.
"Missing required '%s' parameter.": The specified parameter was required but not supplied,
"Not a clean path": "LockManager" only supports absolute paths that have no ".." or "." segments and do not end in "/".
"Not a valid owner name.": The specified user name does not look like a username.
"'%s' is not a supported value for scope.": At present, "LockManager" only supports the exclusive scope for locking.
"'%s' is not a supported value for depth.": According to RFC 4918, the only supported depth values are 0 and infinity.
"'%s' is not a supported value for timeout.": Only integer timeout values are supported.

CONFIGURATION AND ENVIRONMENT

ModName requires no configuration files or environment variables.

DEPENDENCIES

None.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

AUTHOR

G. Wade Johnson "wade@cpanel.net" Erin Schoenhals "erin@cpanel.net"