WebDAV Project

Marc Eaddy

Shao Rong

Jonathan Shapiro

December 16, 1997

Fall 1997

COMS E6113x

Topics in Database Systems:

WWW-based Collaborative Work

Professor Gail Kaiser

Table of Contents

Introduction *

Abstract *

Motivation *

WebDAV *

Description of Our Project *

Requirements Analysis *

Modularity *

Platform Neutrality *

Flexibility *

Extensibility *

Functional Specification *

Protocol Layer *

Executive Layer *

Subsystem Registry *

Functional Subsystems *

Namespace Manager *

Property Manager *

Lock Manager *

Conclusion *

Future Work *

References *

Appendix A: Installation Instructions *

System Requirements *

Step 1: Installing the Java Web Server *

Step 2: Verifying the Java Web Server *

Step 3: Installing the WebDAV Servlet *

Step 4: Configuring the Java Web Server to use the WebDAV Servlet *

Step 5: Verifying the WebDAV Servlet Installation *

Step 6: Installing the WebDAV Client *

Troubleshooting Java Web Server *

Appendix B: WebDAV Client Usage Instructions *

GET *

PUT *

COPY *

MOVE *

DELETE *

PROPPATCH *

PROPFIND *

LOCK *

UNLOCK *

Appendix C: Source Code and Documentation *

Package webdav.client *

Package webdav.common *

Package webdav.executive *

Package webdav.nsman *

Package webdav.lockman *

Package webdav.propman *

Appendix D: Class Hierarchy and System Diagrams *

Introduction

This document will include sections describing the motivation for this project, the project description, a requirements analysis, and a functional specification. We will conclude with an analysis of our architecture prototype, an analysis of our extended HTTP server, and describe possible future directions for this project.

Abstract

We have created a working implementation of a server and client that supports a subset of the extensions to HTTP 1.1 for Distributed Authoring and Versioning on the World Wide Web (WebDAV) [1]. The WebDAV extensions, proposed in draft form by the WebDAV working group of the Internet Engineering Task Force (IETF), are designed to provide support for traditional document management aspects of collaborative work on the World Wide Web with features like resource properties, namespace manipulation, resource locking, and version control.

Our project was to design a prototype architectural framework for implementing the WebDAV specification as an extension of an existing HTTP server. We then used that framework to implement a subset of the WebDAV specification to support resource properties, namespace manipulation, and exclusive write locking.

Motivation

While the HTTP protocol forms a highly scaleable infrastructure for browsing and searching a distributed set of heterogeneous information repositories, it provides extremely limited support for the authoring and management of that information. In absence of protocol features to support traditional document management tasks, much of the creation of Web content takes place outside of the Web itself. Reasonable support for collaborative Web development can often be realized in a local area network (LAN) environment, either by deploying existing document management systems or simply by making use of built-in operating system support for LAN-based file sharing. In either case, however, the model is one in which the Web serves only as the publication medium, not as the authoring environment and does not directly support truly distributed collaboration in authoring. Thus collaboration is limited to those who can share the resources of the local area network or those who are willing to take on the often complex process of managing remote content repositories.

Solutions to this problem exist, ranging from automated publishing based on HTTP PUT, FTP or other mechanisms, to nonstandard locking and versioning extensions [2, 3, 4]. However, interoperable, standards-based support is desirable if the World Wide Web is to live up to its original conception as a shared space for collaboration, rather than simply a vast repository for passive browsing.

WebDAV

The WebDAV working group of the Internet Engineering Task Force is currently developing a specification for extensions to the HTTP 1.1 protocol in the form of new methods, headers, and request and response formats to support a range of new functionality including:

Resource Properties: The ability to associate arbitrary metadata with a Web resource.

Typed Out-of-line Resource Linking: A special type of resource property, typed links is a way of associating resources in terms of semantically meaningful relationships. Out-of-line links enable the associations to exist external to the resources themselves, enabling features such as annotation and individual views.

Shared and Exclusive Resource Locking: The ability to serialize updates to the contents of a shared resource.

Retrieval of Unprocessed Source: Some Web content accessible through a URL is actually the output of a process. A page generated by a CGI script is one example. Usually the resource that describes that content, the script itself, remains inaccessible through the server’s namespace. WebDAV specifies extensions that allow for reading and updating this type of resource.

Partial Updating: The ability to update a specified byte range within a resource, minimizing the bandwidth required since the data transmitted is proportional to the size of the change.

Namespace Manipulation: The ability to copy, delete and move resources on the Web server.

Collections: The ability to create composite structures for aggregating Web resources.

Versioning: Standard version control features like check-in, check-out, and the ability to retrieve previous versions of a resource.

Security: Access control features to restrict the ability to alter resources based on identity or group membership.

Content Variants and Internationalization: The ability to associate different variations of the same information, such as multiple language versions of a document or versions of an image at different resolutions.

As of this writing, the most recent version of the WebDAV specification dated November 19, 1997, although still in draft form, already contains extensions for supporting many of these functional categories. Support for versioning, security, content variants and internationalization have not yet been including in the specification.

Note, since a WebDAV server extends a normal HTTP 1.1 web server, traditional web browsers have access to the server content using standard HTTP 1.1 requests.

Description of Our Project

The goal of this project was to design a system architecture that supported the syntax and semantics of the WebDAV protocol, and which can be implemented using existing database, file system, version control, and other systems as appropriate. Using this architecture, we extended an existing Java Web Server [7] to support resource attributes, namespace manipulation, and exclusive write locking. By implementing this subset of the WebDAV extensions, our WebDAV server satisfies "Level 2"-compliance mandated by the WebDAV specification. We also created a simple WebDAV client that supports this same subset of extensions to demonstrate the functionality of our WebDAV server.

Requirements Analysis

