Webdav/docs/plugin_architecture.txt

eZ Component: Webdav, Plugin-Architecture
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:Author: Kore Nordmann, Tobias Schlitt
:Revision: $Rev$
:Date: $Date$
:Status: Draft

.. contents::

Scope
=====

The scope of this document is to give authors of plugins for the Webdav
component an introduction on how to implement new plugins. If you just want to
use the Webdav component, this document does not contain any relevant
information for you.

.. attention::
   The Plugin-API is not part of the Webdav component in version 1.0, but will
   be part of a later release.

Overview
========

The Webdav component provides a flexible plugin architecture to extend the
features of the component. A plugin is a certain set of classes, that
represents a certain functionality for the component. Every plugin must ship a
class that extends ezcWebdavPluginConfiguration and is used to add the plugin
to the component.

To interact with the component, a plugin can assign an unlimited number of
callbacks to so called "hooks" which are offered by certain parts of the
component. A hook indicates that a certain event has occured inside the
component and informs plugins about this event. A plugin callback will receive
a defined number of parameters, wrapped into an instance of
ezcWebavPluginParameters, it may work on and even possibly alter.

A callback assigned to a hook should usually not return anything, because
procesing of further callbacks will be stopped immediatelly in this case.
Therefore, a plugin callback usually returns null and interacts with the
component through the received parameters. Some special hooks expect a plugin
callback to return a certain object to stop processing of further callbacks by
intention and to inject a certain object into the component. If this is the
case, it is explicitly mentioned in the hook description.

Plugin configuration
====================

Every plugin must provide a class that extends ezcWebdavPluginConfiguration and
is used to activate the plugin in the server. This class is instantiated by the
user and submitted to ezcWebdavPluginRegistry->registerPlugin(). After that,
the plugin is registered and active.

The configuration class expects 2 abstract methods to be implemented, which are
used by the server to determine all necessary information about the plugin:

getNamespace()
  This method must return a string, representing a unique identifier for the
  plugin, called the namespace of the plugin. This sting should usually reflect
  the plugins name for clearity. A good namespace identifier would e.g. be
  "ezcWebdavLockPlugin".
getHooks()
  The server calls this method on the configuration object to receive an array
  containing all hooks the plugin wants to assign to, including the callbacks
  for each hook. The detailed structure of this definition can be found in the
  Webdav API docs.

Additionally, the server will call the init() method on the configuration
object, which by default does nothing. A plugin can overwrite this method, to
perform any kind of setup work.

Hooks
=====

Plugin hooks are catgorized by the class that issues them. 3 classes of the
Webdav component currently support the following plugin hooks:

ezcWebdavTransport
------------------

The ezcWebdavTransport class offers hooks that are related to request parsing
and response handling. To give you the most comfortable way of interacting
with these processes, for each of the request parsing and response handling
methods offer a "before" and an "after" hook. The "before" hook is announced
right before the speicifc method is invoked, while "after" announcement
happens right after the method has been called.

Additionally a hook for parsing unknown requests and one for handling unknown
response objects is announced if such cases occur.


beforeParseCopyRequest
``````````````````````

This hook is announced right before a COPY request is parsed. It retrieves the
parameters

path
  The path contained in the request URI, already transformed by an
  ezcWebdavPathFactory, as a string.
body
  The body contained in the request as a string.

Both parameters are submitted by reference, so any changes made to them will
have effects on other mechanisms accessing those. Therefore, all manipulations
must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterParseCopyRequest
`````````````````````

Analogous to the "before" hook of this method, this hook is announced right
after a COPY request has been parsed. The parameter received by the callbacks
assigned to this hook receives the following parameters:

request
  The request object parsed from the request data (ezcWebdavRequest).

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore, all manipulations must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeParseDeleteRequest
````````````````````````

This hook is announced right before a DELETE request is parsed. It retrieves the
parameters

path
  The path contained in the request URI, already transformed by an
  ezcWebdavPathFactory, as a string.
body
  The body contained in the request as a string.

Both parameters are submitted by reference, so any changes made to them will
have effects on other mechanisms accessing those. Therefore, all manipulations
must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterParseDeleteRequest
```````````````````````

