<?xml version="1.0"?>

<document>

  <properties>
        <author email="ozeigermann@apache.org">Oliver Zeigermann</author>
        <title>WebDAV Construction Kit</title>
    </properties>

  <body>
  
  <section name="WebDAV Construction Kit (WCK)">
    <p>
      The WebDAV Construction Kit (WCK) is a framework for easy integration of the
      WebDAV interface into all kinds of Java software. No special
      knowledge of Slide or WebDAV is required to make the usual
      Windows, Mac and Linux clients work with your server
      system. These are the main features:</p>
      <ul> 
		<li>adapter for Slide's complex storage mechanism to a
      simple API</li>
		<li>reference implementation and default configuration
      to a complete and simple file system store</li>
		<li>JAAS authentication framwork to completely bypass Slide's
      security mechanism; instead the user base and access rights of
      your server system is used</li>
		<li>generic pooling framwork for connections to your
      server system using commons pool</li>
		<li>build script that compiles WCK to both Slide 2.1
      and the current Slide head</li>
    </ul>
<p><em><b>Important: </b>Currenly, WCK is avaiable from CVS
  only. Check out the <a
  href="http://wiki.apache.org/jakarta-slide/WckQuickStart">WCK Quick
  start page</a> for information how to get it working.</em></p>

<p><em><b>Disclaimer #1: </b>WCK has not been officially released,
yet. This means when you use it consider yourself at most as a beta
tester. Feedback is very welcome!</em></p>

<p><em><b>Disclaimer #2: </b>WCK makes WebDAV integration easier. This
does not mean it can do magic! While no special knowledge of Slide and
WebDAV is required you will need good to excellent knowledge of cvs, ant, Java,
Tomcat, XML configuration files, property files and a general idea of
 how to build software. Using WCK is no act of configuration, but
involves serious programming.</em></p>

<p><em><b>Disclaimer #3: </b>WCK has been developed and tested with
Tomcat 5.0.28. Any other Tomcat version, especially 4.x, is not
recommended. If you happen to make WCK work on any other web container
or application server please report back and tell us what was
involved to make it work.</em></p>

    <p>WCK emerged out of the experience that Slide's storing system is most
flexible and generic, but too complex for many people who just want to
add the WebDAV interface to their systems. Additionally, it contains a
JAAS login module that allows you to bypass Slide's user managerment
and the complete internal access checking. All this is done by your
proprietary system. This, however, is optional to you.</p> 

<p>It is important to understand that all this works only when
you access Slide through its WebDAV interface and only if you restrict
yourself to the core WebDAV methods. It is likely not to work when you
use the native Slide interface. It will not work with ACL, BIND,
SEARCH and DeltaV methods.</p> 
  </section>
  
  <section name="The main interfaces">
    <p>To make Slide work as your WebDAV layer you will have to implement a
single interface: <a href="wck/javadoc/org/apache/slide/simple/store/BasicWebdavStore.html">org.apache.slide.simple.store.BasicWebdavStore</a>. It
contains some call back methods which do not use any Slide classes
except for the exceptions, which I thought are pretty obvious and thus
it would have been silly to more or less clone them. Here they are for
a short reference - detailed information can be found in the <a href="wck/javadoc/index.html">Javadocs</a> of
the respective classes:</p>
      <ul> 
		<li>begin, commit, rollback: begins, commits, aborts a request / transaction</li>
		<li>objectExists, isFolder, isResource: existence checks, collection
  vs. content checks</li>
		<li>createFolder, createResource: creation of a collection or a content resource</li>
		<li>removeObject: deletion of a collection or a content resource</li>
		<li>setResourceContent, getResourceContent: storing and retrieval of a
  content resource</li>
		<li>getLastModified, getCreationDate, getResourceLength: retrieval of
  basic meta data</li>
		<li>getChildrenNames: retrieval of the children of a collection</li>
    </ul>

    <p>This is all Slide and WCK need to make basic WebDAV operations
work. There are optional extension interfaces that add full property
access and locking if your system supports them.</p>

    <p>The second main interface is even simpler and allows you to login into
Slide using your proprietary user database. The glue code will pass
session and connection information to your store as well. All this
allows to effectively bypass Slide's security code and leave this to
your system. All you have to implement are three methods of the
<a href="wck/javadoc/org/apache/slide/simple/authentication/SessionAuthenticationManager.html">org.apache.slide.simple.authentication.SessionAuthenticationManager</a>: 
</p>
      <ul> 
		<li>getAuthenticationSession (2x one with user/password one with user
  only): asks if a certain user exists and authenticated itseld
  correctly and if so an object that allows access to your system,
  i.e. a session or connection or anything similiar, is passed back;
  in case the user has already authenticated correctly before only the
  user with no password is passed</li>
		<li>closeAuthenticationSession: closes the session / terminates the
  connection to your system</li>
    </ul>
    <p>Using this interface the glue code finds out if a user exists and
authenticated itself correctly and passes all relevant information to
the basic WebDAV store for you to make authenticated requests to your
system later. All this is optional, you still can use Slide's internal
security with your WebDAV store if this is not appropriate for
you. For your convenience there also is a connection pool framework at
<a href="wck/javadoc/org/apache/slide/simple/authentication/AbstractPoolingConnectionManager.html">org.apache.slide.simple.authentication.AbstractPoolingConnectionManager</a>
available.</p>

  </section>
  
  <section name="Reference Implementation">
    <p>For the store, the session manager and the pooling connection manager
there are reference implementations to the file system to help you get
going. However, the ones for sessions and connection management are
dummies only as the file system neither needs sessions nor
connections. You can find the code in the
<a href="wck/javadoc/org/apache/slide/simple/reference/package-summary.html">org.apache.slide.simple.reference</a> package.</p>
    <p>The reference implementation of the store part and also
parts of the glue code are heavily inspired by the work of Alon who
provided the simple file store to us - so credit goes to Alon. The new
implementation of the file store extends Alon's in adding arbitrary
properties (optional) and locks (optional) and proper handling of
access violations.</p>
  </section>
  
  <section name="Building and Deploying">
    <p>WCK works with both the current versions of Slide 2.1 and the CVS HEAD
and comes with a build script that creates a full working web archive
to be deployed in Tomcat. Which one it will compile to and package
with is to be determined in build.properties.</p>

    <p>Next to the basic settings in build.properties you can define
      additional paths of source and libraries and other settings to
      adapt WCK to your own project. Copy build.properties.sample and
      uncomment and set the appropriate properties:</p>
      <ul> 
		<li>domain: the path of the Domain.xml to use</li>
		<li>jaas.config: the JAAS configuration that contains the reference to your session manager and optionally more parameters</li>
		<li>slide.properties: special Slide properties can that
      selectively be switch on and off; the default switches off
      Slide's internal security as your own should be used, versioning
      and search are switched off as well as WCK does not support them</li>
    </ul>

    <p>If you do not change anything the defaults from the conf
  directory and the reference implementations will be used.</p>

<p><em>A <a href="http://wiki.apache.org/jakarta-slide/WckQuickStart">Quick start page</a> with the default implementations can be found here.</em></p> 

  </section>
  
  <section name="Where to go from here?">
    <p>A dedicated place for user comments and information is in the
    <a href="http://wiki.apache.org/jakarta-slide/WebDavConstructionKit">Slide Wiki</a> pages. Questions are welcome in the 
<a href="http://jakarta.apache.org/site/mail2.html#Slide">Slide user
mailing list</a>. Be sure to subscribe to the list before posting
anything as it will not come through otherwise.</p>

  </section>
</body>
</document>
