*** This package contains classes that provide Binary Compatibility only, not Source Compatibility ***

Note:

Extension of the classes in this package is prohibited unless otherwise documented. Similarly, extension or implementation of the interfaces in this package is prohibited except as documented.

Package com.sas.services.webdav

Provides a client API for accessing WebDAV servers.

See:
Description

Interface Summary

DAVResourceInterface

Provides the interface for a DAV Resource.

Class Summary

ConnectionInfo	Identifies all the information required to make a connection to a DAV server.
DAVConstants	A convenience class to collect all the constants used in the DAV environment.
DAVResource	A DAVResource represents a WebDAV (Distributed Authoring and Versioning) resource as specified in IETF RFC 2518.
NamespaceMap	Implements a specific map from prefixes to namespace URI's.
PropertyMap	Maps properties to their values.
PropertyName	This class represents a qualified property name.
Utils	A convenience class to bring together a number of utilties.

Exception Summary

DAVException

DAVException Wrapper for any exception that might occur in the DAV resource code.

Package com.sas.services.webdav Description

Provides a client API for accessing WebDAV servers.

DAVClient

Overview
What is WebDAV?
Apache DAV setup
DAV Error Codes
Apache Software Licence

Overview

DAVClient services provide a native Java client interface for webDAV communications. WebDAV is an IETF standard and is documented in RFC2518. The WebDAV site has more information about WebDAV. DAVClient is based on Apache Slide client, which provides the plumbing on which DAVClient is built. This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

Examples

Using DAVResource

Create a new collection, create a new resource in the collection, set its contents and then set a property on the resource.

     try {
        DAVResource col = new DAVResource("http://server/base/NewCollection");
        col.makeCollection();
        if (col.getStatusCode == HttpStatus.SC_METHOD_NOT_ALLOWED) {
          // collection already exists
          col.delete();
          col.makeCollection();
        }
        DAVResource res = new DAVResource("http://server/base/NewCollection/NewResource");
        res.setContents( contentString.getBytes() );
        res.setProperty( new PropertyName("Colour", "Z", "http://example.org/namespace"), "Red" );
     } catch (DAVException e) {}
 

Host information can be specified in a ConnectionInfo object, and this could include the resource URI, user name and password, proxy server information. For example,

     try {
        ConnectionInfo host = new ConnectionInfo( "http://server/base/NewCollection" );
        host.setUser( "john" );
        host.setPW( "smith" );
        DAVResource col = new DAVResource( host, logger );
        ...
     } catch (DAVException e) {}
 

Using Collection and Resource