Analogous to the "before" hook of this method, this hook is announced right
after a DELETE request has been parsed. The parameter received by the callbacks
assigned to this hook receives the following parameters:

request
  The request object parsed from the request data (ezcWebdavRequest).

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore, all manipulations must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeParseGetRequest
`````````````````````

This hook is announced right before a GET request is parsed. It retrieves the
parameters

path
  The path contained in the request URI, already transformed by an
  ezcWebdavPathFactory, as a string.
body
  The body contained in the request as a string.

Both parameters are submitted by reference, so any changes made to them will
have effects on other mechanisms accessing those. Therefore, all manipulations
must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterParseGetRequest
````````````````````

Analogous to the "before" hook of this method, this hook is announced right
after a GET request has been parsed. The parameter received by the callbacks
assigned to this hook receives the following parameters:

request
  The request object parsed from the request data (ezcWebdavRequest).

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore, all manipulations must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeParseHeadRequest
``````````````````````

This hook is announced right before a HEAD request is parsed. It retrieves the
parameters

path
  The path contained in the request URI, already transformed by an
  ezcWebdavPathFactory, as a string.
body
  The body contained in the request as a string.

Both parameters are submitted by reference, so any changes made to them will
have effects on other mechanisms accessing those. Therefore, all manipulations
must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterParseHeadRequest
`````````````````````

Analogous to the "before" hook of this method, this hook is announced right
after a HEAD request has been parsed. The parameter received by the callbacks
assigned to this hook receives the following parameters:

request
  The request object parsed from the request data (ezcWebdavRequest).

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore, all manipulations must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeParseMakeCollectionRequest
````````````````````````````````

This hook is announced right before a MKCOL request is parsed. It retrieves the
parameters

path
  The path contained in the request URI, already transformed by an
  ezcWebdavPathFactory, as a string.
body
  The body contained in the request as a string.

Both parameters are submitted by reference, so any changes made to them will
have effects on other mechanisms accessing those. Therefore, all manipulations
must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterParseMakeCollectionRequest
```````````````````````````````

Analogous to the "before" hook of this method, this hook is announced right
after a MKCOL request has been parsed. The parameter received by the callbacks
assigned to this hook receives the following parameters:

request
  The request object parsed from the request data (ezcWebdavRequest).

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore, all manipulations must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeParseMoveRequest
``````````````````````

This hook is announced right before a MOVE request is parsed. It retrieves the
parameters

path
  The path contained in the request URI, already transformed by an
  ezcWebdavPathFactory, as a string.
body
  The body contained in the request as a string.

Both parameters are submitted by reference, so any changes made to them will
have effects on other mechanisms accessing those. Therefore, all manipulations
must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterParseMoveRequest
`````````````````````

Analogous to the "before" hook of this method, this hook is announced right
after a MOVE request has been parsed. The parameter received by the callbacks
assigned to this hook receives the following parameters:

request
  The request object parsed from the request data (ezcWebdavRequest).

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore, all manipulations must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeParseOptionsRequest
`````````````````````````

This hook is announced right before a OPTIONS request is parsed. It retrieves the
parameters

path
  The path contained in the request URI, already transformed by an
  ezcWebdavPathFactory, as a string.
body
  The body contained in the request as a string.

Both parameters are submitted by reference, so any changes made to them will
have effects on other mechanisms accessing those. Therefore, all manipulations
must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterParseOptionsRequest
`````````````````````````

Analogous to the "before" hook of this method, this hook is announced right
after a OPTIONS request has been parsed. The parameter received by the callbacks
assigned to this hook receives the following parameters:

request
  The request object parsed from the request data (ezcWebdavRequest).

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore, all manipulations must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeParsePropFindRequest
``````````````````````````

This hook is announced right before a PROPFIND request is parsed. It retrieves the
parameters

path
  The path contained in the request URI, already transformed by an
  ezcWebdavPathFactory, as a string.
