JavaScript WebDAV Library

JavaScript WebDAV Library

1 Introduction to the JavaScript WebDAV library

I am proud to introduce JavaScript WebDAV library webdav.js which based on AJAX. This library consists the special class webdav which is aimed to make all requests supported by eXo Platform WebDAV-server with supported parameters.

Proposed library supports asynchronous (on default) and synchronous mode of AJAX request processing. To set one of some of this mode you should call webdav.setAsynchronous() or webdav.setSynchronous() method.

Also this library can fulfill BASIC HTTP authentication using value of preset webdav.username and webdav.password properties.

Scheme of WebDAV data exchange:

2 Content of JavaScript WebDAV Library

There is a list of realized methods:

• ExtensionMethod(handler, path, options) method - a simple constructor of the user-defined WebDAV request.

1. WebDAV Modifications to HTTP Operations:

• GET(handler, path, options) method - retrieves the content of a resource.
• PUT(handler, path, options) method - saves the content of a resource to the server.
• DELETE(handler, path, options) method - removes a resource or collection.
• OPTIONS(handler, path, options) method - returns the HTTP methods that the server supports for specified URL.
• MKCOL(handler, path, options) method - creates a collection.
• COPY(handler, path, options) method - copies a resource from one URI to another.
• MOVE(handler, path, options) method - moves a resource from one URI to another.
• HEAD(handler, path, options) method - asks for the response identical to the one that would correspond to a HEAD request, but without the response body. This is useful for retrieving meta-information written in response headers, without having to transport the entire content.

2. WebDAV Property Operations:

• PROPFIND(handler, path, options) method - retrieves properties, stored as XML, from a resource. It is also overloaded to allow one to retrieve the collection structure (a.k.a. directory hierarchy) of a remote system.
• PROPPATCH(handler, path, options) method - changes and deletes multiple properties on a resource in a single atomic act.

3. WebDAV Lock Operations:

• LOCK(handler, path, options) method - puts a lock on a resource.
• UNLOCK(handler, path, options) method - removes a lock from a resource.

4. WebDAV Versioning Extension Operations:

• VERSIONCONTROL(handler, path, options) method - is used to create a new version-controlled resource for an existing version history. This allows the creation of version-controlled resources for the same version history in multiple workspaces.
• CHECKOUT(handler, path, options) method - can be applied to a checked-in version-controlled resource to allow modifications to the content and dead properties of that version-controlled resource.
• CHECKIN(handler, path, options) method - can be applied to a checked-out version-controlled resource to produce a new version whose content and dead properties are copied from the checked-out resource.
• UNCHECKOUT(handler, path, options) method - can be applied to a checked-out version-controlled resource to cancel the CHECKOUT and restore the pre-CHECKOUT state of the version-controlled resource.
• REPORT(handler, path, options) method - an extensible mechanism for obtaining information about a resource.
• ORDERPATCH(handler, path, options) method - is used to change the ordering semantics of a collection, to change the order of the collection's members in the ordering, or both.

5. WebDAV SEARCH Operation:

• SEARCH(handler, path, options) method - a lightweight search method to transport queries and result sets that allows clients to make use of server-side search facilities retrieve properties, stored as XML, from a resource.

1. name of method (passing throw parameter options.method),
2. request headers (passing throw parameter options.headers) and
3. request body (passing throw parameter options.body).

1. handler.onSuccess - will call if the request succeeds,
2. handler.onError - will call if the request fails,
3. handler.onComplete - will call if the request completes.

Each method returns object result which consists next properties:

1. result.status - status of XMLHttp response,
2. result.statusstring - an explanation of status,
3. result.headers - object with hash of XMLHttpRequest response.getAllResponseHeaders() (e.g. if this the response header is "Content-Type: test/plain" then result.headers['Content-Type'] = 'test/plain'),
4. result.content = XMLHttprequest response.responseXML if response.header['Content-Type'] consists 'xml', or = XMLHttpRequest response.responseText otherwise.

