Next message: Jim Whitehead: "Teleconf minutes, Feb. 28, 2000"
From: David.Goodenough@dga.co.uk
To: Delta-V.list@dga.co.uk
Message-ID: <80256893.00381FBF.00@mail.dga.co.uk>
Date: Mon, 28 Feb 2000 11:46:15 +0000
Subject: Collection Fetch/Save proposal
Below is my first cut at the extensions that I mentioned in the Unit of
Work thread last week. I suspect that my XML terminology is wanting
precision, so please feel free both to question what my intentions might be
where they are unclear, and to correct any errors. I have only included
those XML elements as definitions where I felt I had some chance of
defining them correctly, I have no real idea how the differing property
lists which need to be represented in the <!ELEMENT> definitions for
differing types of collection or resource for the DAV:multipart element, or
the DAV:resourse element.
I chose the outer element name multipart largely because of the parallel
with multistatus. It and the other names I think are unique, but there is
nothing sacred about them.
Abstract:
This proposal adds function to the GET and PUT methods to allow the
fetching and saving of entire collections with a single operation.
Changes to existing Draft document:
3.11 Collection fetch and save properties
3.11.1 DAV:multipart
DAV:collection-resources is used as the description of an entire collection
and all the parts that it contains. It is used in the GET and PUT methods
when the target is a collection. This element contains all the properties
which are relevant to this kind of collection, and a DAV:resource-set
element (see 3.11.2).
3.11.2 DAV:resource-set
DAV:resource-set is used to contain all the parts of a collection within a
DAV:multipart. It consists of a sequence of DAV:resource elements (see
3.11.3).
<!ELEMENT resource-set (resource*)>
3.11.3 DAV:resource
DAV:resource contains all the properties of a resource contained within a
collection when represented as part of a resource-set, and the body of the
resource (see 3.11.4).
DAV:resource is used within a DAV:resource-set to describe the whole of a
resource and all its properties. The DAV:resource header includes the URL
name of the individual resource.
3.11.4 DAV:body
DAV:body contains the actual contents of the resource identified by its
containing DAV:resource element.
4.1 GET
...add new paragraph at the end of the existing text...
When the request-URL of a GET identifies a collection, a DAV:multipart
response will be generated which includes all the attributes of the
collection and a resource-set attribute which is a sequence of all the
parts which make up the collection each of which is describes by all of its
properties plus an additional property, the body - attribute name DAV:body,
of the part.
The server should only return this multipart response if all the resources
and their properties can be fetched. If any of the information can not be
retrieved then a multistatus response should be generated instead
indicating those elements with which there is a problem.
4.2 PUT
...add new paragraph at the end of the existing text...
When the request-URL of a PUT identifies a collection, a DAV:multipart
element is used to update the whole of the collection. Its format is the
same as that returned by a GET directed at the same collection. All the
information fetched by the GET method MUST be returned, except where it is
explicitly updated by the client - this enables the server to correlate the
request with its version of the collection and individual resources, and to
make sure that what it being updated is correctly identified. Similarly
for each part all properties supplied by the GET method must be returned
(they must all be present, but their order is of no significance) as
supplied, except where there contents is specifically to be updated. It is
up to the server to discard those attributes which are read-only, but it
should use them to correlate the incoming data to the existing data. Thus
a part may be renamed by retaining its DAV:versioned-resource-id (if the
part is not versioned when it can have no history and so the old part is
simply deleted and the new one created). New parts will not have existing
properties, and so the client may fill in those that it would specify to
create a resource, and the server will then treat this as create request.
As this method results in the wholesale replacement of the current content
if any parts are present in the update that were not present in the
collection the server shall (if it is allowed to) add the new part to the
collection, and if the part was present but is not in the update, then the
server shall delete the part from the collection. It is of course open to
the server - and this should be the default operation - to discard updates
that do not change the parts.
The server MUST validate the request before it starts to action it. Thus
for instance checks to ensure that this client is authorised to delete
items from a collection MUST be made before the update starts. While there
may be update time exceptions, the server should adopt an order of
processing such requests which limits these to only those exceptions which
can genuinely not be detected before the update starts. It is also
desirable that the server should use transaction atomicity and journaling
techniques to ensure that the collection is left either updated or as it
was before the update starts.
The response to a PUT specifying a collection as a target should either be
a success code, or a multistatus response indicating all the problems that
were encountered.
The end..
Well I suspect this will need some work to get it right, comments please.
Regards
David