body
  The body contained in the request as a string.

Both parameters are submitted by reference, so any changes made to them will
have effects on other mechanisms accessing those. Therefore, all manipulations
must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterParsePropFindRequest
`````````````````````````

Analogous to the "before" hook of this method, this hook is announced right
after a PROPFIND request has been parsed. The parameter received by the callbacks
assigned to this hook receives the following parameters:

request
  The request object parsed from the request data (ezcWebdavRequest).

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore, all manipulations must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeParsePropPatchRequest
```````````````````````````

This hook is announced right before a PROPPATCH request is parsed. It retrieves the
parameters

path
  The path contained in the request URI, already transformed by an
  ezcWebdavPathFactory, as a string.
body
  The body contained in the request as a string.

Both parameters are submitted by reference, so any changes made to them will
have effects on other mechanisms accessing those. Therefore, all manipulations
must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterParsePropPatchRequest
``````````````````````````

Analogous to the "before" hook of this method, this hook is announced right
after a PROPPATCH request has been parsed. The parameter received by the callbacks
assigned to this hook receives the following parameters:

request
  The request object parsed from the request data (ezcWebdavRequest).

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore, all manipulations must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeParsePutRequest
`````````````````````

This hook is announced right before a PUT request is parsed. It retrieves the
parameters

path
  The path contained in the request URI, already transformed by an
  ezcWebdavPathFactory, as a string.
body
  The body contained in the request as a string.

Both parameters are submitted by reference, so any changes made to them will
have effects on other mechanisms accessing those. Therefore, all manipulations
must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterParsePutRequest
````````````````````

Analogous to the "before" hook of this method, this hook is announced right
after a PUT request has been parsed. The parameter received by the callbacks
assigned to this hook receives the following parameters:

request
  The request object parsed from the request data (ezcWebdavRequest).

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore, all manipulations must be performed very carefully.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeProcessCopyResponse
`````````````````````````

This hook is announce directly before a ezcWebdavCopy response object is
serialized and send back to the client. The parameter submitted to the hook is
the response object that is going to be serialized.

response
  The response object that is going to be serialized.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterProcessCopyResponse
````````````````````````

This hook is announce directly after a ezcWebdavCopy response object has been
serialized to be send back to the client. The parameter submitted to the hook is
the instance of ezcWebdavDisplayInformation that was created by the processing
method.

result
  The ezcWebdavDisplayInformation instance representing the data to send to the
  client.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeProcessDeleteResponse
```````````````````````````

This hook is announce directly before a ezcWebdavDelete response object is
serialized and send back to the client. The parameter submitted to the hook is
the response object that is going to be serialized.

response
  The response object that is going to be serialized.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterProcessDeleteResponse
``````````````````````````

This hook is announce directly after a ezcWebdavDelete response object has been
serialized to be send back to the client. The parameter submitted to the hook is
the instance of ezcWebdavDisplayInformation that was created by the processing
method.

result
  The ezcWebdavDisplayInformation instance representing the data to send to the
  client.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeProcessErrorResponse
``````````````````````````

This hook is announce directly before a ezcWebdavError response object is
serialized and send back to the client. The parameter submitted to the hook is
the response object that is going to be serialized.

response
  The response object that is going to be serialized.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterProcessErrorResponse
`````````````````````````

This hook is announce directly after a ezcWebdavError response object has been
serialized to be send back to the client. The parameter submitted to the hook is
the instance of ezcWebdavDisplayInformation that was created by the processing
method.

result
  The ezcWebdavDisplayInformation instance representing the data to send to the
  client.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeProcessGetCollectionResponse
``````````````````````````````````

This hook is announce directly before a ezcWebdavGetCollection response object is
serialized and send back to the client. The parameter submitted to the hook is
the response object that is going to be serialized.

response
  The response object that is going to be serialized.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterProcessGetCollectionResponse
