[PROPOSAL] WebDAV tag library

[Willie Vu <ct...@ust.hk>]

Taglib Users,

I submitted a new proposal for a WebDAV tag library to the Apache Taglibs
sandbox.  I I'd appreciate any feedback that you taglibs users/developers
have to improve the tag library.  Here is the proposal:

----------------------------------------------------------------------------
----
I)   Motivation

WebDAV is an extension to HTTP/1.1 protocol that allows clients to perform 
remote web content authoring operations.  There are many applications
supporting this standard such as Apache, and IIS.  As long as authors make
use 
of a WebDAV-enabled client application, they can collaborate on publishing
work.
There are many proprietary WebDAV clients in the market but the majority are
native clients.  Deploying such clients involves great effort.  Maybe you
want
to standardize on one web authoring tool that supports WebDAV.  Doing so
however, 
hinders flexibility for choosing users' favorite authoring tools.  It gets
more complicated if you have no control over user operating environement.

The solution is having a web-based WebDAV client.  Administration can be 
centralized. In addition, regardless of what tools users edit their work,
they can always publish with the web-based client.  To attain the advantages
this solution brings to us, we need an easy-to-use library that hides the 
details of communication with WebDAV server.  

A WebDAV-compliant tag library is the answer.

This tag library is also useful in another scenario: WebDAV-compliant
web-based
file sharing.  Just like discussion forum, or mailing list, web storage and
web-based file sharing is one of the most common applications that can
really
enrich user collaboration and web experience.  Existing groupware
applications
rely on proprietary servers and proprietary web interfaces.  Integrating
with a 
proprietary locks your system into proprietary technologies.  Based on open
standard, this tag library gives you flexibility to pick best of breed
solutions
in a web-based file sharing application.

There are many other WebDAV-based applications.  Using this tag library, the
effort for a web interface addition to these applications decreases 
tremendously.


----------------------------------------------------------------------------
----
II)  Overview

There are two RFCs regarding WebDAV.  They are the original WebDAV standard
- 
RFC 2518, and a versioning extension - RFC 3253.  The initial release of
this
tag library will only implement RFC 2518.

There are three sets of tags in this library.  One set deals with resources,

another deals with properties and the last one deals with WebDAV context.


Resource Tags
=============


<dav:mkcol>

	MKCOL method - creates a collection resource.  Optionally, sets the
resource
	as the value of a scoped variable.

	Syntax
	------

	<dav:mkcol url="url" 
		[var="varName"] 
		[scope="{page|request|session|application}"] />

	Body Content
	------------

	Empty.


<dav:delete>

	DELETE method - deletes a resource.

	Syntax
	------

	<dav:delete [url="url"] />

	Body Content
	------------

	Empty.


	Description
	-----------

	The resource can be specified via the url attribute.  If this action
is
	nested inside a <dav:resource> action, that resource will be used.

	If a resource is a collection, the entire hierarchy will be deleted.


<dav:putResource>

	PUT method - creates or modifies a non-collection resource.

	Syntax
	------

	Syntax 1: without body content

	<dav:putResource [url="url"]
		value="value" />

	Syntax 2: with body content as the value

	<dav:putResource [url="url"]>
		body content
	</dav:putResource>

	Body Content
	------------

	JSP. The JSP container processes the body content, then the action 
	trims it and processes it further.
	

	Description
	-----------

	This action creates or modifies a non-collection resource.  It sets
	the content of the resource as the value attribute or body content.

	The resource can be specified via the url attribute.  If this action
is
	nested inside a <dav:resource> action, that resource will be used.

	In order to upload a file as the content of a resource, see 
	ResourceContentServlet.

<dav:resource>

	GET method - defines a resource from a URL.  

	Syntax
	------

	Syntax 1: without body content

	<dav:resource url="url" 
		[var="varName"] 
		[scope="{page|request|session|application}"] />

	Syntax 2: with body content

	<dav:resource url="url">
		body content contains child tags that make use of the
		resource specified by this URL.
	</dav:resource>

	Body Content
	------------

	JSP. The JSP container processes the body content and then writes it
	to the current JspWriter.  The action ignores the body content.

	Description
	-----------

	This action gets a resource from WebDAV server.
	If no scoped variable is provided, the defined resource will be used

	by its body content.  Otherwise, the resource is set as the value of

	a scoped variable.

	In order to download the content of a resource to a file, see 
	ResourceContentServlet.

	For example,

	<dav:resource url="http://www.foo.com/webdav/resources/foo1" 
		var="foo1" scope="request" />

	<dav:resource url="http://www.foo.com/webdav/resources/foo1">
		<dav:delete/>
	</dav>