3 Example of using of JavaScript WebDAV library

An example of using WebDAV library for the eXo Platform WebDAV-server:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Demonstration of the eXo Platform Client Library of WebDAV</title>
    <script type="text/javascript" src="js/webdav.js"></script>
    <script>    

	// Example of using of eXo Platform Client Library of WebDAV
	/**
	 * Serialize an XML Document or Element and return it as a string.
	 */
	function XMLtoString(node) {
	    if (typeof node != 'object') return node; 
	    if (typeof XMLSerializer != "undefined")
	        return (new XMLSerializer( )).serializeToString(node);
	    else if (node.xml) return node.xml;
	    else throw "XML.serialize is not supported or can't serialize " + node;
	};

	// get and setup webdav object
        var webdav = new Webdav('localhost', '8080');
            
        webdav.username = 'root';
        webdav.password = 'exo';

	// define webdav methods handlers
        function handler_onSuccess(result) {
            alert('Request SUCCEEDED with status = ' + result.status + ': ' + result.statusstring);
        };

        function handler_onError(result) {
            alert('Request FAILED with status = ' + result.status + ': ' + result.statusstring);
        };

	var handler = {
	    onSuccess: handler_onSuccess,
	    onError: handler_onError,
	    onComplete: MKCOL_handler_onComplete
	}

	// for eXoPlatform webdav
	var default_webdav_path = '/rest/jcr/repository/collaboration';		

	// create a collection 'test'
	webdav.MKCOL(handler, default_webdav_path + '/test1');

	// create a resource 'example.txt' with content 'an example'
        function MKCOL_handler_onComplete(result) {
	    // create a resource 'example.txt' with content 'an example' 
	    var options = {
		content: 'an example',
		content_type: 'text/plain; charset=UTF-8'			
	    }
	    handler.onComplete = PUT_handler_onComplete;
	    webdav.PUT(handler, default_webdav_path + '/test1/example.txt', options);
        };
		
	// put resource example.txt under version control
        function PUT_handler_onComplete(result) {
	    // put resource example.txt under version control  
	    handler.onComplete = VERSIONCONROL_handler_onComplete;
    	    webdav.VERSIONCONTROL(handler, default_webdav_path + '/test1/example.txt');
        };
		
	// obtain the 'version-tree' WebDAV report about 'example.txt'        
        function VERSIONCONROL_handler_onComplete(result) {
	    // obtain the 'version-tree' WebDAV report about 'example.txt'
	    var options = {
	        depth: '0',
	        type: 'version-tree'
	    };
	    handler.onComplete = REPORT_handler_onComplete;
	    webdav.REPORT(handler, default_webdav_path + '/test1/example.txt', options);		
        };
		
        // delete the collection 'test'		
        function REPORT_handler_onComplete(result) {
            if ( result.content )
		alert( 'Response of server: ' +  XMLtoString(result.content) );

            // delete the collection 'test'
	    handler.onComplete = 'function() {}';
	    webdav.DELETE(handler, default_webdav_path + '/test1/');
        };
    </script>
</head>
<body>
    <h2>Demonstration of the eXo Platform Client Library of WebDAV</h2>
</body>
</html>

4 How to get JavaScript WebDAV library

You can get this library at the http://svn.exoplatform.org/svnroot/exoplatform/projects/ws/branches/2.0.x/frameworks/javascript/webdav/src/main/js

Demonstration page was placed as http://svn.exoplatform.org/svnroot/exoplatform/projects/ws/branches/2.0.x/frameworks/javascript/webdav/src/main/index.html

JSDoc is available at the http://svn.exoplatform.org/svnroot/exoplatform/projects/ws/branches/2.0.x/frameworks/javascript/webdav/src/main/doc

Another place of Javadoc will be at the http://docs.exoplatform.com.ua site soon.