`````````````````````````````````

This hook is announce directly after a ezcWebdavGetCollection response object has been
serialized to be send back to the client. The parameter submitted to the hook is
the instance of ezcWebdavDisplayInformation that was created by the processing
method.

result
  The ezcWebdavDisplayInformation instance representing the data to send to the
  client.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeProcessGetResourceResponse
````````````````````````````````

This hook is announce directly before a ezcWebdavGetResource response object is
serialized and send back to the client. The parameter submitted to the hook is
the response object that is going to be serialized.

response
  The response object that is going to be serialized.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterProcessGetResourceResponse
```````````````````````````````

This hook is announce directly after a ezcWebdavGetResource response object has been
serialized to be send back to the client. The parameter submitted to the hook is
the instance of ezcWebdavDisplayInformation that was created by the processing
method.

result
  The ezcWebdavDisplayInformation instance representing the data to send to the
  client.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeProcessHeadResponse
`````````````````````````

This hook is announce directly before a ezcWebdavHead response object is
serialized and send back to the client. The parameter submitted to the hook is
the response object that is going to be serialized.

response
  The response object that is going to be serialized.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterProcessHeadResponse
````````````````````````

This hook is announce directly after a ezcWebdavHead response object has been
serialized to be send back to the client. The parameter submitted to the hook is
the instance of ezcWebdavDisplayInformation that was created by the processing
method.

result
  The ezcWebdavDisplayInformation instance representing the data to send to the
  client.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeProcessMakeCollectionResponse
```````````````````````````````````

This hook is announce directly before a ezcWebdavMakeCollection response object is
serialized and send back to the client. The parameter submitted to the hook is
the response object that is going to be serialized.

response
  The response object that is going to be serialized.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterProcessMakeCollectionResponse
``````````````````````````````````

This hook is announce directly after a ezcWebdavMakeCollection response object has been
serialized to be send back to the client. The parameter submitted to the hook is
the instance of ezcWebdavDisplayInformation that was created by the processing
method.

result
  The ezcWebdavDisplayInformation instance representing the data to send to the
  client.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeProcessMoveResponse
`````````````````````````

This hook is announce directly before a ezcWebdavMove response object is
serialized and send back to the client. The parameter submitted to the hook is
the response object that is going to be serialized.

response
  The response object that is going to be serialized.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterProcessMoveResponse
````````````````````````

This hook is announce directly after a ezcWebdavMove response object has been
serialized to be send back to the client. The parameter submitted to the hook is
the instance of ezcWebdavDisplayInformation that was created by the processing
method.

result
  The ezcWebdavDisplayInformation instance representing the data to send to the
  client.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeProcessMultiStatusResponse
````````````````````````````````

This hook is announce directly before a ezcWebdavMultistatus response object is
serialized and send back to the client. The parameter submitted to the hook is
the response object that is going to be serialized.

response
  The response object that is going to be serialized.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterProcessMultiStatusResponse
```````````````````````````````

This hook is announce directly after a ezcWebdavMultistatus response object has been
serialized to be send back to the client. The parameter submitted to the hook is
the instance of ezcWebdavDisplayInformation that was created by the processing
method.

result
  The ezcWebdavDisplayInformation instance representing the data to send to the
  client.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeProcessOptionsResponse
````````````````````````````

This hook is announce directly before a ezcWebdavOptions response object is
serialized and send back to the client. The parameter submitted to the hook is
the response object that is going to be serialized.

response
  The response object that is going to be serialized.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterProcessOptionsResponse
```````````````````````````

This hook is announce directly after a ezcWebdavOptions response object has been
serialized to be send back to the client. The parameter submitted to the hook is
the instance of ezcWebdavDisplayInformation that was created by the processing
method.

result
  The ezcWebdavDisplayInformation instance representing the data to send to the
  client.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeProcessPropFindResponse
`````````````````````````````

This hook is announce directly before a ezcWebdavPropFind response object is
serialized and send back to the client. The parameter submitted to the hook is
the response object that is going to be serialized.

response
  The response object that is going to be serialized.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterProcessPropFindResponse
````````````````````````````