The functional requirements of WebDAV have already been addressed by the WebDAV working group in a requirements document [5] and a set of use-case scenarios [6]. While we will not reproduce their content here, we have studied these documents closely throughout the design, coding and testing phases of our project to ensure that our implementation was compliant with both the syntax and semantics of the proposed WebDAV extensions.

In addition to addressing the requirements set forth by the working group, for our implementation we targeted a set of requirements designed to produce an extensible and robust software product. Our requirements were as follows:

Modularity

Design proceeded from the assumption that the WebDAV-compliant server should be capable of supporting a wide variety of content repositories (local file system, legacy data), version control systems (RCS, CVCS), and database technologies. The server must have a high-level architecture implemented in terms of well-defined interfaces to subsystems that are interchangeable and extensible. These interfaces will hide the details of subsystem implementation from the executive levels of the server as well as from the other subsystems. Many subsystems may, in fact, be implemented as thin layers on top of existing technologies or even using other subsystems.

Platform Neutrality

While certain subsystems may be implemented in terms of operating system features on the server platform, our goal is to have an overall architecture that is highly portable. We choose the Java programming language to help meet this requirement. By extending the Java Web Server we were able to run our WebDAV server on multiple platforms.

Flexibility

The WebDAV specification has been revised several times since the beginning of our project. We designed our architectural framework to minimize the work required to update our WebDAV server to be compliant with these revisions.

Extensibility

Our framework addresses the entire set of WebDAV extensions rather than just those we chose to implement first. In this way, our WebDAV server can be extended over time and gradually brought into greater compliance with the complete WebDAV specification when it becomes available.

Functional Specification

The goal of our design efforts was to specify a system that could easily be extended and modified. To this end, we created a layered architecture where the details of processing extensions to the HTTP protocol are isolated from the underlying subsystems that will carry out the requests. Furthermore, we made it easy to build the lower layers to take advantage of existing systems for features like version control and to make it easy to replace subsystems individually. For example, we envision specifying an interface for version control that could be implemented on top of a variety of third-party or public domain configuration management systems. Thus it would be possible to create multiple plug-compatible subsystems that implement this interface, each leveraging the strengths of its underlying software.

An important criteria for this architecture (and a challenging area for the designers) is the ability to integrate with existing web servers which may have arbitrary resource repositories. Some persistent storage responsibilities will clearly have to be delegated to the specific subsystem implementations. It is also evident that some guidelines or conventions will have to be put in place for accessing that storage if the WebDAV semantics are to be maintained consistently across all possible resource repositories.

In addition to this system-wide issue, design work must be done for specific storage schemes, particularly support for the storage, retrieval, and querying of resource properties. Since the property management subsystem serves as a foundation for many other features of WebDAV it was important that it be designed not just with the support of the methods that address properties in mind. It must also take the needs of other features into account.

Our system architecture is divided into four layers: Protocol Layer, Executive Layer, Subsystem Registry and Functional Subsystems [see Figure 1].

See the diagram Appendix D: Schematic Subsystem Interaction for PROPPATCH Method, to see how the PROPPATCH WebDAV method request would interact with our System Architecture.

Protocol Layer

The top layer of our architecture is primarily concerned with handling the syntactic details of the HTTP protocol and the WebDAV extensions. This includes receiving requests from the Java Web Server, forwarding requests to the Executive Layer and passing responses from the Executive Layer back to the client.

We implemented the Protocol Layer as a Java "servlet" [7] which extends the Java Web Server to handle all HTTP and WebDAV requests and responses.

Executive Layer

The Executive Layer is responsible for coordinating the operations of the subsystems to fulfill a request and for building a response that is compliant with the WebDAV protocol specification. The Executive Layer enforces the "policy" dictated by the WebDAV protocol specification whereas the Functional Subsystems implement the "mechanism" needed to carry out WebDAV requests. By keeping the policy separate from the mechanism, revisions to the WebDAV specification only require changes to the Executive Layer, leaving the Functional Subsystems relatively stable.

A WebDAV request is translated into a sequence of commands. Each command uses an underlying subsystem to perform its task and also stores information which allows the command to be rolled back so that any changes to the resource can be undone. To see the commands used to implement the HTTP and WebDAV methods see the diagram in Appendix D: Command Class Inheritance Hierarchy.

The commands needed to implement a WebDAV request are stored in a CommandQueue which executes each command in order, and upon a critical failure, rolls back all the commands executed. In this way, the CommandQueue provides limited support for atomic transactions to conform to the protocol specification. The design of the CommandQueue allows it to be easily extended or modified as requirements for our WebDAV server change, either by revisions to the WebDAV specification or by the addition of new WebDAV functionality.

An example of a CommandQueue for the PROPPATCH method is shown in Figure 2. A PROPPATCH method can set and remove any number of properties but the entire method must succeed or fail atomically as required by the WebDAV specification. In this example, the failure of the command to remove a property causes the CommandQueue to rollback and undo the previous set property and lock commands.

Figure 2: CommandQueue for PROPPATCH

To see all of the HTTP and WebDAV methods implemented in our WebDAV server, please see Appendix D: Method Class Inheritance Hierarchy.

Subsystem Registry

Once a subsystem has been registered with the Subsystem Registry, it can then be used by the Executive Layer and by other subsystems. A client of a subsystem queries the registry for the specific subsystem interface by specifying the subsystem type and the URL of the resource.

The Subsystem Registry allows multiple versions of the same subsystem to coexist because each subsystem can be responsible for a different URL scope. For example, a WebDAV server could use a local file system to store resources for one directory hierarchy and use a database to store resources for another directory hierarchy. By registering two Namespace Managers, each responsible for a different directory, the proper Namespace Manager will be used depending on which directory the resource resides. This makes it easy to integrate existing legacy systems with our WebDAV server by simply implementing the appropriate subsystem interface.

Functional Subsystems

Using use-case scenarios, we factored the WebDAV requirements into different subsystems and provided a detailed specification for how those subsystems would interact to perform various tasks. For this effort, we used the use-case scenarios provided by the WebDAV working group [6] which ensured that the interfaces we specified were sufficient to allow the subsystems to work together to perform anticipated tasks.

