<?xml version="1.0" encoding="UTF-8"?>
<!-- This document was created with Syntext Serna Free. -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<section id="JCR.WebDAV">
  <title>WebDAV</title>

  <para>The WebDAV protocol enables you to use the third party tools to
  communicate with hierarchical content servers via HTTP. It is possible to
  add and remove documents or a set of documents from a path on the server.
  DeltaV is an extension of the WebDav protocol that allows managing document
  versioning. Locking guarantees protection against multiple access when
  writing resources. The ordering support allows changing the position of the
  resource in the list and sort the directory to make the directory tree
  viewed conveniently. The full-text search makes it easy to find the
  necessary documents. You can search by using two languages: SQL and
  XPATH.</para>

  <para>In eXo JCR, we plug in the WebDAV layer - based on the code taken from
  the extension modules of the reference implementation - on the top of our
  JCR implementation so that it is possible to browse a workspace using the
  third party tools (it can be Windows folders or Mac ones as well as a Java
  WebDAV client, such as DAVExplorer or IE using File-&gt;Open as a Web
  Folder).</para>

  <para>Now WebDav is an extension of the REST service. To get the WebDav
  server ready, you must deploy the REST application. Then, you can access any
  workspaces of your repository by using the following URL:</para>

  <para>Standalone mode:</para>

  <para><uri>http://host:port/rest/jcr/{RepositoryName}/{WorkspaceName}/{Path}</uri></para>

  <para>Portal mode:</para>

  <para><uri>http://host:port/portal/rest/private/jcr/{RepositoryName}/{WorkspaceName}/{Path}</uri></para>

  <para>When accessing the WebDAV server with the
  URL<uri>http://localhost:8080/rest/jcr/repository/production</uri>, you
  might also use "collaboration" (instead of "production") which is the
  default workspace in eXo products. You will be asked to enter your login and
  password. Those will then be checked by using the organization service that
  can be implemented thanks to an InMemory (dummy) module or a DB module or an
  LDAP one and the JCR user session will be created with the correct JCR
  Credentials.</para>

  <note>
    <para>If you try the "in ECM" option, add "@ecm" to the user's password.
    Alternatively, you may modify jaas.conf by adding the <emphasis
    role="bold">domain=ecm</emphasis> option as follows:</para>

    <programlisting>exo-domain {
     org.exoplatform.services.security.jaas.BasicLoginModule required domain=ecm;
};</programlisting>
  </note>

  <para><emphasis role="bold">Related documents</emphasis></para>

  <itemizedlist>
    <listitem>
      <para><link linkend="JCR.LinkProducerService">Link Producer
      </link></para>
    </listitem>
  </itemizedlist>

  <section id="JCR.WebDAV.Configuration">
    <title>Configuration</title>

    <programlisting language="xml">&lt;component&gt;
  &lt;key&gt;org.exoplatform.services.jcr.webdav.WebDavServiceImpl&lt;/key&gt;
  &lt;type&gt;org.exoplatform.services.jcr.webdav.WebDavServiceImpl&lt;/type&gt;
  &lt;init-params&gt;

    &lt;!-- default node type which is used for the creation of collections --&gt;
    &lt;value-param&gt;
      &lt;name&gt;def-folder-node-type&lt;/name&gt;
      &lt;value&gt;nt:folder&lt;/value&gt;
    &lt;/value-param&gt;

    &lt;!-- default node type which is used for the creation of files --&gt;
    &lt;value-param&gt;
      &lt;name&gt;def-file-node-type&lt;/name&gt;
      &lt;value&gt;nt:file&lt;/value&gt;
    &lt;/value-param&gt;

    &lt;!-- if MimeTypeResolver can't find the required mime type, 
         which conforms with the file extension, and the mimeType header is absent
         in the HTTP request header, this parameter is used 
         as the default mime type--&gt;
    &lt;value-param&gt;
      &lt;name&gt;def-file-mimetype&lt;/name&gt;
      &lt;value&gt;application/octet-stream&lt;/value&gt;
    &lt;/value-param&gt;

    &lt;!-- This parameter indicates one of the three cases when you update the content of the resource by PUT command.
         In case of "create-version", PUT command creates the new version of the resource if this resource exists.
         In case of "replace" - if the resource exists, PUT command updates the content of the resource and its last modification date.
         In case of "add", the PUT command tries to create the new resource with the same name (if the parent node allows same-name siblings).--&gt;

    &lt;value-param&gt;
      &lt;name&gt;update-policy&lt;/name&gt;
      &lt;value&gt;create-version&lt;/value&gt;
      &lt;!--value&gt;replace&lt;/value --&gt;
      &lt;!-- value&gt;add&lt;/value --&gt;
    &lt;/value-param&gt;

    &lt;!--
        This parameter determines how service responds to a method that attempts to modify file content.
        In case of "checkout-checkin" value, when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout and followed by a checkin operation.
        In case of "checkout" value, when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout operation.
        In case of "checkin-checkout" value, when a modification request is applied, the request is automatically preceded by a checkin then a checkout operation.
    --&gt;         
    &lt;value-param&gt;
      &lt;name&gt;auto-version&lt;/name&gt;
      &lt;value&gt;checkout-checkin&lt;/value&gt;
      &lt;!--value&gt;checkout&lt;/value --&gt;
    &lt;/value-param&gt;

    &lt;!--
        This parameter determines the list of  (workspace, absolute path ) where the auto versioning is enabled.
        When a new version of a non-versioned document is uploaded through WebDAV, the new version replaces the existing one.
        When a new version of a versioned document is uploaded through WebDAV, the new version is automatically created.
    --&gt;

    &lt;value-param&gt;
            &lt;name&gt;allowed.folder.auto-version&lt;/name&gt;
       &lt;value&gt;workspace1:path1;workspace1:path2;workspace2:path3&lt;/value&gt;
    &lt;/value-param&gt;

    &lt;!--
        This parameter allow to enable auto versioning strategy (updatePolicyType : create-version , autoVersion : checkin-checkout).
    --&gt;

    &lt;value-param&gt;
       &lt;name&gt;enableAutoVersion&lt;/name&gt;
       &lt;value&gt;false&lt;/value&gt;
    &lt;/value-param&gt;


       &lt;!--
        This parameter is responsible for managing Cache-Control header value which will be returned to the client.
        You can use patterns like "text/*", "image/*" or wildcard to define the type of content.
    --&gt;  
    &lt;value-param&gt;
      &lt;name&gt;cache-control&lt;/name&gt;
      &lt;value&gt;text/xml,text/html:max-age=3600;image/png,image/jpg:max-age=1800;*/*:no-cache;&lt;/value&gt;
    &lt;/value-param&gt;
    
    &lt;!--
        This parameter determines the absolute path to the folder icon file, which is shown
        during WebDAV view of the contents
    --&gt;
    &lt;value-param&gt;
      &lt;name&gt;folder-icon-path&lt;/name&gt;
      &lt;value&gt;/absolute/path/to/file&lt;/value&gt;
    &lt;/value-param&gt;

    &lt;!--
        This parameter determines the absolute path to the file icon file, which is shown
        during WebDAV view of the contents
    --&gt;
    &lt;value-param&gt;
      &lt;name&gt;file-icon-path&lt;/name&gt;
      &lt;value&gt;/absolute/path/to/file&lt;/value&gt;
    &lt;/value-param&gt;

    &lt;!-- 
        This parameter is responsible for untrusted user agents definition.
        Content-type headers of listed here user agents should be
        ignored and MimeTypeResolver should be explicitly used instead 
    --&gt;
    &lt;values-param&gt;
      &lt;name&gt;untrusted-user-agents&lt;/name&gt;
      &lt;value&gt;Microsoft Office Core Storage Infrastructure/1.0&lt;/value&gt;
    &lt;/values-param&gt;

    &lt;--
        Allows to define which node type can be used to
        create files via WebDAV.
        Default value: nt:file
    --&gt;
    &lt;values-param&gt;
      &lt;name&gt;allowed-file-node-types&lt;/name&gt;
      &lt;value&gt;nt:file&lt;/value&gt;
    &lt;/values-param&gt;

    &lt;--
        Allows to define which node type can be used to
        create folders via WebDAV.
        Default value: nt:folder
    --&gt;
    &lt;values-param&gt;
      &lt;name&gt;allowed-folder-node-types&lt;/name&gt;
      &lt;value&gt;nt:folder&lt;/value&gt;
    &lt;/values-param&gt;

  &lt;/init-params&gt;
&lt;/component&gt;</programlisting>
      <note>
        <para>
            If the MimeTypeResolver throws exceptions of type "eu.medsea.mimeutil.detector.InvalidMagicMimeEntryException: Invalid Magic Mime Entry"
            on RHEL or CentOS, you should use the mime cache file instead of the magic mime file.
            To provide the full path to the mime cache file, you will need to use the system property exo.mime.cache.
        </para>
     </note>
     <note>
        <para>
            You can use pattern like "^(Microsoft Office Excel 2013).*(Windows NT 6.1)$"
            to define the untrusted user agent.
        </para>
     </note>
      <note>
        <para>
        If the  configuration parameter enableAutoVersion has been set to true :
        </para>
        <para>
          - A system property called jcr.documents.versions.max allows to define the max number of versions that a document can have.
          When a new version is added for a document, if the max number is reached, only the X last versions are kept,
          the other ones are permanently deleted. A non-positive value means no limit. Defaults to 0 (so no limit).</para>
        <para>
          -  A system property called jcr.documents.versions.expiration allows to define the expiration time (in days) of a document version.
          When the expiration time is reached, the version is permanently deleted. The last version of a document is never deleted.
          A non-positive value means no limit. Defaults to 0 (so no limit).
        </para>
     </note>
  </section>

  <section id="JCR.WebDAV.Screenshots">
    <title>Screenshots</title>

    <para>At present, eXo JCR WebDav server is tested by using MS Internet
    Explorer, <ulink url="http://www.ics.uci.edu/~webdav">Dav
    Explorer</ulink>, <ulink
    url="http://www.blackboard.com/Platforms/Learn/Products/Blackboard-Learn/Blackboard-Xythos/Xythos-Drive.aspx">Xythos
    Drive</ulink>, Microsoft Office 2003 (as client), and Ubuntu Linux.</para>

    <section id="JCR.WebDAV.Screenshots.MSInternetExplorer">
      <title>MS Internet Explorer</title>

      <para>(File -&gt; Open as Web Folder)</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/protocols/webdav_explorer.jpg"/>
        </imageobject>
      </mediaobject>
    </section>

    <section id="JCR.WebDAV.Screenshots.DavExplorer">
      <title>Dav Explorer</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/protocols/webdav_davexplorer.jpg"/>
        </imageobject>
      </mediaobject>
    </section>

    <section id="JCR.WebDAV.Screenshots.XythosDrive">
      <title>Xythos Drive</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/protocols/webdav_xythosdrive.jpg"/>
        </imageobject>
      </mediaobject>
    </section>

    <section id="JCR.WebDAV.Screenshots.MicrosoftOffice2003">
      <title>Microsoft Office 2003</title>

      <para>(as client) (File-&gt;Open with typing http://... href in the file
      name box)</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/protocols/webdav_msoffice2003.jpg"/>
        </imageobject>
      </mediaobject>
    </section>

    <section id="JCR.WebDAV.Screenshots.UbuntuLinux">
      <title>Ubuntu Linux</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/protocols/webdav_ubuntulinux.jpg"/>
        </imageobject>
      </mediaobject>
    </section>
  </section>

  <section id="JCR.WebDAV.ComparisonTableOfWebDavAndJCRCommands">
    <title>Comparison table of WebDav and JCR commands</title>

    <table>
      <title/>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>WebDav</entry>

            <entry>JCR</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>COPY</entry>

            <entry>Workspace.copy(...)</entry>
          </row>

          <row>
            <entry>DELETE</entry>

            <entry>Node.remove()</entry>
          </row>

          <row>
            <entry>GET</entry>

            <entry>Node.getProperty(...); Property.getValue()</entry>
          </row>

          <row>
            <entry>HEAD</entry>

            <entry>Node.getProperty(...); Property.getLength()</entry>
          </row>

          <row>
            <entry>MKCOL</entry>

            <entry>Node.addNode(...)</entry>
          </row>

          <row>
            <entry>MOVE</entry>

            <entry>Session.move(...) or Workspace.move(...)</entry>
          </row>

          <row>
            <entry>PROPFIND</entry>

            <entry>Session.getNode(...); Node.getNode(...);
            Node.getNodes(...); Node.getProperties()</entry>
          </row>

          <row>
            <entry>PROPPATCH</entry>

            <entry>Node.setProperty(...);
            Node.getProperty(...).remove()</entry>
          </row>

          <row>
            <entry>PUT</entry>

            <entry>Node.addNode("node","nt:file");
            Node.setProperty("jcr:data", "data")</entry>
          </row>

          <row>
            <entry>CHECKIN</entry>

            <entry>Node.checkin()</entry>
          </row>

          <row>
            <entry>CHECKOUT</entry>

            <entry>Node.checkout()</entry>
          </row>

          <row>
            <entry>REPORT</entry>

            <entry>Node.getVersionHistory(); VersionHistory.getAllVersions();
            Version.getProperties()</entry>
          </row>

          <row>
            <entry>UNCHECKOUT</entry>

            <entry>Node.restore(...)</entry>
          </row>

          <row>
            <entry>VERSION-CONTROL</entry>

            <entry>Node.addMixin("mix:versionable")</entry>
          </row>

          <row>
            <entry>LOCK</entry>

            <entry>Node.lock(...)</entry>
          </row>

          <row>
            <entry>UNLOCK</entry>

            <entry>Node.unlock()</entry>
          </row>

          <row>
            <entry>ORDERPATCH</entry>

            <entry>Node.orderBefore(...)</entry>
          </row>

          <row>
            <entry>SEARCH</entry>

            <entry>Workspace.getQueryManager(); QueryManager.createQuery();
            Query.execute()</entry>
          </row>
          <row>
            <entry>ACL</entry>

             <entry>Node.setPermission(...)</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </section>

  <section id="JCR.WebDAV.Restrictions">
    <title>Restrictions</title>

    <para>There are some restrictions for WebDAV in different Operating
    systems.</para>

    <section id="JCR.WebDAV.Restrictions.Windows7">
      <title>Windows 7</title>

      <para>When you try to set up a web folder by “adding a network location”
      or “map a network drive” through My Computer, you can get an error
      message saying that either “The folder you entered does not appear to be
      valid. Please choose another” or “Windows cannot access… Check the
      spelling of the name. Otherwise, there might be…”. These errors may
      appear when you are using SSL or non-SSL.</para>

      <para>To fix this, do as follows:</para>

      <orderedlist>
        <listitem>
          <para>Go to Windows Registry Editor.</para>
        </listitem>

        <listitem>
          <para>Find a key:
          \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlset\services\WebClient\Parameters\BasicAuthLevel
          .</para>
        </listitem>

        <listitem>
          <para>Change the value to 2.</para>
        </listitem>
      </orderedlist>
    </section>

    <section id="JCR.WebDAV.Restrictions.MicrosoftOffice2010">
      <title>Microsoft Office 2010</title>

      <para>If you have Microsoft Office 2010 applications or Microsoft Office
      2007 applications installed on a client computer. From that client
      computer, you try to access an Office file that is stored on a web
      server that is configured for Basic authentication. The connection
      between your computer and the web server does not use Secure Sockets
      Layer (SSL). When you try to open or to download the file, you
      experience the following symptoms: <itemizedlist>
          <listitem>
            <para>The Office file does not open or download.</para>
          </listitem>

          <listitem>
            <para>You do not receive a Basic authentication password prompt
            when you try to open or to download the file.</para>
          </listitem>

          <listitem>
            <para>You do not receive an error message when you try to open the
            file. The associated Office application starts. However, the
            selected file does not open.</para>
          </listitem>
        </itemizedlist></para>

      <para>To enable Basic authentication on the client computer, follow
      these steps:</para>

      <orderedlist>
        <listitem>
          <para>Click Start, type regedit in the Start Search box, and then
          press Enter.</para>
        </listitem>

        <listitem>
          <para>Locate and then click the following registry subkey:</para>

          <para>HKEY_CURRENT_USER\Software\Microsoft\Office\14.0\Common\Internet</para>
        </listitem>

        <listitem>
          <para>On the Edit menu, point to New, and then click DWORD
          Value.</para>
        </listitem>

        <listitem>
          <para>Type BasicAuthLevel, and then press Enter.</para>
        </listitem>

        <listitem>
          <para>Right-click BasicAuthLevel, and then click Modify.</para>
        </listitem>

        <listitem>
          <para>In the Value data box, type 2, and then click OK.</para>
        </listitem>
      </orderedlist>
    </section>
  </section>

  <section id="JCR.WebDAV.Restrictions.SNS">
    <title>Same name sibling</title>

    <para>The JSR 170 allows JCR nodes under specific conditions to have sub
    nodes of the same name which is not supported by the webdav clients. To
    workaround that, the nodes of the same name are displayed with their index
    in case the index is higher than 1, so if for example we have 2 nodes
    called <emphasis>foo</emphasis>, the first one will be displayed
    <emphasis>foo</emphasis> (as before) and the second one will be displayed
    <emphasis>foo[2]</emphasis>. Thanks to this approach, all webdav clients
    will be able to display the entire content of your repository even if you
    have some nodes of the same name.</para>

    <para>If you want to replace a file whose name is
    <emphasis>foo[3]</emphasis> which means that it is the 3th node called foo
    understand the same parent node, if you paste a file with the exact same
    name (assuming that the update policy allows it), the old file content
    will be replaced with the new one.</para>

    <note>
      <para>As you cannot assign an index explicitly according to the JSR 170,
      you can face some situations where the original name won't be the final
      name. For example you copy the 3th node called <emphasis>foo</emphasis>
      into a directory that doesn't have any node called
      <emphasis>foo</emphasis>, in that case the original name was
      <emphasis>foo[3]</emphasis> but the final name will be
      <emphasis>foo</emphasis>. Those kind of use cases could be not properly
      managed by the Webdav client, it won't find the node at the expected
      location so it will assume that the operation failed but actually the
      name has simply changed. As workaround, you can copy the file outside
      webdav, then set the final name and finally put the file at the expected
      location such that the original and final names will be
      identical.</para>
    </note>
  </section>
</section>