This hook is announce directly after a ezcWebdavPropFind response object has been
serialized to be send back to the client. The parameter submitted to the hook is
the instance of ezcWebdavDisplayInformation that was created by the processing
method.

result
  The ezcWebdavDisplayInformation instance representing the data to send to the
  client.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeProcessPropPatchResponse
``````````````````````````````

This hook is announce directly before a ezcWebdavPropPatch response object is
serialized and send back to the client. The parameter submitted to the hook is
the response object that is going to be serialized.

response
  The response object that is going to be serialized.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterProcessPropPatchResponse
`````````````````````````````

This hook is announce directly after a ezcWebdavPropPatch response object has been
serialized to be send back to the client. The parameter submitted to the hook is
the instance of ezcWebdavDisplayInformation that was created by the processing
method.

result
  The ezcWebdavDisplayInformation instance representing the data to send to the
  client.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeProcessPutResponse
````````````````````````

This hook is announce directly before a ezcWebdavPut response object is
serialized and send back to the client. The parameter submitted to the hook is
the response object that is going to be serialized.

response
  The response object that is going to be serialized.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterProcessPutResponse
````````````````````````

This hook is announce directly after a ezcWebdavPut response object has been
serialized to be send back to the client. The parameter submitted to the hook is
the instance of ezcWebdavDisplayInformation that was created by the processing
method.

result
  The ezcWebdavDisplayInformation instance representing the data to send to the
  client.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

parseUnknownRequest
```````````````````

If ezcWebdavTransport receives a request with an unknown request method, this
hook is announced. The first ezcWebdavRequest object (or ezcWebdavErrorResponse
on error) returned from any of the assigned callbacks will be used for further
proceeding and no more callbacks will be performed.

The parameters send by this hook are:

path
  The path contained in the request URI, already transformed by an
  ezcWebdavPathFactory, as a string.
body
  The body contained in the request as a string.
requestMethod
  The request method as provided by $_SERVER.

Both parameters are submitted by reference, so any changes made to them will
have effects on other mechanisms accessing those. Therefore, all manipulations
must be performed very carefully.

A return value is only expected, if the request was parsed successfully by the
plugin or if the plugin wants to take care about the unknown request, but was
not able to parse it. In the first (success) case the callback must return an
instance of ezcWebdavRequest, in the second an instance of
ezcWebdavErrorResponse. If a plugin returns any value beside null, the
processing of callbacks is stopped and the return value is taken for further
processing.

handleUnknownResponse
`````````````````````

This special hook is announced, if ezcWebdavTransport receives an instance of
ezcWebdavResponse that it can not handle. The first callback that reacts on
this hook and returns a value beside null will be chosen to handle the
response. The reacting callback must return an instance of
ezcWebdavDisplayInformation that contains the information to be send to the
client.

Parameters send by this hook are:

response
  The instance of ezcWebdavResponse that shall be serialized.

A return value is only expected, if the response was handled successfully by
the plugin or if the plugin wants to take care about the unknown response, but
was not able to handle it. In any case, if the plugin feels responsible for the
request, it must return an instance of ezcWebdavDisplayInformation which is
then taken to send information to the client. If a plugin returns any value
beside null, the processing of callbacks is stopped and the return value is
taken for further processing.

ezcWebdavPropertyHandler
------------------------

While the hooks offered by the ezcWebdavTransport class are related to parsing
and processing ezcWebdavRequest/ezcWebdavResponse objects, the hooks offere by
ezcWebdavPropertyHandler are related to parsing and processing properties. The
class offers classes related to dead and live properties as detailed below:

beforeExtractLiveProperty
`````````````````````````

Live properties are such properties that are validated and taken care of by the
server instance, in contrast to dead properties which are only stored by the
server but not validated or even processed.

This hook is announced right before whenever the component attempts to parse a
live property. This might be either that a request contained the XML
representation of the property or that a backend needs to restore the property
from a stored XML representation.

Parameters submitted by this hook are:

domElement
  The DOM element that contains the live property to parse.