The subsystem interfaces required to implement our WebDAV server are the Namespace Manager, the Property Manager, and the Lock Manager.

Namespace Manager

The subsystem responsible for manipulating resources on the server is the Namespace Manager. The HTTP and WebDAV methods supported by the Namespace Manager are GET, HEAD, POST, PUT, COPY, MOVE, and DELETE. In addition the Namespace Manager provides functionality to validate a resource URL to ensure that the URL refers to a resource on the local server, as opposed to another server, and that the resource exists. Validating a resource is used by certain WebDAV methods as a precondition before the method will be executed. This is a policy that some methods require (e.g., GET, COPY, MOVE) whereas other methods do not (e.g., PUT, LOCK).

The LOCK method is an example of how the design of the Executive Level allows for this policy to change in tandem with changes to the specification. Currently, the WebDAV specification allows a lock to be placed on a resource that does not exist to allow for resources to be reserved before their creation. If this policy were to change to require a resource to exist before being locked, it would simply require adding a resource validation command to the CommandQueue for the LOCK method.

Property Manager

The Property Manager allows for arbitrary metadata to be associated with a resource, provides functionality to retrieve the metadata for a given resource, and allows metadata to be removed from a resource. The WebDAV methods supported by the Property Manager are PROPPATCH and PROPFIND.

The WebDAV property model uses a name-value pair where the property name is a valid Extensible Markup Language (XML) element and the property value is empty or a valid XML element [1, 8, 9]. An example of how XML is used for the PROPPATCH method can be found in Appendix D: Schematic Subsystem Interaction for the PROPPATCH Method. In this example, the request and response bodies are in XML format.

The Property Manager allows the server to handle a configurable set of live properties. Live properties are defined by WebDAV to be "properties whose semantics and syntax are enforced by the server" [1]. An example would be a live "read-only" property on a resource that would be enforced by disallowing modification of that resource. Another example would be a page hit counter property whose value would be the number of times that resource has been retrieved.

Live properties must be handled differently from other properties and the Property Manager supports this by providing entry points for Live Property Handlers. Each Live Property Handler can intercept requests for live properties and enforce the syntax and semantics of those properties. A Live Property Handler supports the WebDAV requirement that resource locks must be viewable via the lock-discovery property. The Live Property Handler intercepts lock-discovery property requests and delegates the lock discovery implementation to the Lock Manager. To see the interaction diagram for how the Live Property Handler intercepts the lock-discovery property see Appendix D: Interaction Diagram: Live Property Delegation.

Since the property management subsystem can serve as a foundation for many other features of WebDAV it was designed not just with the support of the WebDAV methods that address properties in mind. In fact, many of the subsystems that we have not implemented, like the Variants Subsystem, could be implemented using the property management subsystem.

Lock Manager

The Lock Manager provides functionality to allow for resources to be locked (with an exclusive write lock) via the LOCK method and unlocked via the UNLOCK method. In order for locks to be granted on a resource, the user must be authenticated by the server. The Lock Manager also allows the user to retrieve information on the current locks on a resource. If a user is not allowed to modify a resource due to that resource being locked by another user, they can perform lock discovery on the resource to obtain information about the owner of the lock. However, lock discovery must be performed by querying for the lock-discovery property of the resource as explained in the section on the Property Manager.

When a WebDAV client requests that a resource be locked using the LOCK method, the Lock Manager creates a unique lock token that is then passed back to the user as the Lock-Token header. This Lock-Token header must be sent any request that modifies a resource. If a resource is locked and the WebDAV client does not send the appropriate lock token, the request will be denied with a "409 Conflict" HTTP status message.

If a WebDAV client loses its lock token, or would like to discover who has a particular resource locked, they can query for the lock-discovery property of that resource. The lock information returned will contain the lock token and the lock owner information. The lock token can then be used to recreate the lock token and the lock owner information can be used to contact the owner of the lock.

Conclusion

We consider our WebDAV project to be a work-in-progress. Although we have implemented a working Level 2-compliant WebDAV server, there is much room for improvement including optimizing the efficiency and throughput of the server and integrating additional WebDAV functionality as it emerges. In addition we are interested in integrating the functionality of emerging specifications on access control [10], metadata [8], ordered collections, and tree operations [11] into our server. We will go into more detail on targeting specific areas for improvement in the section on Future Work.

Our experience with the Java Web Server Version 1.0.3 proved it to be highly flexible and extensible but also difficult to configure properly and debug. We realized early during the design phase that the Java Web Server would allow us to extend HTTP by allowing our WebDAV Servlet to handle all HTTP method requests. We did not anticipate the number of days we would have to spend trying to diagnose different problems that were causing the Java Web Server to be unable to find our servlet, to return invalid responses, or to completely crash. In memoriam to this effort, we have provided some Java Web Server troubleshooting tips in Appendix A: Installation.

We made use of Microsoft's XML parser package (MSXML) to handle the parsing and generation of XML for WebDAV request and response bodies. During the implementation phase of the project it appeared that a dependency of MSXML on native Windows operating system functionality would prevent our solution from running on Unix platforms. Fortunately, it turned out that the dependency was only in one module, and Microsoft even provides an alternate version of the same file with the dependency removed. The dependency was in the XMLInputStream class (com.ms.xml.util.XMLInputStream.java) and has been discussed extensively on the xml-dev mailing list (search the list archive for "XMLInputStream" at http://www.lists.ic.ac.uk/hypermail/xml-dev/ for more information.) The alternate Windows-free version of XMLInputStream is included in the /make subdirectory of the MSXML installation. Overall, we found the MSXML package to be very well designed and implemented, and quite easy to work with.

Future Work