Create a new collection, create a new resource in the collection, set its contents and then set a property on the resource.

     try {
        Collection col = ResourceFactory.createCollection("http://server/base/NewCollection");
        if ( col != null ) {
           Resource res = col.createResource("NewResource");
           res.setContents( contentString.getBytes() );
           PropertyMap props = new PropertyMap();
           props.put( "{http://example.org/namespace}Colour", "Red" );
           res.setProperties( props );
     } catch (DAVException e) {}
 

What is WebDAV?

As mentioned above, WebDAV is an IETF standard and is documented in RFC2518. WebDAV is an extension to the HTTP protocol with the aim of providing the functionality required to do Distributed Authoring and Versioning on the web. This includes a number of new methods, extensions to standard HTTP headers and methods. In addition, many of the new methods provide for an XML payload/body to provide a structured request or response, and also an extended set of errors, listed below is also defined.

New Methods	Description
PROPFIND	Discover the properties of a DAV resource
PROPPATCH	Set or remove the properties of a DAV resource
MKCOL	Make a collection resource (eg. a new folder)
COPY	Copy a resource to another location
MOVE	Move a resource to another location
LOCK	Lock a resource
UNLOCK	Unlock a resource

Here is an example PROPFIND exchange of information between a DAV client and server.

DAVClient (with the help of the Slide client) converts method call requests into these DAV requests with XML bodies to send to the server. Responses from the server are interpreted by DAVClient and results are returned from the method calls.

Interestingly, there is no real versioning included in the WebDAV specification - this has been moved to another DAV specification called "Versioning Extensions to WebDAV" described in RFC3253. There are two other important standards in progress at the moment. First is the "WebDAV Access Control Protocol" and the second is "DAV Searching and Locating".

Setting up DAV on Apache servers

Apache 1

Install the mod_dav module from http://www.webdav.org/mod_dav/ (or http://www.webdav.org/mod_dav/win32 for Windows) and add the following line to the httpd.conf file:

 LoadModule dav_module mod_dav.dll
 

Also add the following to define the locking database in the global environment section of httpd.conf.

 # webDAV extension
 DavLockDB /temp/DavLock
 

Now define a directory with DAV turned on by adding something like the following to the httpd.conf file

 # webDAV extension
 <Directory "c:/program files/apache group/apache/htdocs/foo">
 Dav On
 DavDepthInfinity On
 Options None
 AllowOverride None
 </Directory>
 

Apache 2

DAV is supplied with the server. Uncomment the following two lines in the httpd.conf file:

 LoadModule dav_module modules/mod_dav.so
 LoadModule dav_fs_module modules/mod_dav_fs.so
 

Also add the following to define the locking database in the global environment section of httpd.conf.

 # webDAV extension
 DavLockDB /temp/DavLock2
 

Now define a directory with DAV turned on by adding something like the following to the httpd.conf file

 # webDAV extension
 <Directory "c:/program files/apache group/apache2/htdocs/foo">
 SetEnv redirect-carefully 1
 Dav On
 Options None
 AllowOverride None
 </Directory>
 

Apache2 has introduced a response of "301 Moved Permanently" on collection/directory request URI's that do not end in a slash. To prevent this Apache2 provides a directive to disable redirects on non-GET requests for a directory that does not include the trailing slash. This is the "redirect-carefully" directive used in the example above. At this time the 301 response is not supported and so this directive is required.

Error codes

WebDAV extends the set of HTTP error codes that might be returned from the server. The table below lists the standard error codes and provides a description and explanation of when this error might occur. The error code might appear in a DAVException message or when using the getStatusCode() method provided in the DAVClient API.

Error Code	Method	Description
All 100 level codes	*	Informational
100 Continue [ HTTP]		Initial part of incomplete request was accepted by server. [ HTTP]
101 Switching Protocols [ HTTP]		Server wants to switch to a newer version, or real-time protocol, to continue. Used when an Upgrade header was in the client request. [ HTTP]
102 Processing [WebDAV]	MOVE, COPY	Can be used to indicate status of ongoing processes, particularly processes that use the Depth Header. This is to avoid having the client time-out with an error. [ WebDAV]
All 200 level codes	*	Success
200 OK [ HTTP]	GET, HEAD, OPTIONS, LOCK, POST, DELETE	Typical successful response for these methods, in cases where no new resource is created. [ HTTP]
	TRACE	Trace was reflected back to sender [ HTTP]
	PROPFIND, PROPPATCH	Possible successful response if all props were successfully returned or set. Not used in Microsoft implementations, see code 207. [ WebDAV]
201 Created [ HTTP]	POST, PUT	Resource successfully created [ HTTP]. If the action cannot be completed immediately, a 202 must be returned instead. [ HTTP/1.1]
	MKCOL, MOVE	A collection successfully created or resource successfully moved. [ WebDAV]
	LOCK	If you do a LOCK on a null resource, the LOCK will create the resource.
202 Accepted [ HTTP]	DELETE, PUT, POST	Resource will be created or deleted but it has not yet been created or deleted [ HTTP].
203 Non-authoritative Information [ HTTP]	Any	Meta-information in the header did not come from origin server. Used only when response would otherwise be 200 OK. [ HTTP] Use of this response code is not required. [ HTTP/1.1]
204 No Content [ HTTP]	POST, PUT	Standard success response when no resource was created [ HTTP]. The server has fulfilled the request but does not need to return an entity-body, and might want to return updated meta information. [ HTTP/1.1]. With PUT, the 204 response allows the server to send back an updated etag and other entity information about the resource that has been affected by the PUT operation. This allows the client to do the next PUT using the If-Match precondition to ensure that edits are not lost.
	DELETE, UNLOCK	Standard success response. [ WebDAV]
	COPY, MOVE	The source resource was successfully copied or moved to a pre-existing destination resource. [ WebDAV]
205 Reset Content [ HTTP]		Server has fulfilled request and client should reset document view. Must not include an entity. [ HTTP]
206 Partial Content [ HTTP]	GET	Only some of the resource was returned, with Range Header to indicate how much. [ HTTP]
207 MultiStatus [ WebDAV]	PROPFIND, PROPPATCH, SEARCH, MKCOL	Typical successful response. [ WebDAV]
	COPY, MOVE	If an error in executing the COPY occurs with a resource other than the request Uniform Resource Identifier (URI), then the response must be 207. 424 and 201 responses should NOT be values in 207 multistatus responses to COPY. [ WebDAV]
	LOCK	Used with a multiresource lock request. [ WebDAV]
All 300 level codes	*	Redirection? (further action must be taken to complete request)
300 Multiple Choices [ HTTP]	GET, HEAD	The requested resource corresponds to any one of a set of representations, each with its own specific location, and agent-driven negotiation information (section 12) is being provided so that the user (or user agent) can select a preferred representation and redirect its request to that location. [ HTTP]
301 Moved Permanently [ HTTP]	GET, HEAD	New permanent URI has been assigned to resource. [ HTTP]
	PUT	Server wishes to apply the PUT to a different URI than the one in the method.
302 Moved Temporarily [ HTTP]	GET, HEAD	New temporary URI has been assigned to resource. [ HTTP]
302 Found [ HTTP/1.1]	GET, HEAD, other	The requested resource resides temporarily under a different URI. Since the redirection might be altered on occasion, the client SHOULD continue to use the Request-URI for future requests. [ HTTP/1.1]
303 See Other [ HTTP]	POST	Typically used to respond to a POST, because a response to a POST cannot be stored in the cache, but the response to a GET can. Client uses GET to see other. [ HTTP]
304 Not Modified [ HTTP]		If the client has performed a conditional GET request and access is allowed, but the document has not been modified, the server SHOULD respond with this status code. The response MUST NOT contain a message-body. [ HTTP]
305 Use Proxy [ HTTP]	Any	The requested resource MUST be accessed through the proxy given by the Location field. [ HTTP/1.1]
306 Unused		The 306 status code was used in a previous version of the specification and is no longer used; in addition, the code is reserved. [ HTTP/1.1]
307 Temporary Redirect [ HTTP/1.1]	GET, HEAD	The requested resource resides temporarily under a different URI.
All 400 level codes	*	Client Failure
400 Bad Request [ HTTP]	Any	Malformed syntax, for example, empty namespace name in the Extensible Markup Language (XML) body. [ HTTP]
	SEARCH	No body, invalid scope, etc. The query could not be executed. The request may be malformed (for example, invalid XML). In addition, this can be used for invalid scopes and search redirections.
401 Unauthorized [ HTTP]	Any	Resource requires authorization or authorization was refused [ HTTP]
	PROPPATCH	Execute a PROPPATCH on two properties, one of which requires authentication to change and the other does not. Result: The entire request will be rejected with a 401.
402 Payment Required [ HTTP]	Any
403 Forbidden [ HTTP]	Any	The server understood the request but will not do it. Authorization will not help.
	MKCOL, LOCK, PROPPATCH	Client does not have permissions to make a collection, lock the resource, or set a property. [ WebDAV] Check-out attempt: this will be returned if the resource is not versioned or if the resource is a collection.
404 Not Found [ HTTP]	Any	Resource named was not found. [ HTTP]
405 Method Not Allowed [ HTTP]	Any	The method was not allowed for the resource named. [ HTTP] The response MUST include an Allow header containing a list of valid methods for the requested resource. [ HTTP/1.1]
	MKCOL	This might occur if the resource already exists and thus cannot be created. [ WebDAV]
406 Not Acceptable [ HTTP]	Any	The resource identified by the request is capable only of generating response entities that have content characteristics that are not acceptable according to the Accept headers sent in the request. The response SHOULD include an entity containing a list of available entity characteristics and location(s) from which the user or user agent can choose the one most appropriate. [ HTTP/1.1]
	HEAD	The response need not include an entity as above.
407 Proxy Authentication Required [ HTTP]	Any	This code is similar to 401 (Unauthorized), but it indicates that the client MUST first authenticate itself with the proxy. [ HTTP/1.1]
408 Request Timeout [ HTTP]	Any	The client did not produce a request within the time that the server was prepared to wait. [ HTTP/1.1]
409 Conflict [ HTTP]	MKCOL	A collection cannot be created until intermediate collections have been created. [ WebDAV]
	PROPPATCH	The client has provided a value whose semantics are not appropriate for the property, for example, trying to set a read-only property. [ WebDAV]
	PUT	Cannot PUT a resource if all ancestors do not already exist. [ WebDAV]. If versioning is being used and the entity being PUT includes changes to a resource that conflict with those made by an earlier (third-party) request, the server might use the 409 response code to indicate that it can't complete the request. [ HTTP/1.1]
410 Gone [ HTTP]	GET	The requested resource is no longer available on the server and no forwarding address is known. This condition is considered permanent. [ HTTP/1.1]
411 Length Required [ HTTP]	Any	The server refuses to accept the request without a defined Content-Length. [ HTTP/1.1]
412 Precondition Failed [ HTTP]	Any	The precondition given in one or more of the Request header fields evaluated to false when it was tested on the server. [ HTTP/1.1]
	COPY, MOVE	The server was unable to maintain the live-ness of the properties listed in the property behavior XML element, or the Overwrite Header is F and the state of the destination resource is non-null. [ WebDAV]
	LOCK	The lock token could not be enforced or the server could not satisfy the request in the lockinfo XML element.
413 Request Entity Too Large [ HTTP]	Any	The server refuses to process a request because the request entity is larger than what the server is willing or able to process. [ HTTP/1.1]
414 Request URI Too Large [ HTTP]	Any	The server refuses to service the request because the Request-URI is longer than what the server is willing to interpret. [ HTTP/1.1]
415 Unsupported Media Type [ HTTP]	Any	The server refuses to service the request because the entity of the request is in a format that is not supported by the requested resource for the requested method.
	MKCOL	The server does not support the request type of the body. [ WebDAV]
416 Requested Range Not Satisfiable [ HTTP/1.1]		A server SHOULD return a response with this status code if a request included a Range Header field (section 14.35), if none of the range-specifier values in this field overlap with the current extent of the selected resource, and if the request did not include an If-Range request-header field. [ HTTP/1.1]
417 Expectation Failed [ HTTP/1.1]		The expectation given in an Expect request-header field (see section 14.20) could not be met by this server or, if the server is a proxy, the server has unambiguous evidence that the next-hop server could not meet the request. [ HTTP/1.1]
422 Unprocessable Entity [ WebDAV]	MKCOL	The server understands the content type of the request entity, but was unable to process the instructions that it contains. [ WebDAV] For example, the MKCOL has a request body that is not understood or is incomplete, even if in XML, which is generally accepted in this situation.
	SEARCH	Valid XML body in a SEARCH, but unsupported or unimplemented query operator.
	LOCK	Non-zero depth was specified for a check-out lock, or the Depth Header was omitted.
423 Locked [ WebDAV]	PROPPATCH, DELETE, MOVE	Cannot set properties on, delete, move, or lock a locked resource without the lock token. [ WebDAV]
	LOCK	Already locked (need lock token). [ WebDAV] The user tries to create a transaction within a transaction [TRANS].
	COPY	The destination resource was locked. [ WebDAV]
424 Method Failure [ WebDAV]	PROPPATCH	The method was not executed on a resource because some part of the method's execution failed and the whole method was aborted. [ WebDAV]
	UNLOCK	One of the methods in the transaction failed, therefore the entire transaction failed.
425 Insufficient Space on Resource	SEARCH	The query produced more results than the server was willing to transmit. Partial results have been transmitted.
All 500 Level Codes	*	Server Failure
500 Internal Server Error [ HTTP]		The server encountered an unexpected condition that prevented it from fulfilling the request. [ HTTP/1.1]
501 Not Implemented [ HTTP]	Any	The server does not support the functionality that is required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource. [ HTTP/1.1]. Contrast with 405.
	PUT	Error when a server receives a Content-* header it does not understand in a PUT operation.
502 Bad Gateway [ HTTP]		The server, while acting as a gateway or proxy, received an invalid response from the upstream server that it accessed in attempting to fulfill the request. [ HTTP/1.1]
	COPY, MOVE	The destination could be on another server and the destination server refuses to accept the resource. [ WebDAV]
503 Service Unavailable [ HTTP]		The server is currently unable to handle the request due to temporary overloading or to maintenance of the server. The implication is that this is a temporary condition that will be alleviated after a delay. [ HTTP/1.1]
504 Gateway Timeout		The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI (for example, HTTP, File Transfer Protocol (FTP), Lightweight Directory Access Protocol (LDAP)) or some other auxiliary server (for example, DNS) that it needed to access to complete the request. [ HTTP/1.1]
505 HTTP Version not supported	Any	The server does not support, or refuses to support, the HTTP protocol version that was used in the request message. [ HTTP/1.1]
507 Insufficient Storage	PROPPATCH, MKCOL	The resource does not have enough space to set the properties or make the collection. [ WebDAV]
	COPY	The destination resource does not have sufficient space. [ WebDAV]
	SEARCH	The query produced more results than the server was willing to transmit. Partial results have been transmitted. The server MUST send a body that matches the body for code 207, except that there MAY exist resources that matched the search criteria for which no corresponding response exists in the reply.

References

WebDAV Goland et al, HTTP Extensions for Distributed Authoring -- WebDAV, RFC 2518.

HTTP T. Berners-Lee et al, Hypertext Transfer Protocol -- HTTP/1.0, RFC 1945.

HTTP 1.1 Fielding et al, HyperText Transfer Protocol -- HTTP/1.1, RFC 2616.

? 2000-2001 Microsoft Corporation. All rights reserved. Terms of use.

Apache Software License

Apache Software License Version 1.1 Copyright (c) 2000 The Apache Software Foundation. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment:
   "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.
4. The names "Apache" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org.
5. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*** This package contains classes that provide Binary Compatibility only, not Source Compatibility ***

Note:

Extension of the classes in this package is prohibited unless otherwise documented. Similarly, extension or implementation of the interfaces in this package is prohibited except as documented.