xmlTool
  The instance of ezcWebdavXmlTool that must be used for any XML related
  operations.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterExtractLiveProperty
````````````````````````

Live properties are such properties that are validated and taken care of by the
server instance, in contrast to dead properties which are only stored by the
server but not validated or even processed.

This hook is announced right after whenever the component has parsed a live
property. This might be either that a request contained the XML representation
of the property or that a backend needs to restore the property from a stored
XML representation.

Parameters submitted by this hook are:

property
  The property object that was just parsed (ezcWebdavLiveProperty).
xmlTool
  The instance of ezcWebdavXmlTool that must be used for any XML related
  operations.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeExtractDeadProperty
`````````````````````````

A dead property in WebDAV terms is a named container that contains any
arbitrary XML data, being attached to a resource. The server will not take any
care about the contents of a dead property, but just store and restore it on
request.

This hook is announced right before whenever the component attempts to parse a
dead property. This might be either that a request contained the XML
representation of the property or that a backend needs to restore the property
from a stored XML representation.

Parameters submitted by this hook are:

domElement
  The DOM element that contains the live property to parse.
xmlTool
  The instance of ezcWebdavXmlTool that must be used for any XML related
  operations.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterExtractDeadProperty
````````````````````````

A dead property in WebDAV terms is a named container that contains any
arbitrary XML data, being attached to a resource. The server will not take any
care about the contents of a dead property, but just store and restore it on
request.

This hook is announced right after whenever the component has parsed a dead
property. This might be either that a request contained the XML representation
of the property or that a backend needs to restore the property from a stored
XML representation.

Parameters submitted by this hook are:

property
  The property object that was just parsed (ezcWebdavDeadProperty).
xmlTool
  The instance of ezcWebdavXmlTool that must be used for any XML related
  operations.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeSerializeLiveProperty
```````````````````````````

Live properties are such properties that are validated and taken care of by the
server instance, in contrast to dead properties which are only stored by the
server but not validated or even processed.

This hook is announced right before whenever the component attempts serialize
an instance of ezcWebdavLiveProperty to its XML representation. This might
happen if a property is to be send in a response or if a backend is going to
store the property in its XML representation.

Parameters submitted by this hook are:

property
  The property object that is to be serialized (ezcWebdavLiveProperty).
xmlTool
  The instance of ezcWebdavXmlTool that must be used for any XML related
  operations.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

afterSerializeLiveProperty
``````````````````````````

Live properties are such properties that are validated and taken care of by the
server instance, in contrast to dead properties which are only stored by the
server but not validated or even processed.

This hook is announced right after whenever the component has serialized
an instance of ezcWebdavLiveProperty to its XML representation. This might
happen if a property is to be send in a response or if a backend is going to
store the property in its XML representation.

Parameters submitted by this hook are:

domElement
  The DOMElement instance representing the property in XML (ezcWebdavLiveProperty).
xmlTool
  The instance of ezcWebdavXmlTool that must be used for any XML related
  operations.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

