Bric::Util::WebDav(3)

NAME
Bric::Util::WebDav - Placeholder for Bricolage DAV support.

DATE
$LastChangedDate: 2004-06-04 12:21:12 -0700 (Fri, 04 Jun 2004) $

VERSION
$LastChangedRevision$

DESCRIPTION
In general, to implement Bric::Util::WebDav, one must write a module that overwrites all the methods of Bric::Dav. It should be registered in the httpd.conf file with the location mapping to a key in the %HANDLER hash. When a request comes in, an object from the implementing class is instantiated, with the Apache Request Object, the method, the uri, the element from the location match, and the path following that. The handler method then calls the various methods for the WebDav request (PUT, DELETE, etc.). It expects data to be returned in the following format:

  Return Data Structure
 $return = {
 'special'  => Used for returning DECLINED
              and the like. If 'special' is sent, all
              other information will be
              ignored.

 'error'  => Used for returning simply
                the error code, i.e., 404.
                As with 'special,' if 'error' is sent,
                all other information
                will be ignored.

 'header'=> {
       'header to add' =>  Val
                    if any additional headers
                    are needed they should be
                    sent like so
       },

 'status' =>  200 or 207 etc.,

 'type'   =>  Content-Type header text/html,
              text/xml etc.

 'body'   =>  Body to be sent

 };

 The module you are writing should implement the following methods:

  new
Accepts the Apache request object, the uri, the uri with the first element stripped out, the first element, and the method. Returns a blessed object.

  get
Returns a body, type, and status from the proper uri in the format described above.

  put
Receives a body of a document and places it in the appropriate location. Returns status_code and body or error code.

  delete
For a given uri, returns status_code and body, or error_code, or 207 Multi-Status with XML body.

  mkcol
Receives a body and creates a collection for a given uri. Returns status_code and body or error code.

  do_copy
Receives a Destination, Depth, Overwrite, and Body and makes a duplicate resource at a given destination. Returns status_code and body, or error_code, or 207 Multi-Status with XML body.

  move
'Move' is the equivalent of 'copy' followed by a 'delete' of the initial resource. The rules that apply for 'copy' and 'delete' apply to 'move.'

  lock
Receives Depth, Timeout, If, Lock-Token Headers and XML from Body Attempt to Lock Resource. If there is no Body it is an attempt to refresh the lock. Should return errors_code, 200 Success with an XML body, or 207 Multi-Status with XML body.

  unlock
Receives Lock-Token and attempts to unlock resource held by said token. Returns success_code and body or error_code.

HANDLER
The handler takes the request, processes the uri, and determines what class handles the backend based upon the Handler hash. It then dispatches the valid request to the subroutines laid out in the Allowed hash. These will do a little more information gathering from the request, then dispatch the request to the proper methods within the class initiated earlier. The methods return the appropriate codes, body, headers, etc.

$wd = new Bric::Util::WebDav($r);
    throws:

    None

    side effects:

    None

    notes:

    processes $r to pull Dav specific info out

$return = $self->options();
    throws:

    None

    side effects:

    None

    notes:

    Accepts a Webdav Object. Returns a Hashref containing a hashref whose keys are the Allow Header Values and the Dav Header value. When called it provides a client with a list of the allowed methods and establishes this as a Dav compliant Server.

$return = $self->proppatch($impl_obj);
    throws:

    None

    side effects:

    None

    notes:

    Accepts a Webdav object and an implementation object. Returns a hash ref of return info. Sends the Depth Header and the body to the implementation object's propfind method. Returns the value returned for that call which should be a 207 status code with an XML formatted response body or an error code.

$self->proppatch($impl_obj);
    throws:

    None

    side effects:

    None

    notes:

    Accepts a Webdav object and an implementation object. Returned values: a hash ref of return info. Sends the body to the implementation object's proppatch method. Returns the value returned for that method which should be a 207 status code with an XML formatted response body or an error code.