<dav:copy>

	COPY method - copies a resource.  

	Syntax
	------

	<dav:copy [url="url"] 
		tourl="url" 
		[depth="{infinity|0}"
		[overwrite="{true|false}"] />

	Body Content
	------------

	Empty.

	Description
	-----------

	The source resource can be specified via the url attribute.  If this
action
	is nested inside a <dav:resource> action, that resource will be
used.

	If a resource is a collection and depth is not specified, depth is
default 
	to infinity and the entire hierarchy is copied.  If depth is 0 for a

	collection resource, only the collection and its properties but not 
	resources identified by its internal member URIs, are to be copied.

	Note that COPY method does not allow a depth value of 1.


<dav:move>

	MOVE method - moves a resource.  

	Syntax
	------

	<dav:move [url="url"] 
		tourl="url" 
		[overwrite="{true|false}"]/>

	Body Content
	------------

	Empty.

	Description
	-----------

	The source resource can be specified via the url attribute.  If this
action
	is nested inside a <dav:resource> action, that resource will be
used.

	If a resource is a collection, the entire hierarchy is moved.  

<dav:lock>

	LOCK method - locks a resource.  

	Syntax
	------

	<dav:lock [url="url"] 
		[owner="user"]
		[depth="{infinity|0}"
		[locktype="{write}"] 
		[lockscope="{exclusive|shared}"] />

	Body Content
	------------

	Empty.

	Description
	-----------

	The resource can be specified via the url attribute.  If this action
is
	nested inside a <dav:resource> action, that resource will be used.

	The owner specifies the person who holds the current lock.  If owner
is 
	not specified, see <dav:user> on how to resolve owner.

	If a resource is a collection and depth is not specified, depth is
default 
	to infinity.

	Infinity depth means to lock the resource specified by URL and all
its 
	internal members, all the way down the hierarchy.

	0 depth means to just lock the resource specified by URL.

	Note that LOCK method does not allow a depth value of 1.

	Timeout is not supported because WebDAV servers do not have to honor
it.
	This action can be enhanced to support it if required in future.  
	
	Since timeout is not supported, refresh LOCK request is not
supported 
	either.


<dav:unlock>

	UNLOCK method - removes a lock on a resource.  

	Syntax
	------

	<dav:unlock [url="url"] 
		[owner="user"] />

	Body Content
	------------

	Empty.

	Description
	-----------

	The resource can be specified via the url attribute.  If this action
is
	nested inside a <dav:resource> action, that resource will be used.

	The owner specifies the person who holds the current lock.  If owner
is 
	not specified, see <dav:user> on how to resolve owner.


Property Tags
=============


<dav:property>

	PROPFIND method - defines a scoped variable and sets its value to a 
	property of a resource.

	Syntax
	------

	<dav:property property="propertyName" 
		[url="url"] 
		[var="varName"] 
		[scope="{page|request|session|application}"] />

	Body Content
	------------

	Empty.


	Description
	-----------

	The resource can be specified via the url attribute.  If this action
is
	nested inside a <dav:resource> action, that resource will be used.

	WebDAV PROFIND method can retrieve all properties of a single
resource,
	or properties from multiple resources.  This action does not support

	this feature.  A workaround is to use <dav:resource> action to
define 
	a resource.  Then access its properties from the attribute props of 
	the Resource class.


<dav:putProperty>

	PROPPATCH method - modifies a property of a resource.

	Syntax
	------

	Syntax 1: without body content

	<dav:putProperty property="propertyName" value="value"
		[url="url"] />

	Syntax 2: with body content as value

	<dav:putProperty property="propertyName" 
		[url="url"]>
		body content as value
	</dav:putProperty>

	Body Content
	------------

	JSP. The JSP container processes the body content, then the action 
	trims it and processes it further.


	Description
	-----------

	The resource can be specified via the url attribute.  If this action
is
	nested inside a <dav:resource> action, that resource will be used.



Context Tags
============

<dav:user>

	Stores the current user who connects to the WebDAV server. 

	Syntax
	------

	<dav:user value="user" />


	Body Content
	------------

	Empty.

	Description
	-----------

	As a result of using this action, the user specified by the value
attribute
	takes precedent to HttpServletRequest.getPrincipal().  This means
that if 
	this action is used, it should be declared at the beginning of a
page, 
	before any other WebDAV actions.  Subsequent WebDAV actions will be
carried
	out on this user's behalf.
	

<dav:options>

	OPTIONS method - establishes the capability of the WebDAV server.

	Syntax
	------

	<dav:options 
		[url="url"]
		[var="varName"] 
		[scope="{page|request|session|application}"] />

	Body Content
	------------

	Empty.


	Description
	-----------

	Defines a scoped variable and sets its value to an Options class
instance.

	The resource can be specified via the url attribute.  If this action
is
	nested inside a <dav:resource> action, that resource will be used.




Class Options
=============

This class encapsulates the capability of the WebDAV server.  It contains
the following attributes:

- davclass - Collection
- publicMethods - Collection
- allowedMethods - Collection
- dasl


Class Resource
==============

This class encapsulates a resource.  It contains the following attributes:

- url
- content - an InputStream that returns the content of this resource
- parent - a Resource that is the parent of this Resource
- childResources - a Collection of Resources
- props - a Map that maps property names to a single String property value

For example,

<dav:resource url="http://www.foo.com/webdav/resources/foo1" var="foo1" />
<c:forEach var="child" items="${foo1.childResources}">
	<c:out value="${child.url}"/>
	<c:out value='${child.props["aProperty"]}'/>
	<c:forEach var="prop" items="${child.props}">
		<c:out value="${prop.key}"/>
		<c:out value="${prop.value}"/>
	</c:forEach>
</c:forEach>


Class ResourceContentServlet
============================

Content of a resource is available in JSP from the content attribute of 
the Resource class.  Despite its availability, downloading or uploading 
resource content, that may be text or binary, goes outside of JSP and JSP 
tags.  The reason is that JSP is designed for text output.  

This servlet is created to handle download and upload of resource content.


Expected parameters:

url = url of resource
type = { down | up }

If type is not specified, it is default to "down", i.e. download.  If type
is "up", it is for upload.

When upload, one and only one file input type is expected to be 
submitted to this servlet.

For example,

To download,

	You have a link in JSP or HTML that looks like the following:

		http://localhost:8080/servlet/resourceContent?
		url=someEncodedURL&type=down

	Clicking this link will prompt user to save the resource content
	as a file.

To upload,

 	Initially, you have a HTTP form in JSP or HTML that collects the
file 
	to be downloaded.

	<form enctype='multipart/form-data' method='POST' 
	action='http://localhost:8080/servlet/resourceContent'>
		<input type='text' name='url' value='someEncodedURL'>
		<input type='file' name='afile.pdf'>
		<input type='submit' value='upload'>
		<input type='hidden' name='type' value='up'>
	</form>

	After submit, the file is uploaded to the WebDAV server as the
resource 
	content.


----------------------------------------------------------------------------
----
III) Requirements

This tag library requires a servlet container that supports the JavaServer
Pages
Specification, version 1.2 or higher.  It also requires the JSP Standard Tag

Library (JSTL).

It uses a WebDAV-compliant Java API from the Jakarta Slide project.

Jelly is a Jakarta Commons subproject.  It is gaining popularity for its 
capability in XML processing and scripting.  Syntax of Jelly script is
similar
to JSP tags.  As an optional requirement, a Jelly-enabled tag library will
be
created to implement this WebDAV tag library.

----------------------------------------------------------------------------
----
IV)  Commitment

Contributing Institution:

Centre for Enhanced Learning and Teaching, 
Hong Kong University of Science and Technology 
http://celt.ust.hk

Committer:

Willie Vu 
mailto:willievu@yahoo.com

----------------------------------------------------------------------------
----

$Revision: 1.4 $

--
Willie Vu


---------------------------------------------------------------------
To unsubscribe, e-mail: taglibs-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: taglibs-user-help@jakarta.apache.org