9.3 Create a Folder

Now that Alice is viewing her personal collection, she chooses New... from the File menu, and then selects Folder. Microsoft Explorer always creates new folders with the name New Folder, and then allows users to rename the folder. This behavior is exactly how Explorer works with a local folder.

Web Folders uses MKCOL to create a new WebDAV collection called New Folder and uses PROPFIND to check the new folder's properties. Then Web Folders prompts the user for a real name and uses MOVE to rename the collection (see Figure 9-3).

Figure 9-3. Summary of creating new collection.

Although Web Folders required three requests to create a new folder, a client with a greater concern for performance could arrange to have a different UI that only required one request (MKCOL).

The MKCOL and MOVE request and response details are interesting, as is the response to the PROPFIND. These interactions are covered in the next few sections.

9.3.1 MKCOL

Web Folders uses MKCOL to create New Folder (see Listing 9-8). The space in the name is escaped so that it is a legal URL (Section 3.1.3).

Listing 9-8 MKCOL request and response.

 MKCOL /users/alice/New%20Folder HTTP/1.1 Accept-Language: en-us Translate: f User-Agent: Microsoft Data Access Internet Publishing    Provider DAV 1.1 Host: www.example.com Content-Length: 0 Connection: Keep-Alive Cookie: XythosSessionID=2600-2141502937; XythosUser=alice@1  HTTP/1.0 201 Created Content-Length: 0 Cache-Control: no-cache Pragma: no-cache Date: Sun, 18 Nov 2001 22:25:38 GMT Server: Tomcat Web Server/3.3 Final ( JSP 1.1; Servlet 2.2 )  

The client continues to send the Accept-Language, Translate, User-Agent, Host, Content-Length, Connection, and Cookie headers with each request. The client continues to send every one of these headers in every request, and that's boring, so from here on I'll omit them in order to draw attention to what matters or is new. Most of these headers are not useful or required in an MKCOL request. Only the Host header is required with the MKCOL request.

9.3.2 New Folder Properties

Web Folders now sends a PROPFIND request because it needs some property values (probably the creation date) to know how to correctly display the new folder in Explorer. This request also verifies that the new folder exists, has the expected name, and is not locked but may be locked. Since the PROPFIND request is no different from that shown in Listing 9-3, I'll show only the response body to show the properties of a newly created collection (see Listing 9-9).

Listing 9-9 PROPFIND response fragment for new collection.

 <D:response>    <D:href>http://www.example.com/users/alice/New%20Folder/</D:href>    <D:propstat>       <D:prop>          <D:resourcetype><D:collection/></D:resourcetype>          <D:displayname><![CDATA[New Folder]]></D:displayname>          <D:creationdate b:dt="dateTime.tz">              2001-11-18T22:25:38Z</D:creationdate>          <D:lockdiscovery></D:lockdiscovery>          <D:supportedlock>[omitted]</D:supportedlock>          <D:getlastmodified b:dt="dateTime.rfc1123">              Sun, 18 Nov 2001 22:25:38 GMT</D:getlastmodified>       </D:prop>       <D:status>HTTP/1.1 200 OK</D:status>    </D:propstat> </D:response> 

The response shows that the new folder was created and is not locked (lockdiscovery is empty) but may be locked (the value of the supportedlock property was omitted from the example because it's the same for every resource). It shows that the name of the collection is New Folder. That means that the Xythos server chose to undo the HTTP character escaping and store the resource name without escape sequences.

String Escaping

Clients must be prepared to deal with servers that unescape escaped strings and servers that store escaped strings as is, because RFC2518 doesn't require either behavior. The RFC also does not specify what the displayname property value should be, but most servers set the value of that property to the last part of the path to the resource and do not allow that value to be modified.

9.3.3 Collection Name Change

After creating the new collection, Web Folders allows the user to change the name of the new collection from New Folder to something else. The name change causes Web Folders to send another PROPFIND depth-0 request to the parent of the new folder (not to the new folder) and then a MOVE method on the new folder itself.

It's not clear what purpose this new PROPFIND request serves, because it's a depth-0 request. It doesn't retrieve the contents of the parent collection, so it can't be used to see if the new collection still exists or if another collection already exists with the new name chosen by the user. It may be used to determine if the parent collection is locked or to see if the parent collection supports some nonstandard WebDAV feature. We won't show this request or response because it's so similar to the last PROPFIND example, but instead we skip straight to the MOVE request and response that actually perform the rename (see Listing 9-10).

Listing 9-10 MOVE method to rename a collection.

 MOVE /users/alice/New%20Folder HTTP/1.1 Destination: http://www.example.com/users/alice/work Content-Length: 0 Overwrite: F [typical headers omitted]  HTTP/1.0 201 Created Content-Length: 0 Cache-Control: no-cache Pragma: no-cache Date: Sun, 18 Nov 2001 22:26:40 GMT Server: Tomcat Web Server/3.3 Final ( JSP 1.1; Servlet 2.2 )  

The request simply names the new location. The response is a 201 Created message, which makes it clear that the client did not overwrite a collection that already existed with the name work but instead created a new resource at that URL. An existing collection would not have been overwritten in any case, because the client request includes the directive not to overwrite existing resources in the Overwrite header.