/ 
Net-DAV-Server-1.300_02
River stage one • 2 direct dependents • 4 total dependents
/ Net::DAV::LockManager

NAME

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

VERSION

This document describes Net::DAV::LockManager version 1.300_01.

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

LICENSE AND COPYRIGHT

Copyright (c) 2010, cPanel, Inc. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.