WEBDAV Working Group Y. Goland, Microsoft
INTERNET-DRAFT E. J. Whitehead, Jr., U.C. Irvine
Asad Faizi, Netscape
Stephen R. Carter, Novell
Del Jensen, Novell
<webdav-draft-06.html> January 23, 1997
Expires June, 1997
Author's draft: v0.6
This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or made obsolete by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress".
To learn the current status of any Internet-Draft, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast).
Distribution of this document is unlimited. Please send comments to the WWW Distributed Authoring and Versioning (WEBDAV) working group at <w3c-dist-auth@w3.org>, which may be joined by sending a message with subject "subscribe" to <w3c-dist-auth-request@w3.org>. Discussions of the WEBDAV working group are archived at <URL:http://www.w3.org/pub/WWW/Archives/Public/w3c-dist-auth>. The HTTP working group at <http-wg@cuckoo.hpl.hp.com> also discusses the HTTP protocol. Discussions of the HTTP working group are archived at <URL:http://www.ics.uci.edu/pub/ietf/http/>. General discussions about HTTP and the applications which use HTTP should take place on the <www-talk@w3.org> mailing list.
[Ed. Note: TBD]
The purpose of this document is to extend the HTTP 1.1 [HTTP11] protocol to support features which satisfy the Distributed Authoring and Versioning requirements set down in [INSERT REFERENCE TO UNIFIED DAV REQUIREMENTS DRAFT].
The following entries define how a term is used within this document.
Unless otherwise noted, the use of terminology in this document is consistent with the definitions of terms given in [HTTP11].
Editor: Sections references need to be entered.
This specification uses the Augmented BNF and Basic Rules as defined in Section 2 of [HTTP11].
The following design conventions have been adopted by the HTTP Distributed Authoring and Versioning (DAV) group.
[Ed. Note: Misplaced this section - should follow links. Will correct later.]
DAV methods provide diverse abilities, and no current system supports all of them. As such the client requires a mechanism to determine what features of a method a server supports. DAV provides such a mechanism controlling how methods are defined and then providing for a feature discovery mechanism. DAV also provides for a version number to allow servers to alter method semantics without breaking older clients.
Part of the feature discovery mechanism is a regulated format for method request bodies. This format allows for individual method functions to be identified and for the server to be able to describe its support for those functions. Methods that support this format are referred to as Schema Methods. All Schema Methods MUST use this format. [Author's Note: We will have to change the name.]
A Schema Method takes the following form:
Request-Body = Schema-Version CRLF *(Schema-Entry CRLF)
Schema-Version = 1*Digit.1*Digit
Schema-Entry = AttributeName ":" (Enumerated_List | Comma_List
| Open_Value)
AttributeName = Token
Enumerated_List = #Token
Comma_List = #Token
Open_Value = Text-No-CRLF
Text-No-CRLF = ; Text which doesn't contain a CRLF
The method's request body always begins with a Schema-Version that is followed by a series of Schema-Entries. These entries always consist of a name followed by a colon followed by either a predefined list of values, a comma separated list of tokens, or an open value which can contain any legal text but a CRLF.
The Schema-Version major number describes a set of schema entries and their defined values for a particular method. The major number MUST increase if the semantics of a previously defined schema entry is altered or if the Schema Method format is changed.
The Schema-Version minor number is used for feature negotiation purposes. As defined below feature negotiation allows the server to list each schema-entry and indicate if the entry is required, optional, or unsupported. A server MAY add new schema-entries to a method without changing the minor schema-version number so long as those entries are optional. If a new required schema-entry is introduced then the minor number MUST be increased.
With the Schema Method format it becomes possible for a server to provide information to a client regarding the schema-entries it supports and the manner in which it supports them. This mechanism is completely mechanistic so any Schema Method can be negotiated upon. This section describes the response format used by a server to declare the nature of its support for a Schema Method.
The format is to list each schema entry, mark it as required, optional, or unsupported, and then indicate what values it may take on. Schema entries with predefined lists of values the server lists which of those values is supported. For schema entries with a comma delaminated list of tokens, the server indicates how many tokens it will accept. No additional information is provided for schema entries that use the Text-No-CRLF production.
A client MAY include schema entries whose values are enumerated lists for which there is only a single legal value. A client MUST NOT include schema entries that have been marked as unsupported. A client MAY include a schema entry that is marked as optional. A client MUST include schema entries that are marked as required. A client MUST only use values that the server has indicated it will accept. If definition of a Schema Method does not state that a schema entry is required then the server MAY make that entry required, optional, or unsupported. The Schema-Version production MUST be included in all request bodies of all Schema Methods. The definition of a Schema Method MAY put restrictions on the interaction of schema entries, such as declaring that if one schema-entry is required then so must another.
The format for providing Schema Method negotiation information is a web collection that is contained in a response of type Text/HTML.
WC Attributes:
Type = "DAV/VersionSupport"
Name = MethodName
Schema-Version = SupportedVersions
SupportedVersions = #(VersionRange | MajorNumber | Individual)
VersionRange = Schema-Version "to" Schema-Version
MajorNumber = 1*Digit "." "*"
Individual = Schema-Version
WCDATA Entry:
Entry = AttributeName (Required_Optional | "Unsupported")
CRLF
AttributeName = Token
Required_Optional = ("Required" | "Optional") [(EnumList
| NumLegalEntries)]
EnumList = "Enumerated_List" ":" "["#Token"]"
| "AsDefined"
NumLegalEntries = "Number_Entries" ":" 1*Digit | "Infinite"
| "AsDefined"
The "AsDefined" value is used when the definition of possible values is too complex to be expressed in this simple negotiation format.
The VersionRange production allows the server to declare support for all versions within a specified range. The MajorNumber production allows the server to declare support for all versions within a major version. The Individual version production allows the server to declare support for an individual version.
Multiple web collections may be specified as necessary if support differs based on schema-version.
Two mechanisms are provided for discovering server support for a Schema Method. One is by checking for a link and the other is by using a discovery method. A server MUST support at least one of these two mechanisms.
The type of the schema method link is defined as follows:
SchemaMethodLink = "DAV.SchemaMethod." MethodName
MethodName = Token
This destination of this link is the support provided by the source for the method specified. The result will be a text/html response body containing a series of web collections describing the systems support for that Schema Method.
[NOT YET DEFINED - A Web Collection to indicate that there is variation of function based on namespace.]
[2.4.2 NOT YET DEFINED - It will provide for the submission of a schema method name and information about schema versions supported by the client. The server will then return a web collection specifying the sort of support provided for the schema method and schema versions indicated.]
In [HTTP11] link and unlink methods were introduced. The idea was to allow for two or more arbitrary resources to be associated with each other. In essence, its purpose was to extend the linking facilities available on the Web to all content types, not just HTML.
This document proposes a link facility consisting of links which are typed and unidirectional, containing an explicit source and destination.
Links are typed. These types explain the purpose and behavior of a link. It is possible that multiple links defined on the same resource may have the same type, e.g., a resource with multiple authors.
A link type usually belongs to a link schema, such as the "LockInfo" type which belongs to the "DAV" schema. By convention, links which belong to a schema are specified as: schema "." typename. Thus, the LockInfo type would be specified as "DAV.LockInfo". This creates a type namespace which is less susceptable to namespace collision than a single, flat namespace. However, use of the "." to denote hierarchy is only a convention, since types are properly considered to be opaque tokens.
The LINK method requests that a single typed unidirectional hypertext link be created on the Request-URI. This link consists of three fields, a source URI, a destination URI, and a type, which is an opaque token. The source URI is the beginning of the link, the destination URI is the endpoint of the link, and the type describes the relationship between the source and destination resources. A link may be interpreted as a binary relationship between the source and destination resources, which has the meaning, "the destination resource contains information of relation <type> to the source resource." A link may also be interpreted as an attribute-value pair, where the attribute name is the link type, and the value is pointed to by the destination of the link.
The specification of the requested link is made in the message body of the LINK request, which SHOULD be of content type "application/link". The source URI of the link will typically correspond to the Request-URI of the LINK request, but MUST not be required to do so. Either the source URI or the destination URI of the link MUST correspond to the Request-URI of the LINK request. This ensures that the Request-URI is part of the link being defined.
If the source URI is ommitted in the link specification, the source URI defaults to the Request-URI. If the destination URI is ommitted in the link specification, the destination URI defaults to the Request-URI.
Some servers may automatically allocate part of their namespace for link information of a specific type. For example, the creation date of a resource at URL <http://www.ics.uci.edu/resource.html> might be accessed from <http://www.ics.uci.edu/resource.html?create_date>. In this case, a user-agent would not want to specify the destination of a link of type "create_date," and instead would want the server to automatically fill-in the correct destination URI. If the server should specify the source or destination URI of a link, then the key word "SET" is entered for the source or destination URI in the link specification.
The request body of a LINK method request is of content type application/link, defined as:
Link = Version CRLF [ Source CRLF ] [ Destination CRLF ] Type CRLF Schema-Version = "Schema-Version" ":" 1*Digit "." 1*Digit Source = "Source" ":" ( URI | "SET" ) Destination = "Destination" ":" ( URI | "SET" ) Type = "Type" ":" token
The Schema-Version field specifies the version of the specification of the application/link media type. By definition, the version of the application/link media type specified in this document is "1.0".
Example
Source: http://www.ics.uci.edu/~ejw/reports/Q1.html Destination: http://www.ics.uci.edu/~ejw/reports/Q1_author.html Type: Author
This link states that the destination URI contains information about the author of the source URI. It may also be interpreted as the value of the author attribute of the source URI can be found in the resource pointed to by the destination URI.
The request body of a LINK method request is of content type application/linkresult, defined as:
LinkResult = Version CRLF LinkSource CRLF LinkDestination CRLF Type CRLF LinkSource = "Source" ":" URI LinkDestination = "Destination" ":" URI Type = "Type" ":" token
a) there is a syntax error in the application/link message body (e.g., missing field values, missing type value)
b) the source URI and the destination URI fields are both missing
c) Both the source URI and the destination URI are specified, and neither match the Request-URI.
d) Unsupported Type - The server does not allow links of the specified type to be created.
e) The server does not have room to store the requested link.
f) The server is unable to fulfill a request to automatically set an endpoint of the link.
The UNLINK method requests the removal of any link defined on the Request-URI which exactly matches the link specification in the request message body, which must be of content type application/unlink.
If there are any links which exactly match the link specification, a description of the removed links is returned in a response body of type application/unlinkresult.
The request body of an UNLINK method request is of content type application/unlink, defined as:
UnLink = Version CRLF Source CRLF Destination CRLF Type CRLF
Schema-Version = "Schema-Version" ":" 1*Digit "." 1*Digit LinkSource = "Source" ":" URI LinkDestination = "Destination" ":" URI Type = "Type" ":" token
The Schema-Version field specifies the version of the specification of the application/unlink media type. By definition, the Schema-Version of the application/unlink media type specified in this document is "1.0".
The response body of an UNLINK method is of content type application/unlinkresult, defined as:
UnLinkResult = Version CRLF 1*(LinkSource CRLF LinkDestination CRLF Type CRLF)
Schema-Version = "Schema-Version" ":" 1*Digit "." 1*Digit LinkSource = "Source" ":" URI LinkDestination = "Destination" ":" URI Type = "Type" ":" token
a) there is a syntax error in the application/unlink message body (e.g., missing fields, missing field values, missing type value)
b) Both the source URI and the destination URI are specified, and neither match the Request-URI.
c) No links match the specification in the request message body.
The LINKSEARCH method is used to search on the link tuple space. The search occurs in the URI namespace. Search points and scope define the area of name space to be searched. The search points are URIs from which the search should start. The scope defines the number of levels into the URI namespace the search should go down. The search syntax is in prefix notation in order to ease processing by the server.
The Request-URI is the search arbiter, and it is the job of that resource to process the request and return the results.
The media type is application/linksearch.
This syntax is adapted from [RFC1959] and [RFC1960].
LinkSearchMethod = Schema-Version CRLF [SearchPoints] CRLF SearchPattern CRLF Scope CRLF SearchPoints = "SearchPoints" ":" 1#URI SearchPattern = "SearchPattern" ":" 1*SearchOperations SearchOperations = And | Or | Not | Item And = "&" 2*SearchOperations Or = "|" 2*SearchOperations Not = "!" SearchOperations Item = Operator CompareTo MatchPattern Operator = "=" | "!=" CompareTo = "Source" | "Destination" | "Type" MatchPattern = 1*(token | " *") CRLF Scope = "Scope" ":" 1*Digit | "Sub"
The SearchPoints are URIs on which the search is to be performed. If at least one URI is not listed in SearchPoints then the search point becomes the request-URI.
The operator is equals "=" or not equals "!=". Source and Destination equality are dependent upon the type of URIs. Please refer to the definition of the referenced URI type to determine equality rules. The server MUST NOT compare URIs with which it is not familiar. Two types are equal if their tokens are octet for octet equal.
The MatchPattern allows for wildcard matching. Inserting spaces prevents the wildcard character to not be confused with characters in the token. A wildcard character matches zero or more characters.
The scope operator specifies how deep into the URI namespace the search should go. A scope of 0 means the search is only on the search point(s). A scope higher than zero means the search should proceed scope levels down the URI namespace. A scope of "sub" means the search should go all the way down to the leaves of the namespace.
Redirects may only be followed if the new location is within the defined search space.
The response body will be of type text/html and contain a web collection with type "DAV/LinkSearchResponse". That web collection will itself contain a series of web collections that have the following definition:
WC Attributes
Type = "DAV/LinkResponse"
WCDATA Entry
Entry = [OnSource] [OnDestination] Type
OnSource = ["ON"] "Source" ":" URI CRLF
OnDestination = ["ON"] "Destination" ":"
URI CRLF
Type = "Type" ":" token CRLF
Each DAV/LinkResponse indicates the source, destination, and type of a link result. The "ON" tag indicates if the source and/or destination is aware of the link's existence.
Editor: these error conditions will be merged with the response codes in the following section in a future rev. of the document.
URI Doesn't Exist (From Here on Down) (Incomplete) -
URI Access is Forbidden (From Here on Down) (Incomplete) - 403 Forbidden
URI Access is Not Allowed (From Here on Down) (Incomplete) - 401 Unauthorized
URI Not Found (From Here on Down) (Incomplete) - 404 Not Found
Arbiter does not Support Search on this URI (From Here on Down) (Incomplete) - 406 Not Acceptable
URI does not Support Search (From Here on Down) (Incomplete) - 405 Method Not Allowed
URI has been redirected out of search space (Temporarily | Permanently)(From Here on Down)(Incomplete) - 301 Moved Permanently, 302 Moved Temporarily
Unknown URI Type in Comparison (Include URI)
202 Accepted - The request has been accepted and an appropriate response generated.
203 Non-Authoritative Information - The request has been accepted but the response may be based on outdated or non-authoritative link information.
413 Request Entity Too Large - The results of the request are larger than the server is willing to return. The request should be made again using an appropriate range header. No body is returned.
GETLINKS is a convenience method that takes a type and returns a webmap containing link tuples whose source or destination equals the Request-URI and whose type matches the submitted typed.
The media type of the request body is application/GETLINKS.
GetLinksMethod = Schema-Version CRLF TaggedType CRLF TaggedType = "Type" ":" #type | "All"
A text/html media type containing a web collection of type DAV/GetLinksResponse that contains DAV/LinkResponse entries.
See the return codes for the LinkSearch method.
GetLinkVal is a convenience method that takes a type and returns a message/multipart. The first entry in the message/multipart is a Web Collection with link tuples whose source or destination equal the Request-URI and whose type matches the submitted type. The rest of the entries in the message/multipart are the result of a GET submitted on the source or destination of the link that does not equal the Request-URI.
The request body for method GETLINKVAL is of content type application/getlinkval, defined below:
GetLinkValMethod = Schema-Version CRLF TaggedType CRLF
The response body is multipart/related. The first entry is of type text/html containing a DAV/GetLinkValResponse Web Collection containing DAV/LinkResponse web collections. Following the text/html is a series of responses containing GET results.
See return codes for the LinkSearch method.
SETLINKVAL is a convenience method that combines LINK and PUT. It is used to create a link and to specify the contents of one end of the link.
The request body consists of a MIME multipart. The first entry is the request body contained below which is of type Application/SETLINKVAL. The second entry is the headers and body of the information to be PUT.
SETLINKVAL = Schema-Version CRLF LINK CRLF PutDestination CRLF ;
LINK in Section 3.3.2
PutWhere = "Put-Where" ":" "Source" | "Destination"
A web collection that contains the results from LINK and PUT.
TBD.
This section specifies only those link types which are absolutely necessary to implement the functionality described in this specification. Link types other than the ones described within are possible, but must be defined in other documents. Since there are many different possible relationships which can exist between resources, there are many different link types which can exist to describe these relationships. It is difficult, if not impossible to enumerate and describe all of these relationships, especially since the meaning of the same type may vary depending on usage context. This specification has therefore chosen not to try and enumerate all possible link types, instead providing a mechanism for discovering which link types (DAV.SupportedLinkTypes), and which sets of link types (DAV.SupportedLinkSchemas) are supported on a resource.
A server is not required to support all of the DAV Link Types. However, if a server supports a DAV Link Type, it SHOULD maintain the consistency of that relationship by ensuring the contents of the Destination URI are always up-to-date.
The DAV Link Types specified in this document form the "DAV" link schema.
All DAV schema links have a source URI which is the resource being described by the link. The destination URI alway points to a resource whose content type, and contents are described below for each DAV link type.
The history link returns information about the history of a versioned document. This information is contained within a DAG that describes the ancestors and children of various versions in the tree. The history link MUST be defined on the tree handle and SHOULD be defined on individual versions. Versions that do not have a history link MUST have a tree link defined on them.
The history link has type DAV.Versioning.History.
The destination body of the history link is a text/html file containing a series of web collections of type "DAV/History".
WC Tag Attributes:
Type = "DAV/History" Name = VersionToken
WCAT Tag Attributes and/or WCDATA Entry:
Rel = ("ParentEntry" | "ChildEntry" | "SiblingEntry")
Version = Token
HREF = Pointer to a web collection w/more information
Rel = ("Parent" | "Child" | "Sibling")
Version = Token
HREF = Pointer to a parent, child, or sibling.
The Rel/Version/HREF triples above can be used with WCAT or WCDATA. The *Entry links provide pointers to web collections with more information about the family member. The version tag provides the version of the relative being pointed to. The second Rel/Version/HREF triple provides a pointer directly to the versioned resource. All attributes defined on HCs MAY also be used here to provide information such as creation date, author, owner, etc.
A server MAY create a link of type DAV.Versioning.CheckedOut on the check out root(s), the working resource, or both. The destination resource of a DAV.Versioning.CheckedOut link is of content type application/checkoutresult, which contains the same information as the response body to the CHECKOUT method. invocation which caused the creation of this link. An optional Web Collection attribute, "Principal" may also be included, which holds information about the principal(s) who initiated the check out.
WC Attributes:
Type = "DAV/Identifier"
WCDATA Attributes:
ContactURI = "URI"
A server MAY create a link of type DAV.Versioning.DefaultPublished on the version tree handle and all members of the version tree pointed to by the handle. The destination resource of a DAV.Versioning.DefaultPublished link is a member of the version tree, and points to the version which has been designated as being appropriate for display to non-editors. The DAV.Versioning.DefaultPublished destination resource SHOULD be returned to non-DAV aware clients who perform a GET on a version tree handle.
A server MAY create a link of type DAV.Versioning.NextVersion on a versioned resource. The destination resource of a DAV.Versioning.NextVersion link is the version that immediately succeeds the source. A resource MAY have multiple DAV.Versioning.NextVersion links.
Destination resource content type: Web Collection
Synytax: TBD
The contents of the destination resource is a list of the link types which the server will definitely allow to be created on the source URI. The server may allow the creation of links with types other than those contained in the destination resource, but this is not guaranteed.
If a server supports a particular schema, then all link types in the supported schema SHOULD be returned in the destination resource of a SupportedLinkTypes link.
If a server implements the LINK method, it MUST also implement the SupportedLinkTypes link.
Destination resource content type: Web Collection
Syntax: TBD
The contents of the destination resource is a list of link schemas. If a link schema is listed, it means that the server SHOULD allow the creation of links with types belonging to that schema. The server may allow the creation of links with types which do not belong to a schema listed in the destination resource, but this is not guaranteed.
If a server implements the LINK method, it SHOULD also implement the SupportedLinkSchemas link.
[Ed. Note: This section will be removed from the spec and appended]
The mechanism for locking and unlocking a resource involves the use of a "lock token" (LockToken) which is used to reference the instantiation of the lock. Each lock token instantiates the occurrence of a lock on one resource or a specified portion of a resource (i.e., a lock on a range of a resource). The locking of multiple resources will cause the instantiation of an equal number of lock tokens.
Lock tokens represent a lock that is specific to the context of a server and therefore can not be transferred to another server. Nor is it allowable to transfer the LockToken to another "client space" even if both are instantiated on the same server. A "client space" is defined as the data space in the context of the client obtaining the lock. More than one thread can be active in a given "client space."
A mechanism is provided to ensure that a method is executed only if a lock is in place. This mechanism allows a lock header to be included in the method request. The method will be executed only if the LockToken is still valid. Multiple LockTokens may be include in the lock header. Lock headers may reference any LockToken allowing the submission of a method on a resource with a LockToken that refers to another resource.
A lock may designate "write exclusive" on a given resource. "Write exclusive" is currently the only type of lock supported. A single range for the "write exclusive" lock may be defined and overlapping ranges are never allowed. Thus a lock on the entire resource would be exclusive of any and all range locks on the same resource. Multiple range locks may be instantiated for a given resource (even among multiple "user spaces"), but overlapping ranges are not permitted. The following table describes the allowable states:
Request |
State |
Result |
| full | full | denied |
| full | partial | denied |
| full | none | granted |
| partial | full | denied |
| partial | partial | granted* |
| partial | none | granted |
* if no overlap
Once defined the definition of the lock range may not be modified. The only mechanism supported is to release the lock and instantiate a new lock with a defined range.
The size of a resource may not be changed within the defined region of a lock range unless the range includes +n (n>0) octets beyond the end of the resource (eof). By definition, locking a range beyond the eof provides the owner with the ability to add to the eof and therefore extend the resource.
If an entire resource is locked and the lock owner deletes the resource then the write lock remains. Further actions on the resource (e.g. PUT) are allowed because the LockToken is still instantiated.
Each lock may have a time out associated with it. If no time out value is associated with the lock then the lock will never time out (implementors should have some mechanism for destroying a lock at an administrative level). Otherwise the lock will expire if the designated amount of time has elapsed without a method being invoked on the resource by the lock owner. The time out value may be modified without affecting the rest of the the lock by submitting a lock request for the LockToken with no other values associated with it other than a new time out value.
[Ed. Note: Need description of LOCK method.]
The Request-URI of the LOCK method is the URI of the resource to be locked.
The lock request specifies the target of the lock, parameters of the lock, and requests that a lock be set on the resource.
The request body of a LOCK method is of content type application/lock, defined as:
LockBody = Schema-Version LockEntry CRLF TimeOut CRLF
[LockRange CRLF] [LockOwner CRLF]
LockEntry = "LockEntry" ":" LockWriteExclusive
LockWriteExclusive = "write exclusive"
TimeOut = "TimeOutSeconds" ":" TimeOutVal
TimeOutVal = 1*digit | "Infinite"
LockRange = "LockRange" ":" 1*digit "-" (1*digit | "eof++")
LockOwner = "LockOwner" ":" URI
Example:
LOCK /users/johndoe/davspec.html HTTP/1.1 Content-Type: application/lock
Schema-Version: 1.0 LockEntry: write exclusive TimeOut: 2400 LockRange: 100-eof++ LockOwner: mailto:johndoe@foo.com
The response body of a LOCK method is of content type application/LockResponse, defined below. The syntax of this content type is that of a Web Collection.
ResourceLockResponse = WC_Open LockResponse WC_Close
WC_Open = "<"WC VERSION=<">1.0<"> TYPE=" ("DAV/Lock"|"DAV/Unlock")
"<">NAME=<">" LockToken "<">>"
LockToken = token
LockResponse = *WCAT LockData *WCAT
LockData = "<WCDATA>" LockURI LockBody LockGranted "</WCDATA>"
; LockBody production from Section 6.2.2
LockURI = "ResourceLocked" ":" URI
LockGranted = "LockGranted" ":" RFC1123-date [*digit] ;*digit for milliseconds
WC_Close = "</WC>"
Example:
This is a possible response body from the lock request example in Section 6.2.2.
<WC VERSION="1.0" TYPE="DAV/Lock" NAME="LK_Xj5N75"> <WCDATA> ResourceLocked: http://www.foo.com/users/johndoe/davspec.html Schema-Version: 1.0 LockEntry: write exclusive TimeOut: 2400 LockRange: 100-eof++ LockOwner: mailto:johndoe@foo.com LockGranted: Thu, 23 Jan 1997 15:11:27 GMT </WCDATA> </WC>
Lock already owned:
Lock range overlaps:
Invalid range:
Resource not found:
Denied:
General Failure:
[Ed. Note: Need description of Unlock method]
The Request-URI of the UNLOCK method specifies the URI of the resource to be unlocked.
The request body of an UNLOCK method is of content type application/unlock, defined below:
UnlockRequest = Schema-Version UnLockToken UnLockToken = "UnLock-Token" ":" LockToken
The response body of an UNLOCK method is of content type application/UnlockResult, which is defined by the production ResourceLockResponse, defined in Section 6.2.3.
Lock not found:
Lock not owned:
Lock timed out:
Denied:
General Failure:
[Ed. Note: "LockInfo" link and associated "LockDiscovery" WC should be included in the section on DAV Link Schema links]
When a lock is taken out the system SHOULD record who owns the lock. Ownership information can be taken from the From header, from identification provided by authentication, or from the LockOwners field.
Lock Discovery is enabled via a DAV Schema link of type DAV.LockInfo. Lock Discovery is performed by using the GetLinkVal method on links of this type.
The LockInfo Link is structured as:
src = URI of the resource
dest = URI of the lock discovery WC
type = "LockInfo"
The DAV.LockInfo destination resource is of content type text/html, which uses the Web Collection syntax:
LockDiscoveryResponse = WC_Open LockResponse OtherFields WC_Close
WC_Open = "<"WC VERSION=<">1.0<"> TYPE=<">DAV/LockDiscovery<">
NAME=<">" LockToken "<">>"
LockResponse = *WCAT LockData *WCAT
LockData = "<WCDATA>" LockBody LockGranted "</WCDATA>"
LockGranted = RF1123-date [*digit]
OtherFields = (implementation specific) *
"Owner" ":" 1*octet **
WC_Close = "</WC>"
* not negotiable, safely dropped by client
** if available
This method requests the server to manipulate the mapping for the resource in the namespace such that a new location (mapping) is created for the Request-URI in the namespace, while maintaining the existing location (mapping) in the namespace. The actual implementation is left to the discretion of the server. The presence of hyperlinks within a resource creates special problem in Web resources. The fact that these hyperlinks could be either absolute or relative create yet another level of complexity.
The Request-URL will be the URL for the source resource which will be copied to the destination. In case of a versioned resource, depending on the implementation, it may be either the root of the version tree, in which case it may mean to copy the whole tree or a specific version (depending on the value of request-version), or it may be the version tree history. In case of non-versioned resource, it will refer to the resourse itself.
The message body will contain the URL of the destination of the COPY. The OVERWRITE header, as defined by this spec., defines the behavior of the server if a resource already exists as referred to by destination URL. If the value of the overwrite header is true (default), then any existing resource referenced by the destination URL will be overwritten. If the value of overwrite header is false then the copy will fail when the URL of an existing resource matches that of the destination URL. In case of non-versioned collections, COPY can be used as one of the ways to add to the collection.
The information about the destination and the switch to determine if the links need to copied as well, will be passed in the message body which should be of the content type "application/copy". Also defined in the body is a switch called "copylink". If the value of this switch is set to true, then the server should copy all the links that it deems pertinent. This spec. leaves it to the discretion of the server to determine which links are or are not appropriate in the context of copy. When links are copied the following condition MUST be met:
The defination of the content type Application/Copy is as follows:
copy = Schema-Version CRLF destination CRLF copylink CRLF [request-version CRLF] Schema-Version = 1*DIGIT "." 1*DIGIT destination = "destination" ":" URI copylink = "copylink" ":" value value = "true" | "false" request-version = "Request-Version" ":" token
The request-version token may be used to refer to a versioned resource by its version ID, in which case the Request-URI must point to the version tree handle. If the Request-URI points to the version tree handle and the request-version field is not provided, then the whole tree will be copied to the new location.
The following rules apply when a versioned resource is invloved in a copy operation:
- A versioned resource can be copied into a non-versioned space.
- A versioned resource cannot be copied into another versioned resource.
- A non-versioned resource cannot be copied into a versioned resource.
The response body returns the status code back.
The following status codes may be returned:
OK - The server has successfully copied the resource, and all the links, if applicable, to the new location in the namespace.
Copy failed due to some internal error:
The source is missing
The desitination exists (and the overwrite switch is false)
One or more links (in case copylink switch is true) failed to copy due to some internal error.
This is a discovery method to be used with COPY method. Since it is the server's discretion to choose the links that it deems appropriate to copy with the new resource location, these links have to be discoverable. COPYHEAD provides this discovery mechanism to the client. The Request-URI will be the URI for the source resource which will be copied to the destination. In case of a versioned resource, it will be the version tree handle. In case of non-versioned resource, it will refer to the resourse itself. The information about the destination (and the switch to determine if the links need to copied as well) will be passed in the message body which should be of the content type "Application/Copyhead".
The definition of application/copyhead is exactly the same as application/copy.
The response will be a Web Collection. It will contain a list of all the links that the server deems appropriate to copy with the destination URI.
Response = WC_OPEN HEAD_INFO WC_CLOSE
WC_OPEN = "<WC version="<""> 1.0 <"> Type = <"> "("DAV/COPYHEAD" | "DAV/MOVEHEAD")" <">>"
HEAD_INFO = REQUEST RESPONSE_CODE LINK_RESPONSE TIME_STAMP
WC_CLOSE = "</WC>"
REQUEST = "<WCDATA>" REQ_BODY "</WCDATA>"
REQ_BODY = actual request line and headers (without any message body)
of the COPY request for which the discovery is being made.
RESPONSE_CODE = "<WCDATA>" CODE "</WCDATA>"
CODE = exact copy of HTTP status line.
LINK_RESPONSE = Web Collection response format for each link (see section on LINK)
TIME_STAMP = "<WCDATA>" TIME "</WCDATA>"
TIME = "Time" ":" RFC 1123 date [*digit]
To copy a resource pointed to by http://foo.bar.com/foobar.html, with a link of the type "Author" and destination URI http://foo.bar.com/junk, the copyhead response will be as follows:
<WC version="1.0" Type="DAV/COPYHEAD"> <WCDATA> COPYHEAD http://foo.bar.com/foobar.html HTTP/1.1 Content-type : application/copyhead
{instance of content type application/copy goes here}
</WCDATA>
<WCDATA> Status : 200 OK </WCDATA>
<WC version="1.0" Type="DAV/LINK">
<WCDATA>
ON Source : http://foo.bar.com/foobar.html
Dest : http://foo.bar.com/junk
Type : Author
</WCDATA>
</WC>
<WCDATA> Time : some time value </WCDATA>
</WC>
This method requests the server to manipulate the resource/namespace mapping; a new location (mapping) is created for the Request-URI in the namespace, and the existing location (mapping) in the namespace is removed. The actual implementation is left to the discretion of the server.
Move can be considered as an atomic, logical operation combining a COPY followed by a DELETE on the source URI. This means MOVE inherits all the complexities of COPY operation, and add a few more of its own due to the fact that it changes the resource location in the namespace.
For instance: from the perspective of the client, a MOVE on a resource may result in a REDIRECT to the new location namespace. WEBDAV does not require a server to issue a redirect on "moved" URIs in order to be compliant, but one might argue that some sort of discovery for "server capability" be provided.
Also there is an issue of "level of intelligence" of move. One argument is that due to the special nature of HTML media types, move should automatically perform some link management on links after a MOVE. While it is impossible to manage all links pointing to a resource due to lack of control over all of the links pointing to the resource, it is conceivable that links from a resource, and links within a resource might be manageable. The opposing argument to this is that allowing a move operation to have side-effects which could modify the resource being moved - or worse yet modify resources which were not being moved - can have unexpected consequences. It is important to know the consequences of an operation before executing the operation.
WEBDAV is silent on MOVE/link interaction issues, specifying a simple MOVE with a discoverable list of links to be moved with the resource. Beyond that WEBDAV does not make any recommendation or suggestions about the actual implementation of the MOVE operation.
In case of non-versioned collections, move can be used as one of the ways to add to the collection.
This section defines the content type application/move.
Move = Schema-Version CRLF destination CRLF movelink CRLF [request-versionCRLF] Schema-Version = 1*DIGIT "." 1*DIGIT destination = "destination" ":" URL movelink = "movelink" ":" value value = "true" | "false" request-version = "Request-Version" ":" token
The request-version token may be used to refer to a versioned resource by its version ID, in which case the Request-URI must point to the version tree handle. If the Request-URI points to the version tree handle and the request-version field is not provided, then the whole tree will be moved to the new location.
The following are the rules that apply when a versioned resource is invloved in a move operation:
- A versioned resource can be moved into a non-versioned space.
- A versioned resource cannot be moved into another versioned resource.
- A non-versioned resource cannot be moved into a versioned resource.
The response body returns the status code.
The following status codes may be returned:
OK - The server has successfully moved the resource, and all the links, if applicable, to the new location in the namespace.
Move failed due to some internal error:
This is a discovery method to be used with MOVE method. Since it is the server's discretion to choose the links that it deems appropriate to move with the new resource location, these links have to be discoverable. MOVEHEAD provides this discovery mechanism to the client. The Request-URI is the URI for the resource to be moved. In case of a versioned resource, it will be the version tree handle. In case of non-versioned resource, it will refer to the resourse itself. The information about the destination (and the switch to determine if the links need to moved as well) are passed in the message body (content type "Application/Movehead").
The definition of application/movehead is exactly the same as move
The response is a Web Collection of type DAV/MOVEHEAD with BNF identical to that for DAV/COPYHEAD. It will contain a list of all the links that the server deems appropriate to move with the destination URI.
To move a resource pointed to by http://foo.bar.com/foobar.html, with a link of the type "Author" and destination URI http://foo.bar.com/junk, the movehead response will be as follows:
<WC version="1.0" Type="DAV/MOVEHEAD"> <WCDATA> MOVEHEAD http://foo.bar.com/foobar.html HTTP/1.1 Content-type: application/movehead
{instance of application/move goes here.}
</WCDATA>
<WCDATA> Status : 200 OK </WCDATA>
<WC version="1.0" Type="DAV/LINK">
<WCDATA>
ON Source : http://foo.bar.com/foobar.html
Dest : http://foo.bar.com/junk
Type : Author </WCDATA>
</WC>
<WCDATA> Time : some time value </WCDATA>
</WC>
To destroy a resource is permanently remove a resource from storage. To delete a resource is to request that the resource no longer be made available for editing. Destory differs from delete in that a versioning system may allow a deleted resource to be visible, but not editable, while a destroy causes the resource, and all knowledge about the resource to be removed from the server. A destroy is performed by the DESTROY method. The request-URI of the DESTROY method is the resource to be destroyed.
An undelete undoes the action of a delete, making a deleted resource available for editing. An undelete is performed by executing the UNDELETE method. The request-URI is the resource to be undeleted.
According to The Random House College Dictionary - Revised Edition, Collection is defined as "2. Something that is collected, as a group of objects..." In the most generic sense a URI Collection brings together a group of URIs and provides information about them. This specification will not be defining such a collection, mostly because it is a pretty idea with no where to go. At least for now. In the future systems will be available that will be able to make profitable use of a generic collection. For now this specification defines the Hierarchical Collection (HC). The HC is meant to walk, talk, and look just like a directory in a file system. URIs are added to an HC as either relative or absolute. All relative URIs in an HC are relative to the Request-URI. This restriction is in place in order to replicate normal file system behavior. Thus if the collection is copy, moved, or otherwise manipulated within the name space it will be possible to copy, move, etc. its component parts. This behavior is referred to as propagation. The idea is that a command executed on the collection can be propagated to all the relative URIs. The PropagateLevel header controls propagation behavior. This header specifies the number of levels a command should be propagated. Absolute URIs are added as links and thus commands are not propagated through them. Thus, if a collection is copied, the COPY method will be executed on all the relative URIs but not on the absolute URIs. Of course all the absolute URI entries will still be members of the collection, they simply won't have the COPY method executed on them.
Executing the MAKECOLLECTION method creates HCs. This is the same as executing a MKDIR on a file system. If a MAKECOLLECTION is executed on a Request-URI which is not itself a member of a collection then either the system will automatically create all the necessary collections or it will reject the method. Once the collection is created any URI PUT under the collection's namespace will "magically" appear inside the collection. Again, this behavior mimics that of a normal file system. Adding a relative URI directly to a collection will either be rejected or cause a NULL file to appear. Removing a URI directly from a collection will cause a link to disappear in the case of an absolute URI or will cause the file to be deleted in the case of a relative URI.
The CREATECOLLECTION method indicates to the server that the clients wishes a specified URI to act as a collection.
The contents of message/collection identify what sort of collection is being created. This document defines the Hierarchical Collection (HC). A HC only supports a hierarchical name space and is meant to replicate the behavior of a file system directory.
A HC contains URIs. URIs may be entered as relative or absolute. Relative URIs must be relative to the request-URI. A relative URI is a propagate entry. If a PropagateLevel header is included with a method executed on a HC then the method will be propagated through all relative URIs. Absolute URI entries do not propagate.
MessageCollection = Version CRLF CollectionType CRLF
CollectionType = "Collection Type" ":" ("HC"
| Text)
CREATECOLLECTIONERROR = WC_OPEN Type WC_CLOSE
ContentError = "DAV/Error/CreateCollection"
Type = "Do Not Support Type" ":" ("HC" |
Text)
Editor: this section needs to incorporate the correct text from Yaron.
This content type is used to add a link to a collection. In the case of an HC most systems will not accept a relative URI. Rather, to add a new entry to an HC, the resource should be created using a PUT or similar method. If the server does accept a relative URI for an HC then the result SHOULD be the creation of an empty resource.
AddResource = Version CRLF URIType CRLF URIEntry CRLF
URIType = "Type" ":" ("Relative" | "Absolute")
URIEntry = "URI" ":" (relativeURI | absoluteURI)
URIType indicates the type of URI while URIEntry indicates the actual URI. URIType is included for negotiation purposes. If the URI is relative then it is relative to the request-URI. The productions relativeURI and absoluteURI are defined in section 3.2.1 of rfc2068.
The content type of the response body is text/HTML and contains a Web collection.
This content type is used to remove a URI from a collection. In the case of an HC most systems will not accept a relative URI. Rather, to delete an HC entry, the resource should be DELETEd or DESTROYed. If the server does accept a relative URI for an HC then the result SHOULD be the deletion of the resource.
RemoveResource = AddResource
The content type of the response body is text/HTML and contains a Web collection.
The PropagateLevel header controls how many levels a method will be propagated down a collection. Zero means the method should only be executed on the collection. Infinity means the method should be propagated as far down as possible. A loop is impossible with HCs because its name space is a tree and absolute URIs do not propagate. Other collection types will have to define their own mechanisms to detect and prevent loops.
PropagateLevel = "PropagateLevel" ":" (1*Digit | "Infinity")
The following web collection can be included in any web collection based body.
WC Attributes
Type = "DAV/Error/Prop/FailedAt"
WCDATA Entry
Entry = "Propagation Mechanism Failed at" ":"
*(Relative | Absolute_URI CRLF)
Relative = "Base" ":" Absolute_URI "Relative"
":" *Relative_URI CRLF
This specification provides interface definitions which clients may use to perform the common versioning operations check in, check out, version history retrieval, and merge. A fundamental assumption of this specification is that the semantics of versioning operations are defined by the server, and may vary from server to server, depending on the versioning engine employed. As a consequence, this specification provides a common interface for accessing the functionality of many different versioning engines.
Since versioning functionality may vary from server to server, or even in different namespaces on the same server, a discovery mechanism is provided for clients to determine precisely what effect a CHECKOUT or a CHECKIN method invocation will have on the state of the server. A client may query the server for its CHECKIN and CHECKOUT semantics by retrieving the destination resource of the DAV.Discovery.CHECKOUT and DAV.Discovery.CHECKIN links. It is expected that a client will query the value of the DAV.Discovery.CHECKOUT link before performing a check out, and the DAV.Discovery.CHECKIN link before performing a check in, so it knows exactly what will occur when it issues the CHECKOUT or CHECKIN request.
Similarly, the who and when of setting a version identifier varies significantly:
A version tree is a directed acyclic graph of versioned resources. Arcs in the version graph indicate "is-version-of" (or "is-successor-of") relationships. Each versioned resource is a first-class resource, addressable by a URI. A version tree MUST have a handle resource, known as the version tree handle, which is used to refer to the version tree as a whole. The contents of the handle resource MUST be a single URI (a pointer), which is used by the versioning engine to identify the version tree as a whole. The version handle resource MAY point to either the root object of the version tree, or the history resource for the version tree.
The version tree handle MUST have server generated links of type DAV.Versioning.DefaultPublished, DAV.Discovery.CHECKIN, and DAV.Discovery.CHECKOUT, and MAY have a server generated link of type History. Each versioned resource MAY have server generated links of the following types: DAV.Versioning.History, DAV.Versioning.DefaultPublished, DAV.Versioning.NextVersion, DAV.Discovery.CHECKOUT, DAV.Discovery.CHECKIN.
Versioning is an orthogonal issue to content negotiation. Each particular variant of a resource MAY be independently versioned, and MAY have its own version tree.
TBD: A Figure showing a sample version tree (using text characters)
A CHECKOUT is a declaration by a client that it might edit a versioned resource. The CHECKOUT method is intended to map to the notion of check out supported by the server's versioning engine. The Request-URI of the check out method is a version tree handle, which identifies the version tree on which the CHECKOUT will be performed.
A server MAY create a working resource as the result of a check out. If the server creates a working resource, it MUST return the URI of this resource in the response body.
All of the activity which occurs during CHECKOUT method invocation MUST be performed atomically.
Editor: this section will be subsumed by a more general method discovery mechanism.
The request body of the CHECKOUT method is of content type application/checkout, defined as:
Checkout = Schema-Version CRLF [Derived-From CRLF] [Request-Version CRLF]
[Request-Lock CRLF] [Request-Intent CRLF]
[Request-Working-Loc CRLF] [Request-Visibility CRLF]
Schema-Version = "Schema-Version" ":" 1*DIGIT "." 1*DIGIT
Derived-From = "Derived-From" ":" #token
Request-Version = "Request-Version" ":" token
Request-Lock = "Request-Lock" ":" "Exclusive" "Write"
Request-Intent = "Request-Intent" ":" ("true" | "false")
Request-Working-Loc = "Request-Working-Loc" ":" ("Client" | "Server")
Request-Visibility = "Request-Visibility" ":" Visible-When [Visible-Where]
Visible-When = ("Always" | "If_Locked" | "Never")
Visible-Where = ("On_CheckOut_Root" | "On_Working" | "On_Both")
The Schema-Version is the version number of the syntax specification of the application/checkout content type.
Derived-From specifies the version identifier of the check-out root(s) from which the working resource (if it exists) is derived. If more than one version identifier is specified in the Derived-From value, the working resource MAY be the result of a merge of the specified versions, and the exact semantics of this merge operation will vary across versioning engines.
Request-Version specifies a client's request to set the version identifier of the working resource. The server MAY set the version identifier of the working resource to this value. If this field is omitted from the request message body, the server MAY perform a check out from a default check out root (often the latest version).
Request-Lock is used by the client to request a lock when a server supports optional locking on check out.
Request-Intent is used by the client to request the server to establish an intent to edit on check out. An intent to edit MAY result in the association of authentication or user information with either the check out root, or the working resource.
Request-Working-Loc is used by the client to request where the working resource is located. If the client specifies "Client," then the server SHOULD not create a working resource on the server. If the server does not create a working resource on the server, the client SHOULD retrieve its working resource from the check out root after successful completion of the CHECKOUT. If the client specified "Server," then the server SHOULD create a working resource on the server.
Request-Visibility is used by the client to request whether to create a DAV.Versioning.CheckedOut link, and the resource which will store the link. Visible-When describes whether the DAV.Versioning.CheckedOut link SHOULD always be created ("Always"), SHOULD only be created if the check out performs a lock ("If_Locked"), or SHOULD never be created ("Never"). Visible-Where describes where the link SHOULD be stored: on the check out root ("On_CheckOut_Root"), on the working resource ("On_Working"), or on both the check out root and the working resource.
The response body of a CHECKOUT method invocation is of content type application/checkoutresult, defined as:
CheckoutResult = WC-Open CheckoutResultData WC-Close
WC-Open = "<WC VERSION =<">1.0<"> TYPE =<">DAV/CheckoutResult<">>"
CheckoutResultData = *WCAT WCCheckoutData WCAT
WCAT = {arbitrary, server-defined Web Collection attributes}
WCCheckoutData = "<WCDATA>" DerivedTree DerivedRoot [WorkURI]
[WorkVersion] [Visibility] "</WCDATA>"
DerivedTree = "Derived-Tree" ":" URI CRLF
DerivedRoot = "Derived-Root" ":" #URI CRLF
WorkURI = "Working-URI" ":" URI CRLF
WorkVersion = "Working-Version" ":" token CRLF
Visibility = "Visibility" ":" ( Visibility-Where | "Never" ) CRLF
WC-Close = "</WC>"
Derived-Tree is the location of the version tree handle on which the check out was performed.
Derived-Root is the location of the (possibly many) versioned resources on which the check out operation was performed.
WorkURI is the location of the working resource generated by the server on check out, if it exists.
WorkVersion is the version identifier of the working resource, if it was set on check out.
Visibility is the location where the client can retrieve the DAV.Versioning.CheckedOut link.
An error condition occurs if the following conditions hold:
If a client requests a version identifier on check out, but the server:
a) cannot set a version identifier
b) refuses to set a version identifier
If a client requests a lock, but the server doesn't support locking.
If the client requests an intent to edit, but the server doesn't support intent to edit.
If the client doesn't specify a Derived-From version, and the server has no default value.
Syntax error in the request body. If a client requests a feature the server doesn't support then it has committed a syntax error because the discovery told the client what the server supports.
A CHECKIN is a declaration by a client that it wishes to place a resource under version control. The CHECKIN method is intended to map to the notion of check in supported by the versioning engine. The Request-URI for a CHECKIN method invocation is the version tree handle of the version tree which is being operated on.
A check in SHOULD clear any server state which is set as a result of a check out. For example, if a server locks a resource on check out, it should remove the lock upon check in.
To place a resource under version control for the first time, a check in is performed on the resource. In this case, the Request-URI is the desired location of the version tree handle, and the Working-URI or the check in body gives the contents of the resource to be placed under version control.
All of the activity which occurs during CHECKIN method invocation MUST be performed atomically.
Editor: this section will be subsumed by a more general purpose discovery mechanism
The request body of a CHECKIN method invocation MUST be in one of two forms:
If the request-body is of content type multipart/related, the checkin operation is defined to be a PUT of the checkin entity body (into a server-dependent temporary resource), followed by a CHECKIN.
The definition of content type application/checkin is:
CheckIn = Schema-Version CRLF [Derived-From CRLF]
[Working-Resource CRLF] [Request-Version CRLF]
[Check-In-Location CRLF]
Schema-Version = "Schema-Version" ":" 1*DIGIT "." 1*DIGIT
Derived-From = "Derived-From" ":" #token
Request-Version = "Request-Version" ":" token
Working-Resource = "Working-Resource" ":" ( "[" URI "]" ) |
("VersionID" ":" token) | "BODY"
The Schema-Version is the version number of the syntax specification of the application/checkout content type.
Derived-From specifies the version identifier of the check-out root(s) from which the working resource (if it exists) is derived. If more than one version identifier is specified in the Derived-From value, the checked-in resource MAY be entered as the successor of the Derived-From resources.
Request-Version specifies a client's request to set the version identifier of the check in resource. The server MAY set the version identifier of the check in resource to this value. If this field is omitted from the request message body, the server MUST set the version identifier if it has not previously been set.
Working-Resource specifies a URI or a version identifier of the working resource which is to be checked-in. If the value is "BODY," the working resource is contained in the check in body.
Open issues: 1 - If a version has multiple parents the client wants to know where the version links will go. If the system supports multiple inheritance then that needs to be stated. If the system only supports single inheritance then the client needs to know, before hand, which version the new version will be linked to. 2 - The syntax allows a client to specify different derived-from resources on Check In then were listed on Check Out. Somewhere there is a versioning system that doesn't allow this. The client needs to know this fact before performing the check out.
There is no response body defined for the CHECKIN method.
If the Derived-From token(s) do not exist,
If the working URI is not located on this server, or the server is not authorized to retrieve the working URI.
If the PUT of the checkin entity body fails.
Syntax error in the request body.
The request-URI of the DIFF method is an arbiter. The arbiter will compare the entries and return the differences between them.
The request-URI of the MERGE method is also an arbiter. The arbiter will combine the entries and return the result.
The Application/Diff content-type works with the DIFF method. The Application/Merge content-type works with the Merge method.
Application/Diff = Body
Application/Merge = Body
Body = 1#("URI" ":" URI | "Entity" ":"
entity-body)
The SERVERMERGE method requests that the server merge a number of entities on behalf of the client. The request-URI is a server side arbiter who performs the merge on behalf of the client.
The request body may take on one of two possible formats. One format is application/servermerge, which is defined below. The second format is message/multipart related which will contain an entry of type application/servermerge as well as entities for the server to merge.
Type = application/servermerge
Merge = Schema-Version CRLF MergeType CRLF [MergeEntities CRLF]
ReturnType CRLF [ReturnURI CRLF]
MergeType = "Merge Types" ":" ("URIs" | "Bodies" | "URIs" "Bodies")
MergeEntities = "Merge Entries" ":" #URI
ReturnType = "Return Result" ":" ("URI" | "Body")
ReturnURI = "Return Location" ":" URI
MergeType specifies what mechanisms are being used to refer to bodies to be merged. URIs means that a MergeEntities has been included while Bodies indicates that one or more message/multipart related have been included. ReturnType specifies how the results are to be returned, either as part of the response or recorded in a URI. ReturnURI specifies the URI for the result to be recorded in if the user selects that return mechanism. A server MAY support any combination of values for MergeType and ReturnType. It MUST provide for discovery of supported values.
Only support # bodies to be merged
Can not resolve URI
Can not store in URI
Can not merge included types
Merge Failed
Merge Succeeded
[Will fold in from above.]
Command comments are entity headers.
Command_Comment = "Comment" ":" CommentVal
CommentVal = URI | comment
This is the standard comment facility used by versioning systems. Servers that do not understand the header or do not wish to make use of the information are free to ignore the information. No specification is made regarding how this information is to be retrieved. It is likely, however, that most systems will make the command comments available through their history attribute.
Editor: this method should be viewed as proposed functionality.
This method request the server to freeze the version tree in the current state, and copy the default published version outside of versioning space so that it is accessible as an unversioned resource to the client. After the version tree is frozen, the clients will not be able to perform any operation except CHECKIN at which time the tree will be taken out of the frozen state and put back into the version space. The Request-URI is the URI of the version tree handle.
None.
The response will only consist of the status code as returned by the server.
The error codes could any of the following:
OK - the server successfully froze the version tree and copied the Default
Published Version into non-version space.
FREEZE failed because the server could not freeze the tree.
FREEZE failed because the server could not copy the default published version
to unversioned space
FREEZE failed because the server could not determine the Default Published
Version
The source (tree) is missing
The max length header requests that the server not return any results greater than specified in the header. The header also specifies if partial results are preferred to no results in the case when the result entity is greater than allowed by the header.
MaxLengthHeader = "MaxLength" ":" Size Partial CRLF
Size = "Size" ":" Bytes-Unit 1*Digit
Partial = "Partial" ":" ("Acceptable" | "Not Acceptable")
The If-Lock header makes any request to which it has been appended conditional on the lock(s) referred to by the included token(s) still being active. This header can not be dropped.
IfLockHeader = "If-Lock" ":" #LockToken CRLF
Command-Comments (short form CCMD) is a request-header which is used to transmit comment information on any HTTP request method to the server. The server MAY provide persistent storage for the comments. The server MAY log the comments. The server MAY ignore the comments.
The definition of the syntax of the Command-Comments header is as follows:
CommandComments = ("CCMD" | "Command-Comments") ":" LangTaggedString
LangTaggedString = Lang UTF-8 ; See RFC 2044 for UTF-8 definition
Lang = "(" LangTag ")"
LangTag = 1*8ALPHA *("-"1*8ALPHA)
Overwrite is a request-header which specifies whether the destination of the method should or should not be overwritten.
Overwrite = "Overwrite" ":" ("Yes" | "No")
If the value of Overwrite is "Yes," a destination resource will be replaced if it exists. If the value of Overwrite is "No," the server will not replace the destination resource if it exists.
This header may be applied to the PUT method, and thus modifies the definition of PUT given in Section 9.6 of [HTTP/1.1].
Editor: This is a proposed feature.
The LinkSearch method can be expensive, especially when a number of attributes must be retrieved over time.
A more economical mechanism is to append a search string to URL using "?". However, the URL could be confused with any of a number of search syntax's. The solution proposed by this document is to create a new header called LinkSearch.
LinkSearch = "LinkSearch" ":" HTTP_url ; See section 3.2.2 of [HTTP11]
If the HTTP URL does not end in a "/" then a "?" may be appended to it and the attribute search syntax defined below may be used to search for attributes on that particular resource. If the URL does end with a "/" then any resource whose name is a child of the specified HTTP URL may be searched on directly.
To perform a search a string matching the following syntax should be used.
LinkSearchSuffix = "?" Attribute
Attribute = token
So, if the LinkSearch value is http://foo/bar then a search on a link type of author would be performed using http://foo/bar?author. If the returned value is http://foo/bar/ then the author search may be performed on http://foo/bar/?author and any of its children, such as http://foo/bar/doublebar?author.
By returning the LinkSearch header the server is agreeing to manipulate the search URL as it would the URL of the resource it resolves to. Thus it becomes the responsibility of the server to resolve the search URL whenever it is included in a command.
If it is impossible to resolve the search request to a single result then a 416 Not Unique error should be returned. This error specifies that the URI was not resolvable to a unique resource.
If the search URI does not resolve to any attribute then any request containing that URI should return a 404 Not Found error.
Editor: this is a proposed feature.
In some cases a server may have an arbiter which handles all searches on resources. To allow for the use of the arbiter but still gain the advantages of URL based searching the LinkPrefix is introduced.
LinkPrefix = "LinkPrefix" ":" HTTP_url
To retrieve a particular attribute the following syntax should be used:
LinkPrefixSuffix = "?" URL LinkSearchSuffix
Thus the returned URL has the URL to be searched on appended to it followed by the actual search syntax as previously specified. This allows for quick retrieval of attribute values but with the benefit of processing requests at a single resource.
The URI returned by LinkPrefix has the same use semantics as the URI returned by LinkSearch.
[Ed. Note: preliminary and incomplete]
Introduce the concept of Distributed Authoring compliance, Versioning compliance, and totally optional features. Use the list from presentation.
[Ed. Note: preliminary and incomplete]
Roy Fielding, Richard Taylor, Larry Masinter, Henry Sanders, Judith Slein, Dan Connolly, David Durand, Henrik Nielsen, Paul Leach. Kenji Ota, Kenji Takahashi. Jim Cunningham. Others, TBD.
[Ed. Note: preliminary and incomplete]
[HTTP11] R. T. Fielding, J. Gettys, J. C. Mogul, H. F. Nielsen, and T. Berners-Lee. "Hypertext Transfer Protocol -- HTTP/1.1" Internet-Draft draft-ietf-http-v11-spec-07.txt, expires February 12, 1997.
[ORANGE] DoD 5200.28-STD, "Department of Defense Trusted Computer System Evaluation Criteria", December, 1985.
[RFC1521] N. Borenstein, N. Freed. "MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies." RFC 1521, Bellcore, Innsoft, September, 1993.
[URL] T. Berners-Lee, L. Masinter, M. McCahill. "Uniform Resource Locators (URL)." RFC 1738, CERN, Xerox PARC, University of Minnesota, December, 1994.
[RFC1959]
[RFC1960]
[WEBC] - References to web collections.