There are several limitations with our current WebDAV server implementation in the areas of efficiency, concurrency, and support for transactions. For our prototype WebDAV server our highest priority was making sure that all the subsystems functioned correctly and met the requirements mandated by the WebDAV protocol specification. Similarly, our priority for the WebDAV client was to make sure that it could be used to test and demonstrate the functionality of our WebDAV server. The user interface for the client could be redesigned to be more user-friendly and provide support for features that are common in modern Web browsers.

At the executive level of the server architecture, the CommandQueue could be redesigned to support concurrency and transaction management. The current design of the CommandQueue is flexible, extensible and has limited support for transactions. However, the throughput of our WebDAV server is very poor because only one request can be processed at a time. This restriction could be lifted if the CommandQueue was designed to allow concurrent requests to be processed. For example, multiple GET requests could be processed in parallel whereas PUT requests on the same resource must be synchronized to prevent race conditions (the "lost update" problem). In addition to having multiple CommandQueues executing in parallel to fulfill multiple requests, the commands within the CommandQueue could also be executed in parallel. An example of this is the PROPFIND method, which allows the user to request several properties at once. Allowing each property request to proceed in parallel within the PROPFIND CommandQueue would optimize efficiency.

The CommandQueue’s current transaction model is not powerful enough to fully support transactions in a multi-threaded environment or to allow transactions to be rolled back in the event of a server crash. To do this, the subsystems themselves would have to maintain state information between function calls and possibly provide functions to begin and end transactions. This would allow subsystems that use a backend database to take advantage of the database’s built-in transaction management functionality. Alternately, the CommandQueue could employ transaction management software to support transactions.

At the subsystem level, efficiency could be greatly improved by using technologies such as caching, buffered I/O, and databases. Our prototype implementation of the Namespace Manager does not take advantage of in-memory caching, buffered I/O, or the "Last-Modified-By" HTTP header. The "Last-Modified-By" header only requires the retrieval of pages that have been modified since a certain date. The Property Manager could be improved by implementing it using a relational or object-oriented database that would allow for efficient modification and retrieval of properties. As the specification for access control emerges [11], we hope to integrate it into our Lock Manager. We could also improve the security of principal authentication by using the Secure Sockets Layer version of the Java Web Server.

An interesting experiment would be to rewrite Java Web Server’s Server-Side Includes Servlet so that it could recognize requests for and retrieve resource properties using the Property Manager subsystem. This would allow the web server to produce dynamically generated web pages that included arbitrary metadata. An example of how this could be used would be the automatic insertion of author, date and version info into every requested page. Combine this with the new page compilation functionality that is part of Version 1.1 of the Java Web Server, which allows you to embed Java code directly inside a page, and you have a very powerful dynamic page generation solution.

References

Y. Y. Golland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, D. Jensen, "Extensions for Distributed Authoring and Versioning on the World Wide Web." Internet-draft, work-in-progress, November 19, 1997.

http://ds.internic.net/internet-drafts/draft-ietf-webdav-protocol-05.txt

Bentley, R., Appelt, W., Busbach. U., Hinrichs, E., Kerr, D., Sikkel, S., Trevor, J. and Woetzel, G., "Basic Support for Cooperative Work on the World Wide Web," in International Journal of Human-Computer Studies 46(6): Special issue on Innovative Applications of the World Wide Web. Academic Press, June 1997.

http://bscw.gmd.de/Papers/IJHCS/IJHCS.html

Microsoft Web Publishing API Home Page,

http://www.microsoft.com/msdn/sdk/inetsdk/help/itt/web_publishing/wpsdk.htm

G. Kaiser, E. J. Whitehead, Jr., "Distributed Authoring and Versioning", IEEE Internet Computing, Vol. 1, No. 2, March/April 1997.

http://computer.org/internet/9702/collab9702.htm

J. A. Slein, F. Vitali, E. J. Whitehead, Jr., D. Durand, "Requirements for Distributed Authoring and Versioning Protocol for the World Wide Web." RFC XXXX. Xerox, Univ. of Bologna, U.C. Irvine, Boston Univ. YYY, 1997. ftp://ds.internic.net/rfc/rfcXXXX.txt

http://ds.internic.net/internet-drafts/draft-ietf-webdav-requirements-03.txt

O. Lassila, "HTTP-based Distributed Content Editing Scenarios." Internet-draft, work-in-progress, May 1997.

http://ds.internic.net/internet-drafts/draft-ietf-webdav-scenarios-00.txt

JavaSoft Servlet Development Kit Home Page,

http://jserv.javasoft.com/products/java-server/servlets/index.html

R, V. Guha, T. Bray, "Meta Content Framework Using XML",

http://www.w3.org/TR/NOTE-MCF-XML-970624/

T. Berners-Lee, "Notes on Metadata Architecture", Unpublished white paper, January 1997.

http://www.w3.org/pub/WWW/DesignIssues/Metadata.html

P. J. Leach, Y. Y. Golland, "WebDAV ACL Protocol." Internet-draft, work-in-progress, November 10, 1997.

http://ds.internic.net/internet-drafts/draft-ietf-webdav-acl-00.txt

Y. Y. Golland, S. Reddy, "WebDAV Tree Operations." Internet-draft, work-in-progress, November 10, 1997.

http://ds.internic.net/internet-drafts/draft-ietf-webdav-depth-01.txt

IETF WebDAV Working Group Home Page,

http://www.ics.uci.edu/~ejw/authoring

Appendix A: Installation Instructions

System Requirements

Requires the Java Archive (JAR) program, PKZIP.exe or WINZIP.exe to extract the contents of a Java Archive file in addition to the system requirements for the Java Web Server.

Step 1: Installing the Java Web Server

The software and installation instructions for installing the Java Web Server can be found at http://jserv.javasoft.com/products/java-server/downloads/index.html. After you download and install the Java Web Server, follow the instructions to start the Java Web Server for web service on port 8080 (the default port). The installation directory that was chosen for the Java Web Server will hereafter be referred to as the <JavaWebServerRoot>.