beforeSerializeDeadProperty
```````````````````````````

A dead property in WebDAV terms is a named container that contains any
arbitrary XML data, being attached to a resource. The server will not take any
care about the contents of a dead property, but just store and restore it on
request.

This hook is announced right before whenever the component attempts serialize
an instance of ezcWebdavDeadProperty to its XML representation. This might
happen if a property is to be send in a response or if a backend is going to
store the property in its XML representation.

Parameters submitted by this hook are:

property
  The property object that is to be serialized (ezcWebdavDeadProperty).
xmlTool
  The instance of ezcWebdavXmlTool that must be used for any XML related
  operations.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.


afterSerializeDeadProperty
``````````````````````````

A dead property in WebDAV terms is a named container that contains any
arbitrary XML data, being attached to a resource. The server will not take any
care about the contents of a dead property, but just store and restore it on
request.

This hook is announced right after whenever the component has serialized
an instance of ezcWebdavDeadProperty to its XML representation. This might
happen if a property is to be send in a response or if a backend is going to
store the property in its XML representation.

Parameters submitted by this hook are:

domElement
  The DOMElement instance representing the property in XML (ezcWebdavDeadProperty).
xmlTool
  The instance of ezcWebdavXmlTool that must be used for any XML related
  operations.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

The return value of callbacks assigned to this hook will be ignored and
therefore may not occur, since processing of additional callbacks will be
stopped as soon as a return value is send.

extractUnknownLiveProperty
``````````````````````````

Live properties are such properties that are validated and taken care of by the
server instance, in contrast to dead properties which are only stored by the
server but not validated or even processed.

If the ezcWebdavPropertyHandler attempts to parse a live property from XML,
which it does not know by itself, this hook is announced. As soon as the first
callback returns an instance of ezcWebdavLiveProperty, the hook announcement is
ended and the returned object will be used.

Parameters submitted by this hook are:

domElement
  The DOMElement instance representing the property in XML (ezcWebdavDeadProperty).
xmlTool
  The instance of ezcWebdavXmlTool that must be used for any XML related
  operations.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

A return value from a callback is only expected, if the callback was able to
parse the live property. In this case, it must return the created instance of
ezcWebdavLiveProperty, containing the property data. If a callback returned a
value, no further callbacks will be dispatched.

If a plugin decides to assign a callback to this hook to parse custom live
properties, it must also assign to the serializeUnknownLiveProperty hook, to
ensure that the property object can also be serialized back to an XML
representation.

serializeUnknownLiveProperty
````````````````````````````

Live properties are such properties that are validated and taken care of by the
server instance, in contrast to dead properties which are only stored by the
server but not validated or even processed.

If the ezcWebdavPropertyHandler attempts to serialize a live property to XML,
which it does not know by itself, this hook is announced. As soon as the first
callback returns an instance of ezcWebdavLiveProperty, the hook announcement is
ended and the returned object will be used.

Parameters submitted by this hook are:

property
  The property object that is to be serialized (ezcWebdavDeadProperty).
xmlTool
  The instance of ezcWebdavXmlTool that must be used for any XML related
  operations.
parentElement
  This instance of DOMElement will contaoin the returned DOMElement later. Its
  ownerDocument must be used to create or import the nodes returned, so that
  they can be appended to the parentElement. The appending may not be handled
  by the callback itself.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

A return value from a callback is only expected, if the callback was able to
serialize the live property. In this case, it must return the created instance
of DOMElement, containing the property data as XML. If a callback returned a
value, no further callbacks will be dispatched.

If a plugin decides to assign a callback to this hook to serialize custom live
properties, it must also assign to the parseUnknownLiveProperty hook, to ensure
that the property object can also be from an XML representation.
                 
ezcWebdavServer
---------------

The main WebDAV server object receives any request that was parsed by
ezcWebdavTransport and dispatches it to the backend to use. On the way back it
receives a response from the backend to pass it to ezcWebdavTransport again for
serializating the contained and sending it to the client.

To handle unknown requests and responses, as well as to react on certain
requests or responses, the server object offers 2 important hooks.

receivedRequest
```````````````

This hook is announced whenever a request is received by the server through
ezcWebdavTransport. The hook should be used by plugins for 2 reasons:

1. React on request objects without affecting the further process.
2. React on request objects, but replacing the further process.

If a plugin just wants to be informed about certain requests, it must not
return a value from its callback. If this is the case, further callbacks
assigned to this hook will be processed.

In the second case, the plugin wants to take care for processing the request
itself and must return an instance of ezcWebdavResponse afterwards. If this is
the case, dispatching of callbacks for this hook is stopped and the
generatedResponse hook is announced for the response, right before it is send
to ezcWebdavTransport for being serialized and send. Note that the processing
of the request by the backend will not take place in this case. If the backend
should still take care about a request, no return value may be returned by any
assigned callback.

A plugin may choose to handle a request completly on its own and may use any of
the public API that is provided by the server, that is create new request
objects and let them get processed by server and backend.

Parameters submitted to this hook are:

request
  The instance of ezcWebdavRequest that was received from ezcWebavTransport.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