$return = $self->get($impl_obj);
    throws:

    None

    side effects:

    None

    notes:

    Accepts a Webdav object and an implementation object. Returned values: a hash ref of return info. Passes no additional data. Expects to receive a status and body, an error_code or a special.

$return = $self->put($impl_obj);
    throws:

    None

    side effects:

    None

    notes:

    Accepts a Webdav object and an implementation object. Returned values: a hash ref of return info. Passes the data contained in the body. Expects to receive a status and body, an error code, a 207 and XML body or a special. Places or replaces an element at said uri. If PUT tries to place an item without proper parentage it should return a 409 Conflict Code. So as not to override the MKCOL command, put may not be a col resource.

$return = $self->do_delete($impl_obj);
    throws:

    None

    side effects:

    None

    notes:

    Accepts a Webdav object and an implementation object. Returned values: a hash ref of return info. Passes no additional data to the implementation object. Expects to receive a status of 204, an error code, a 207 and XML body or a special. Removes the resource of a given uri if called on a collection (dir). It is a Depth=Infinity Request if error response in 207 Fashion unless 424 Failed Dependency. If there is a failure here it should be returned in XML data, unless it is a not found or Failed Discrepancy Error.

$return = $self->mkcol($impl_obj);
    throws:

    None

    side effects:

    None

    notes:

    Accepts a Webdav object and an implementation object. Returned values: a hash ref of return info. Passes the body of the request (if any) if expects to receive a 201 with a body, or an error code. mkcol is a handler for MKCOL requests will respond with the following status codes: 201 (Created) - On Success 403 (Forbidden) - On Failure Not Allowed 405 (Method Not Allowed) - Name already Taken 409 (Conflict) The ancestors do not exist 415 (Unsupported Media Type) Body info type not supported 507 (Insufficient Storage) All ancestors must exist for this to succeed and the uri cannot already be taken.

$return = $self->copy($impl_obj);
    throws:

    None

    side effects:

    None

    notes:

    Accepts a Webdav object and an implementation object. Returned values: a hash ref of return info. Sends the values of the Destination, Depth, and Override Headers and the body of the request. Expects to receive a 201 with a body, an error code, a 207 with an XML Body, or a special. Copies a resource and all its properties at x uri to y uri. Copy should work for depth headers of 0 and infinity. Infinity gets a full recursive copy. 0 copies the collection and its resources but not its members. Copy can also contain an overwrite header. If so, a delete is performed first.

$return = $self->move($impl_obj);
    throws:

    None

    side effects:

    None

    notes:

    Accepts a Webdav object and an implementation object. Returned values: a hash ref of return info. Move is the equivalent of a Copy request followed by a Delete request. All the rules governing both apply here.

$return = $self->lock($impl_obj);
    throws:

    None

    side effects:

    None

    notes:

    Accepts a Webdav object and an implementation object. Returned values: a hash ref of return info. Sends the Values of the Depth, Timeout, If, and Lock-Token Headers. Expects to receive a 200 with XML body, error code, a 207 with XML, or a special. Performs a lock at said uri. Accepts Depth, Timeout, If, Lock-Token Headers, XML in the Body.

$self->unlock($impl_obj);
    throws:

    None

    side effects:

    None

    notes:

    Accepts a Webdav object and an implementation object. Returned values: a hash ref of return info. Sends the Lock-Token header. Expects to receive a 204 success code or an error_code or a 207 with XML body. Unlocks resource at said uri with associated lock-token.

PRIVATE FUNCTIONS
None

PRIVATE CLASS METHODS
None

PRIVATE INSTANCE METHODS

$body = $wd->_get_body();
    throws:

    None

    side effects:

    None

    notes:

    Accepts a WebDav object Returns a Scalar of the contents of the body of the request

@header_values = $wd->_get_headers(@header_names);
    throws:

    None

    side effects:

    None

    notes:

    Accepts a WebDav object and a list of Named headers Returns a list of their values

AUTHOR
michael soderstrom (miraso@pacbell.net)