Step 2: Verifying the Java Web Server

The Java Web Server installation can be verified by attempting to retrieve a page using any web browser. For example, if the name of the machine that the server was installed on is <servername>, you can verify that the Java Web Server was installed correctly be retrieving the following page

http://<servername>:8080/index.html.

If you receive an error from your browser indicating that the host could not be found, you have not installed the Java Web Server correctly.

Step 3: Installing the WebDAV Servlet

After the Java Web Server is up-and-running, you will need to install the WebDAV servlet Java class files and configure the Java Web Server to use the WebDAV servlet.

You can obtain the WebDAV servlet and WebDAV client Java archive (JAR) file from

webdav.jar.

Once this file has been downloaded, you will need to create a subdirectory underneath the Java Web Server root directory called "classes" and copy the archive file into it. After this file has been copied to the classes directory, you will need to extract the Java source and class files. Here is how you would use the jar program to extract the files from the archive:

<JavaWebServerRoot>\classes > jar xvf webdav.jar

After the archive has been extracted, you should see the following directory hierarchy:

<JavaWebServerRoot>\classes\HTTPClient

<JavaWebServerRoot>\classes\webdav

<JavaWebServerRoot>\classes\com

Step 4: Configuring the Java Web Server to use the WebDAV Servlet

In order for the Java Web Server to be able to use the WebDAV servlet, you must run the Java Web Server Administration Tool. The Administration Tool is an applet that a standard web browser can execute by traversing the following link:

http://<servername>:9090/index.html.

Notice the default port number for the Administration Tool is 9090 instead of 8080. You can login to the Administration Tool by using "admin" for the username and password.

Once you’ve logged into the Administration Tool, select "Web Service" underneath "Java Web Server", and then click on "Manage". When the Web Service Setup tree applet appears, select "Servlet Aliases". You will see a list of directory and filename mappings to servlet names. Select the Alias for the root directory ‘/’. Change the Servlet Invoked from "file" to "webdav" and click "Save". Now you will need to add the "webdav" servlet.

Click on the button at the top of the Web Service applet that says "Servlets". When the Servlets tree appears, select "Add" and on the right-hand side of the applet window you should see a form called "Add a New Servlet". In the field labeled "Servlet Name" type "webdav". In the field labeled "Servlet Class" type "webdav.executive.WebDavServlet". Now click "Add".

You should see a new servlet called "webdav" added to the bottom of the list of Servlets underneath the "Configure" branch on the left-hand side of the applet. The right-hand applet pane should show the configuration parameters for the WebDAV servlet. Make sure the field labeled "Class Name" reads "webdav.executive.WebDavServlet".

Close the Administration Tool and restart the Java Web Server to make sure your changes take effect.

If you are having problems using the Administration Tool, you can modify the property files for the Java Web Server manually using a test editor: (Note, you do not need to do this unless you are having problems with the Administration Tool)

Using a text editor, open the file called <JavaWebServerRoot>\properties\server\javawebserver\webpageservice\rules.properties.
Replace the line that says /=file with /=webdav.
Using a text editor, open the file called <JavaWebServerRoot>\properties\server\javawebserver\webpageservice\servlets.properties.
Add a line at the end of the file that says servlet.webdav.code=webdav.executive.WebDavServlet.

Step 5: Verifying the WebDAV Servlet Installation

At this point, the WebDAV servlet class files have been added to the <JavaWebServerRoot>\classes directory, the Java Web Server has been configured to use the WebDAV servlet instead of the default file servlet, and the Java Web Server has been restarted. To verify the WebDAV servlet, simply open a normal web browser and begin requesting files from the Java Web Server. In particular, you should be able to retrieve the index.html file by requesting the link:

http://<servername>:8080/index.html

If you receive an error from the Java Web Server complaining that the WebDAV servlet cannot be found, make sure that you have completed Step 4 and that the servlet’s class name is webdav.executive.WebDavServlet (the case must be exact).

If you receive an error from your browser complaining that the web server returned an invalid response, the WebDAV servlet class files may be corrupt or an internal error may have occurred in the Java Web Server. See the Troubleshooting Java Web Server section for hints on how to diagnose this. You may have to redo Steps 3 and 4.

To ensure that the WebDAV servlet is being used to retrieve pages and not the default file servlet, try requesting a page that does not exist on the server:

http://<servername>:8080/index.html.does.not.exist

If the WebDAV servlet has been installed correctly, you should see an error page with an error message containing the text, "WebDAV Server – 404 Not Found". If you instead see an error page that does not include the words "WebDAV Server" or you receive one of the above errors, you have not installed the WebDAV servlet properly because the default servlet is being used. You will need to redo Step 4.

Congratulations, you have successfully installed the WebDAV servlet! The WebDAV servlet extends the Java Web Server to be a fully functional WebDAV server.

Step 6: Installing the WebDAV Client

To harness the functionality of the WebDAV server you must use a WebDAV-compliant client program. Unlike normal web browsers, a WebDAV client is able to use the extended WebDAV HTTP methods such as PROPPATCH and LOCK. We have created a simple WebDAV client that demonstrates the basic functionality of the WebDAV server.

If you have not already done so, download the WebDAV Java archive file and extract it into the <JavaWebServerRoot>\classes directory as explained in Step 3.

After you have installed and extracted the WebDAV Java archive file, you can run the client by executing the following line:

<JavaWebServerRoot>\classes >..\bin\java –classpath .;..\lib\rt.jar webdav.client.WebdavClient

Or, if the Java Development Kit is already installed on your system, and your CLASSPATH and PATH system variables are set properly, you can run the client by executing the following line:

<JavaWebServerRoot>\classes > java webdav.client.WebdavClient

If you receive an error stating that the java program could not be found, make sure that the java program can be located in your PATH system variable.

If you receive an error stating that the "webdav/client/WebdavClient" class could not be found, make sure that the <JavaWebServerRoot>\classes path is in your CLASSPATH.