generatedResponse
`````````````````

Whenever the server receives an instance of ezcWebdavReponse from either the
backend or from a plugin callback, this hook will be announced. The hook allows
plugins to be informed about every response that is send to the client. Plugin
callbacks can react on these responses or even replace them.

To replace a response, the plugin just needs to exchange the received
parameter. The callback must not return any value. If it does, the processing
of further callbacks will be stopped immediatelly, but the returned value will
be ignored.

If a callback replaced the response object with a different instance of
ezcWebdavResponse, all further callbacks are affected by this change and will
receive the new response instead of the initial one.

Parameters submitted to this hook are:

response
  The instance of ezcWebdavResponse that should be send by ezcWebavTransport.

Any changes made to the parameter will have effects on other mechanisms
accessing it. Therefore all manipulations must be performed very carefully and
should be avoided if possible.

API
===

Every plugin may access any public API elements of the Webdav component to
perform any necessary tasks. To access the correct module for the right task,
plugins should follow the following hints to ensure correct working.

Central server
--------------

The central entrance point of the Webdav component is the class
ezcWebdavServer, which coordinates all other modules. The singleton instance of
this class acts also as the central registry for all modules, which can be
accessed through the servers properties, once it is initialized.

The singleton instance of the server can be access using
ezcWebdavServer->getInstance() and offers the following attributes to be used
by plugins:

$pathFactory
  This attribute contains the instance of ezcWebdavPathFactory that has been
  configured by the user to be used. In most cases, a plugin will not need to
  access this one, since it only acts on processed pathes. Only if new request
  data is parsed or response data needs to be serialized, a plugin might need
  to access to path factory to parse an URI into a path or the other way
  around.
$xmlTool
  The instance of eczWebdavXmlTool is used in the transport layer and while
  dealing with properties. When dealing with parsing/processing request or
  response data, this attribute of the server should be accessed for XML
  handling. In case of property related hooks, the XML tool to use will be
  provided as a parameter, which _must_ be used in this case.
$propertyHandler
  The property handler object stored in this attribute is used to parse live
  and dead properties from XML and serialize them to XML. A plugin can also
  make use of this functionality. The attribute contains an instance of
  ezcWebdavPropertyHandler.
$headerHandler
  Analogous to $propertyHandler, this attribute contains an instance of
  ezcWebdavHeaderHandler, which can be used by a plugin to access and parse
  headers sent with the request.
$transport
  The main element of the transport layer is kept in this attribute: An
  instance of ezcWebdavTransport, which is responsible for parsing requests and
  for serializing and sending of responses. Normally, a plugin should not need
  to access this attribute.
$backend
  The backend used by the server is hold in this attribute, an instance of
  ezcWebdavBackend. While a plugin could theoretically access the backends
  methods directly, it is recommended to interact with it using request and
  response objects. A newly created request object can be send to the backend
  using ezcWebdavBackend->performRequest() which will return a response object
  for evaluation. This will work with every backend, while non-standardized
  methods might be missing in certain backends, which might break the plugin.
 
Data transport
--------------

It often occurs, that a plugin needs to store data related to an
infrastructural element of the component (request/response/property) and to
access this data later during the request. To avoid that every plugin needs to
implement a storage engine for this on its own, all infrastructual objects
allow you to attach certain data to them and read this data later. Note that
the data is not presistent between requests, but is only valid during the
request.

Intfrastructural elements are all instances of

- ezcWebdavRequest
- ezcWebdavRepsonse
- ezcWebdavProperty

and derived classes. All of these extend ezcWebdavInfrastructureBase, which
offers the data storage mechanism for plugins.

To attach data to such an object, the method setPluginData() is used, expecting
the namespace of the plugin a key for the data and the data itself. Later, the
data can be restored from the same object, by using its getPluginData() with
the namespace and key. The methods hasPluginData() and removePluginData() are
also available to maintain the storage.


..
   Local Variables:
   mode: rst
   fill-column: 79
   End: 
   vim: et syn=rst tw=79