11.10 DeltaV Special Mechanisms

DeltaV introduces some new WebDAV mechanisms that are useful even outside of versioning. Some of these mechanisms have already been reused in other WebDAV-based specifications.

11.10.1 REPORT Method

The REPORT method is a general-purpose request for the server to compile a useful set of information (perhaps with some input provided in the client request) and return the information as one response. There is no standard for requesting a report (the format of the body can vary), the kind of information returned in the report, or how the report response is formatted. This is defined independently for each kind of report.

A REPORT request typically addresses some resource that is essential to the report results. For example, in the version-tree report, the request is addressed to the VCR for which the version-tree is needed.

The REPORT request has a body where the root element names the report being requested. Inside the root element may be some more information used in compiling the report. In the version-tree report, the body specifies the property values to return for each version.

The complete list of reports DeltaV defines is:

  • version-tree: Lists all the versions belonging to the same version history, along with selected property values.

  • expand-property: Similar to version-tree but more powerful.

  • compare-baseline: Determines how two baselines differ and compiles the differences.

  • latest-activity-version: Tells the latest version in a version history that belongs to the named activity.

  • locate-by-history: Collects the URLs of all the VCRs in this collection that are related to one of the specified version histories.

  • merge-preview: Shows what the result of a merge would look like before it's done.

The REPORT mechanism is so broadly useful it is already used by some other standards such as the access control proposal.

11.10.2 Error Reporting

DeltaV introduces more detailed error reporting. The response codes 403 Forbidden and 409 Conflict have been extended to contain additional error information. For example, when a client attempts to check out a resource that is already checked out and that may not be checked out again, the server uses the 409 Conflict code plus a specific error element must-be-checked-in (in the DAV: namespace, of course) in the body (see Listing 11-12).

Listing 11-12 DeltaV error response.
 HTTP/1.1 409 Conflict Content-Type: text/xml; charset="utf-8" Content-Length: xxxx graphics/enter.gif <?xml version="1.0" encoding="utf-8" ?> <D:error xmlns:D="DAV:">    <D:must-be-checked-in/> </D:error> 

The DeltaV specification introduces nearly 150 such error codes. In the draft, they are labeled "precondition" and "postcondition." Either a precondition or a postcondition code may be used in either the 403 Forbidden or the 409 Conflict response body, at the discretion of the server. Implementors must read the precondition and postcondition sections very carefully because they also contain the normative information about how an operation must behave or the state the server must be in for an operation to be legal.

Many of the precondition error codes are actually ways for the server to indicate that the client has attempted to use a feature the server does not support. Some features cannot be advertised in the OPTIONS response, so only the error is available to indicate that the feature is not supported. For example, if the server does not support deleting versions, it uses the no-version-delete error code in a response to a DELETE request to a version. Clients may have to attempt the operation and see if it fails to find out if that feature is supported. This leads to poor client GUI design, as discussed in Section 11.9.2. The situation is even worse if a server supports deleting versions in some situations but not in others. Thus, if the server uses the no-version-delete error code, the client must assume that this particular version can't be deleted. The client can't assume that versions can never be deleted.

Other status codes besides 403 Forbidden and 409 Conflict continue to be appropriate exactly as already defined. For example, 400 Bad Request should still be used if a header is badly formatted.

11.10.3 Feature Discovery by OPTIONS Body

DeltaV introduces a body in the OPTIONS request to find out additional information about the system as a whole. The body is only returned if the client asks for it by using a specific type of XML body in an OPTIONS request. The body contains the options element, and the options element contains one or more of the following elements:

  • version-history-collection-set: The server returns the set of collections (or reserved namespaces) the server uses to store version-history resources.

  • workspace-collection-set: The server returns the set of collections where workspaces may be created.

  • activity-collection-set: The server returns the set of collections where activities may be created.

The successful 200 OK response from the server contains a body, and the body contains an options-response root element. The options-response element can contain any or all of the previous three elements, depending on which ones the client asked for, and each contains as many href elements as necessary to list all the special collections.

11.10.4 Feature Discovery Properties

DeltaV uses OPTIONS in the regular way to determine whether various named features are supported. Various feature strings may appear in the DAV response header to indicate support for those features.

Another way to discover functionality is to look for three new properties that must exist on any resource in a repository supporting DeltaV:

  • supported-method-set

  • supported-live-property-set

  • supported-report-set

The OPTIONS response already lists a supported set of methods in the HTTP/1.1 Allow header (Section 3.7.2), so the supported-method-set property is redundant. One advantage to the supported-method-set property is that its value can be retrieved for a number of resources at once with the PROPFIND request and a Depth header. An OPTIONS request can only address one resource at a time, so the client would have to send OPTIONS once per resource to catalog the set of supported methods.

These properties make it possible to indicate support for some DeltaV features that can't be advertised in any other way. For example, if the server supports deleting versions, it should list the DELETE method in the supported-method-set property of a version.

There remain some features that cannot be advertised by the server or discovered by the client. For example, to see if the server supports automatic versioning, it's not sufficient to see if the auto-version property is present or supported in live-property-set, because it may be present yet its value may be fixed at empty (no auto-versioning). Instead, the client must attempt to set the auto-version property to see if the server is capable of handling the various defined automatic versioning options. If the client can't set this property, it proves little, because the server might only allow auto-versioning to be configured through administration tools and not via PROPPATCH.

11.10.5 Live Property Requirements

Live and dead properties were defined in Section 4.4.1. Live properties are any properties for which the server controls the semantics or syntax. All properties defined in DeltaV are live properties, including the comment property, even though the client controls its value.

Configuration Live Properties

DeltaV defines some live properties that the user may be able to modify to change the behavior of the resource over subsequent operations. The server controls the syntax and values of these properties because the values are used as configuration information. DeltaV does not specify what error message should be used when the client attempts to set one of these properties to an illegal value. A generic 400 Bad Request response would be appropriate but not very informative.

Supporting Unsupported Live Properties
graphics/roadt_icon.jpg

DeltaV requires that when a DeltaV server does not support a DeltaV live property, the server must prevent that live property from being given a value by clients. Otherwise, other clients will believe this is the server-generated value for that live property

Allprop Semantics Changed

The DeltaV RFC effectively changed the semantics of the PROPFIND allprop request. If a server supports DeltaV, it must not return all live properties in response to even an allprop request it must return only the live properties defined in RFC2518 and the dead properties. Instead, to get the names of live properties, the client may issue a propname request or get the supported-live-property-set property. Then, the client can issue a more specific PROPFIND response to get the values of those live properties.

The propname request continues to list all property names whether live or dead or DeltaV. In addition, dead properties continue to be returned in PROPFIND requests, along with the live properties defined in RFC 2518.

A side benefit here is that for the first time, the client can tell the difference between live and dead properties. If the server supports DeltaV, and it returns a property in response to propname that is not returned in response to allprop, it's a live property. If a DeltaV server returns a non-RFC2518 property in response to allprop, it is very likely to be a dead property.

This redefinition for allprop is accepted outside of DeltaV as well because it reduces performance costs for servers.



WebDAV. Next Generation Collaborative Web Authoring
WebDAV. Next Generation Collaborative Web Authoring
ISBN: 130652083
EAN: N/A
Year: 2003
Pages: 146

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net