If everything goes smoothly, you should see a Java application window appear with the title "WebDAV Client". See Appendix B: WebDAV Client Usage Instructions for more information on using the WebDAV client.

You have successfully installed the WebDAV client!

Troubleshooting Java Web Server
Problem: JavaWebServer not starting properly on Windows OS. Can't start the JWS administrator. When using "httpd.exe -verbose -verify", I can see all these exceptions being thrown.

Cause: The classes.zip files are locked preventing them from being upgraded properly during an upgrade or a new installation of the JavaWebServer.

Solution: Kill explorer.exe in Task Man. From MSDOS, delete all the classes.zip files that were locked. Start up explorer.exe again.

Cause: The CLASSPATH variable is messing things up (causing conflicts).

Solution: Remove the CLASSPATH variable and restart.

Problem: Servlet does not get unloaded even if the .class file is deleted.

Cause: Servlet has been loaded into memory by the JWS. Java only loads symbols for classes once. However, the ServletInvoker class loads symbols for the servlet classes each time. The moral of this story is that you have to restart the JWS is you want non-servlet classes to be updated after they have been loaded at least once.

Solution: Restart the JWS.

Problem: Could not remove one of the servlets using the admin tool.

Cause: Possible bug in JWS admin tool.

Solution: Remove the desired servlet from D:\projects\JavaWebServer\Properties\Server\JavaWebServer\WebPageService\servlet.properties.

Problem: I want to add a new servlet. How do I make the .class file available?

Solution: Put it into the Servlets directory. You should not need to restart the JWS. Or, you can put it in the D:\projects\JavaWebServer\classes hierarchy.

Problem: Okay, I did that but the servlet is not being found.

Solution: Make sure that you compiled it correctly and that the most recent version is the one in the Servlets directory. Or make sure that the servlet is in the D:\projects\JavaWebServer\classes hierarchy.

Problem: If I recompile a Servlet, do I need to restart the JWS to make sure it picks up the new one?

Solution: Not if its in the Servlets directory because it gets automatically reloaded. All other class updates require you to restart the JWS.

Problem: I have a servlet that uses some classes located in separate files. When I modify one of the classes I don't see the changes reflected in the servlets behavior.

Solution: You have to restart the JWS.

Problem: I am using a servlet that resides in the Servlets directory and I have no problem loading it. However, I get all kinds of problems when my servlet tries to use other classes. In one case, the web browser reported that an invalid response was received.

Cause: This is probably due to the package/class not being found when the servlet is loaded by the ServletInvoker. In this case, the ServletInvoker is dying very ungracefully and causing an invalid http response to be generated, probably something similar to "Package not found exception!"

Solution: Make sure that the class files are located in the CLASSPATH for the JavaWebServer. By causing a servlet to output the System Properties, you can see what the JWS CLASSPATH is.

Here is the code to output the System Properties:

Properties p = System.getProperties();

e = p.propertyNames();

if (e.hasMoreElements())

{

out.println("<h1>System Properties</H1>");

out.println("<pre>");

while (e.hasMoreElements())

{

String strName =

(String) e.nextElement();

String strValue = p.getProperty(strName, "NOT SET");

out.println(strName + " = " + strValue);

}

out.println("</pre>");

}

Here is an example of the System Properties for my system:

java.class.path = d:\projects\javawebserver\classes;

d:\projects\javawebserver\lib\classes.jar;

d:\projects\javawebserver\lib\rt.jar;

d:\projects\javawebserver\lib\i18n.jar;

d:\projects\JAVAWE~1\classes;

d:\projects\JAVAWE~1\lib\classes.zip

So by simply moving the classes into the d:\projects\javawebserver\classes directory, the servlet was able to find them.

Problem: I moved my servlet into that directory and then moved it back to the servlets directory after viewing the servlet once. Now when I make changes to the servlet they don't appear when I reload the page.

Cause: Because the servlet was picked-up from a directory other than "Servlets", the JWS has loaded it into memory so changes won't be detected.

Solution: Remove the servlet class file from the other directory and restart the JWS.

Problem: I keep getting these "Server returned an invalid or unrecognized response!" errors from Internet Explorer when I try to load my servlet.

Cause: The servlet is trying to pull in classes that are invalid or not found. This is usually due to an incorrect package specification in the "package" or "import" lines. The reason why this compiles is because the old .class files previously existed in the invalid directory so the old .class file gets pulled in causing all kinds of mayhem. Another reason is if the class itself is invalid. For example, make sure that the methods you are trying to use are actually accessible (public) to your class.

Solution: Remove all old .class files. The easy way is to delete the class hierarchy and recompile all. The compiler will then complain about incorrect package specifications that you will then have to fix.

Problem: For some reason the JavaWebServer is calling my servlet twice if the servlet fails the first time.

Cause: The servlet is creating an invalid HTTP response that, for some unknown reason, causes the JavaWebServer to call the servlet twice. Our guess is that there is some kind of retry code in the JavaWebServer.

Solution: This is always a problem with the servlet code. Make sure that the servlet is generating a valid HTTP response even if the servlet fails during execution.

Appendix B: WebDAV Client Usage Instructions

The WebDAV client application provides a raw interface for sending HTTP requests and receiving HTTP responses. The possible HTTP methods allowed are GET, PUT, COPY, MOVE, DELETE, PROPFIND, PROPPATCH, LOCK and UNLOCK. A brief description of how to use these methods using the client application will be given. For a more detailed description of these methods or their semantics, please refer to the WebDAV specification [1].

Using a Java interpreter (usually, java or java.exe) run the webdav.client.WebdavClient application. The application should display a window titled "WebDAV Client". If there is a problem starting the WebDAV client application, please see Step 6: Installing the WebDAV Client in Appendix A.

The drop-down Method menu allows you to select the HTTP method you would like to use. For Hostname put the server name of the WebDAV server (<servername>). The Port Number is the port that the Java Web Server is configured to use (default is 8080). The User Name should be your last name and is required for user authentication. The Resource Name is the URL of the resource without the protocol, server name, or port number. In other words, everything after "http://<servername>:8080".

A brief description and examples will now be given for each method.

GET

Summary: Retrieves the resource requested and saves it in the client’s current working directory. The saved file name is the same as the resource name requested relative to the current working directory.

Headers Needed: None.

Example:

Method: GET

Resource Name: /index.html

The http://<servername>/index.html file is retrieved and saved as index.html in the current working directory.

PUT

Summary: Publishes the resource specified by retrieving the contents of the file with the same file name in the current working directory.

Headers Needed: None.

Example:

Method: PUT

Resource Name: /index.html

The index.html file is retrieved from the current working directory and published to the server overwriting http://<servername>:8080/index.html.

COPY

Summary: Copies the resource to the location specified by the "Destination" HTTP header.

Headers Needed: "Destination" is the destination resource name (relative to the web server). "Overwrite" is either true (T) or false (F). If Overwrite is true, the copy method will overwrite the destination resource if it already exists. If Overwrite is false and the destination resource already exists, the copy method will fail with a "412 Precondition Failed" HTTP status message. The Depth header is unused for now.

Example:

Method: COPY

Resource Name: /index.html

Destination: /index.html2

Overwrite: F

Depth: 0

The http://<servername>:8080/index.html source resource is copied to the http://<servername>:8080/index.html2 destination resource on the web server.

MOVE

Summary: Moves the resource to the location specified by the "Destination" HTTP header.

Headers Needed: "Destination" is the destination resource name (relative to the web server). "Overwrite" is either true (T) or false (F). If Overwrite is true, the move method will overwrite the destination resource if it already exists. If Overwrite is false and the destination resource already exists, the move method will fail. The Depth header is unused for now.

Example:

Method: MOVE

Resource Name: /index.html

Destination: /index.html2

Overwrite: F

Depth: 0

The http://<servername>:8080/index.html source resource is moved to the http://<servername>:8080/index.html2 destination resource on the web server.

DELETE

Summary: Deletes the resource specified from the web server.

Headers Needed: None.

Example:

Method: DELETE

Resource Name: /index.html

The http://<servername>:8080/index.html resource is removed from the web server if this user is the owner of the lock on that resource.

PROPPATCH

Summary: Sets or deletes properties for a resource.

Headers Needed: The "XML_file" header is only used by the client application to retrieve the XML file which contains an appropriate PROPPATCH request body. The PROPPATCH method allows properties to be set and deleted by using the XML elements "propertyupdate" which can contain one or more "set" and "remove" elements.

Example #1: Set Properties

For this example, we will create an XML file named set-properties.xml which will hold our request body. Here are the contents of that file:

<set>

<prop>

</prop>

<prop>

</prop>

<prop>

<todo>Get stuff done</todo>

</prop>

</set>

</propertyupdate>

Method: PROPPATCH

Resource Name: /index.html

XML_File: set-properties.xml

The http://<servername>:8080/index.html resource will now contain the "author", "version" and "todo" properties. In the client’s output window you should see a multi-status response indicating that the properties were updated.

Example #2: Remove a Property

For this example, we will create an XML file named remove-properties.xml which will hold our request body. Here are the contents of that file:

<prop>

<todo/>

</prop>

</remove>

</propertyupdate>

Method: PROPPATCH

Resource Name: /index.html

XML_File: remove-properties.xml

The http://<servername>:8080/index.html resource will now only contain the "author" and "version" properties – the "todo" property was removed. In the client’s output window you should see a multi-status response indicating that the properties were updated.

PROPFIND

Summary: Retrieves one property or all of the properties that have been set on the resource specified.

Headers Needed: The "Propfind" header can have one of three values: "allprop", "propname", or a specific property name. Specifying "allprop" causes the PROPFIND method to retrieve all the property names and values that have been defined on the resource. Specifying "propname" causes only the property names to be retrieved for the resource. Specifying a specific property name causes only that property to be retrieved. The Depth header is not currently used.

Example #1: Allprop

For these examples, we assume that the "author" and "version" properties were set using the previous PROPPATCH examples.

Method: PROPFIND

Resource Name: /index.html

Propfind: allprop

Overwrite: F

Depth: 0

You should see the following output in the client application’s output window showing the "author" and "version" properties:

<multistatus><response><href>/index.html</href><prop><version>1.0</version><author>Dr. Foo Bar</author></prop><status>200 OK</status></response></multistatus>

Example #2: Propname

Method: PROPFIND

Resource Name: /index.html

Propfind: propname

Overwrite: F

Depth: 0

You should see the following output in the client application’s output window showing the "author" and "version" property names but not their values:

<multistatus><response><href>/index.html</href><prop><author/><version/></prop><status>200 OK</status></response></multistatus>

Example #3: Author Property

Method: PROPFIND

Resource Name: /index.html

Propfind: author

Overwrite: F

Depth: 0

You should see the following output in the client application’s output window showing only the "author" property:

<multistatus><response><href>/index.html</href><prop><author>Dr. Foo Bar</author></prop><status>200 OK</status></response></multistatus>

LOCK

Summary: Locks the resource requested with an exclusive write lock.

Headers Needed: The LockType header should read "Write" and the LockScope header should read "Exclusive". Do not change these since our WebDAV server only supports exclusive write locks.

Example:

Method: LOCK

Resource Name: /index.html

LockType: Write

LockScope: Exclusive

If the http://<servername>/index.html resource is not already locked by another user, the LOCK method will return success and the client application will obtain a Lock-Token from the LOCK method’s response.

UNLOCK

Summary: Unlocks a resource that was previously locked by the user.

Headers Needed: None.

Example:

Method: LOCK

Resource Name: /index.html

If the http://<servername>/index.html resource was previously locked by this user using the LOCK method, the UNLOCK method should return success.

Appendix C: Source Code and Documentation

The javadoc utility was used to create HTML documentation pages from our source code. The source code documentation is a great deal more verbose and detailed than the summaries given here. You can peruse the source code documentation located at

The source code for our WebDAV Server and Client can be obtained from the Java archive file located at

webdav.jar.

Here is a brief synopsis of the Java classes for our "client", "common", "executive", "nsman", "lockman", and "propman" Java packages.

Package webdav.client

WebdavClient.java	Creates and displays the WebDAV Client user interface.
ClientFrame.java	Basic client user interface class.
WebdavMethod.java	Client-side encapsulation of WebDAV methods.
WebdavRequest.java	Client-side encapsulation of WebDAV HTTP extension requests.
HTTPClient\*.java	Helper HTTP client code borrowed from Ronald Tschalär.

Package webdav.common

Depth.java	Class to encapsulate the WebDAV Depth header semantics.
Principal.java	Class to encapsulate the concept of an authenticated Principal.
SubsystemInterface.java	Interface (currently empty) that all subsystems support.
SubsystemRegistry.java	Provides run-time registry, lookup, and management of different functional subsystems.
SubsystemScope.java	Encapsulates subsystem type and URI scope.
Uri.java	Class to encapsulate the notion of a URI.
UriScope.java	Encapsulates the concept of a namespace subset.
WebDavRequest.java	Defines some common headers required by the WebDAV specification.
WebDavResponse.java	Static definitions of HTTP response codes (including WebDAV extensions) and helper functions.
WebDavRetCode.java	Internal generic response codes.
WebdavXML.java	Static definitions of WebDAV-specific XML tags and utility functions for dealing with XML.

Package webdav.executive

Command.java	Base class for command objects. Command objects encapsulate individual requests on functional subsystems. All Commands support "undo" functionality. CommandQueue treats all derived objects generically as type Command.
CommandQueue.java	Encapsulates the execution and rollback of a chain of Command objects.
CopyMethod.java	Encapsulates the WebDAV COPY method.
CopyPropCmd.java	Command that encapsulates a Property Manager copy property request.
CopyResourceCmd.java	Command that encapsulates a Namespace Manager copy resource request.
DeleteAllPropCmd.java	Command that encapsulates a Property Manager delete all properties request.
DeleteMethod.java	Encapsulates the HTTP DELETE method.
DeletePropCmd.java	Command encapsulates a Property Manager delete property request.
DeleteResourceCmd.java	Command that encapsulates a Namespace Manager delete resource request.
Executive.java	Creates the appropriate Method object and execute it.
GetAllNamesCmd.java	Command that encapsulates a Property Manager get all property names request.
GetAllPropsCmd.java	Command that encapsulates a Property Manager get all properties request.
GetMethod.java	Encapsulates the HTTP GET method.
GetPropCmd.java	Command that encapsulates a Property Manager get property request.
GetResourceCmd.java	Command that encapsulates a Namespace Manager get resource request.
InvalidMethod.java	Null placeholder method to handle not recognized or not implemented HTTP/WebDAV methods.
LockMethod.java	Encapsulates the WebDAV LOCK method.
LockResourceCmd.java	Command that encapsulates a Lock Manager lock resource request.
Method.java	Base class for representing HTTP and WebDAV methods.
MethodFactory.java	Creates the appropriate method object by examining HTTP request method name.
MoveMethod.java	Encapsulates the WebDAV MOVE method.
MovePropCmd.java	Encapsulates a Property Manager move property request.
MoveResourceCmd.java	Encapsulates a Namespace Manager move resource request.
PropCmd.java	Base class for all commands that talk to a Property Manager.
PropFindMethod.java	Encapsulates the WebDAV PROPFIND method.
PropPatchMethod.java	Encapsulates the WebDAV PROPPATCH method.
PutMethod.java	Encapsulates the HTTP PUT method.
PutResourceCmd.java	Command that encapsulates a Namespace Manager put resource request.
SetPropCmd.java	Command that encapsulates a Property Manager set property request.
UnlockMethod.java	Encapsulates the WebDAV UNLOCK method.
UnlockResourceCmd.java	Command that encapsulates a Lock Manager unlock resource request.
ValidateUriCmd.java	Command that encapsulates a Namespace Manager is resource valid request.
WebDavServlet.java	Servlet class to capture all HTTP requests and run them through WebDAV.

Package webdav.nsman

NamespaceInterface.java	Abstract interface for Namespace Manager that all Namespace Manager implementations must support.
NamespaceManager.java	Concrete implementation for a file system Namespace Manager.

Package webdav.lockman

LockManCore.java	Encapsulates the concept of an internal and external lock token that is passed between a Lock Manager and the client.
LockManErrorCode.java	Lock Manager error codes.
LockManIntf.java	Abstract interface for Lock Manager that all Lock Manager implementations must support.
LockManRequest.java	Encapsulates the concept of a client request for a lock on a resource.
SimpleLockManager.java	Supports the Lock Manager interface and provides a partial implementation that supports the semantics of WebDAV locking. The actual implementation is deferred to the implementing subclass.
SimpleLockManagerImpl.java	Concrete implementation of the abstract SimpleLockManager class that provides an implementation using the Property Manager to store locks.

Package webdav.propman

LivePropertyDelegator.java	Abstract interface for LivePropertyDelegators.
LivePropertyHandler.java	Abstract interface for LivePropertyHandlers.
LockPropertyHandler.java	Concrete implementation of LivePropertyHandler and PropertyManager to reflect active Lock Manager locks via the lock-discovery property.
PropertyManager.java	Abstract interface for Property Manager.
PropertySubsystem.java	Concrete implementation of Property Manager and LivePropertyDelegator to allow live property handlers to hook requests or pass them along to SimplePropManager.
SimplePropManager.java	Concrete implementation of Property Manager using file system to store properties.