Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

[r17271]: apps / doc / data / webdav.xml Maximize Restore History

Download this file

webdav.xml    219 lines (219 with data), 15.9 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: webdav.xml 17271 2012-10-08 15:00:16Z joewiz $ -->
<book>
<bookinfo>
<graphic fileref="logo.jpg"/>
<productname>eXist-db – Open Source Native XML Database</productname>
<title>Using WebDAV to Access the Database</title>
<date>March 2011</date>
<author>
<firstname>Dannes</firstname>
<surname>Wessels</surname>
<affiliation>
<address format="linespecific">
<email>dizzzz@exist-db.org</email>
</address>
</affiliation>
</author>
</bookinfo>
<chapter id="webdav">
<title>WebDAV</title>
<section id="webdav">
<title>Introducing WebDAV</title>
<para>eXist-db ships with a <ulink url="http://en.wikipedia.org/wiki/WebDAV">WebDAV</ulink> interface. WebDAV makes it possible to manage database
collections and documents just like directories and files in a file system. You can copy,
move, delete, view or edit files with any application supporting the WebDAV protocol, including Windows
Explorer, Mac OS X Finder, <ulink url="http://www.webdav.org/cadaver">cadaver</ulink>, <ulink url="http://www.konqueror.org/">KDE Konqueror</ulink>, <ulink url="http://www.oxygenxml.com/">oXygen XML Editor</ulink>, <ulink url="http://www.altova.com/">XML Spy</ulink>, <ulink url="http://www.libreoffice.org/">LibreOffice</ulink> and many others (see "Compatibility" below).</para>
<para>While eXist-db has had WebDAV support since version 1.0b2, the new WebDAV implementation since
version 1.4.1 brings improved WebDAV compatibility, thanks to its use of the excellent open-source <ulink url="http://milton.ettrema.com/">Milton</ulink> WebDAV API for Java. </para>
<para>In the default configuration
the WebDAV server can be accessed via the URLs <ulink url="http://localhost:8080/exist/webdav/db/">http://localhost:8080/exist/webdav/db/</ulink> and <ulink url="https://localhost:8443/exist/webdav/db/">https://localhost:8443/exist/webdav/db/</ulink> (since eXist-db 2.0).
</para>
</section>
<section id="compatibility">
<title>Compatibility</title>
<para>The <ulink url="http://milton.ettrema.com/">Milton</ulink> project maintains a detailed WebDAV client
<ulink url="http://milton.ettrema.com/guide/compat/">compatibility list</ulink> that describes a "Recipe
for broad client compatibility." In case of any problems please read this document. However, some preliminary points
specific to eXist should be kept in mind:</para>
<itemizedlist>
<listitem>
<para>For Windows 7 see notes below and at the hints on the
<ulink url="http://milton.ettrema.com/guide/compat/">Milton documentation</ulink>.</para>
</listitem>
<listitem>
<para>eXist's Milton based WebDAV interface does not currently support HTTP Digest Authentication.</para>
</listitem>
<listitem>
<para>The size of an XML document is presented as a multiple of 4096 bytes, which is eXist's
internal pagesize (see <ulink url="configuration.xml#conf.xml">conf.xml</ulink>). The actual
size on an XML document stored in the database can not be determined because the size depends on many factors, e.g. the applied
serialization parameters.</para>
</listitem>
</itemizedlist>
<para>The Milton-based WebDAV interface has been successfully tested with: Windows Web Folders (Windows XP/7), <ulink url="http://www.jscape.com/products/file-transfer-clients/anyclient/">AnyClient</ulink> (cross-platform), Mac OS X
Finder, <ulink url="http://www.panic.com/transmit/">Transmit</ulink> (Mac OS X),
<ulink url="http://cyberduck.ch/">Cyberduck</ulink>, davfs2 version 1.4.5 (Linux),
OxygenXML and LibreOffice.</para>
<para>The following clients are reported to have issues: <ulink url="http://en.wikipedia.org/wiki/GVFS">GVFS</ulink> (Nautilus) and <ulink url="http://www.netdrive.net/">NetDrive</ulink>. (Compatibility can change over time)</para>
</section>
<section id="clients">
<title>Clients</title>
<section id="webfolders">
<title>Windows Web Folders</title>
<para>Out of the box, Windows (XP, 7) has <emphasis role="italic">some</emphasis> native support for
the WebDAV protocol, but there are some well-known issues. Please consult the
following articles in case of any problem.</para>
<note>
<para>Be aware that there are multiple versions of WebDAV Microsoft libraries
(and different flavors of bugs). To avoid some frustration if the steps
below don't work for you, <ulink url="http://support.microsoft.com/?kbid=892211">Update Windows XP for
Web Folders</ulink>, or take more information about <ulink url="http://greenbytes.de/tech/webdav/webfolder-client-list.html">Web
Folder Client (MSDAIPP.DLL) Versions and Issues</ulink>.</para>
</note>
<note>
<para>Windows Vista and Windows 7 both restrict access to WebDAV servers that
use Basic HTTP authentication on non-SSL connections. This restriction can
be solved by changing a registry key. Read more on <ulink url="http://support.microsoft.com/kb/841215">MSDN</ulink> and <ulink url="http://greenbytes.de/tech/webdav/webdav-redirector-list.html">greenbytes.de</ulink>. However, SSL connections do bring improved
security.</para>
</note>
<para>Perform the following steps in Internet Explorer: <itemizedlist><listitem><para>Select <command>File -&gt; Open</command>.</para></listitem><listitem><para>Fill in URL like
<command>http://localhost:8080/exist/webdav/db/</command> or
<command>https://localhost:8443/exist/webdav/db/</command>.</para></listitem><listitem><para>Check "Open as Web Folder".</para></listitem><listitem><para>Click OK.</para></listitem></itemizedlist>
<screenshot><graphic fileref="resources/webdav_xp_webfolders.png"/></screenshot>
</para>
</section>
<section id="networkplaces">
<title>Windows XP's My Network Places</title>
<para>This enables you to access eXist-db from almost any Windows XP application that supports 'Network
Places' in the standard File dialog: <screenshot><graphic fileref="resources/webdav_xp_mnp0.png"/></screenshot>
</para>
<para>First, go to "My Network Places", click "Add..." <screenshot><graphic fileref="resources/webdav_xp_mnp1.png"/></screenshot>
</para>
<para>Then select the service provider. <screenshot><graphic fileref="resources/webdav_xp_mnp2.png"/></screenshot>
</para>
<para>Then enter the eXist-db WebDAV URL, e.g. http://localhost:8080/exist/webdav/db/. <screenshot><graphic fileref="resources/webdav_xp_mnp3.png"/></screenshot>
</para>
<para>Finally click on the icon to access eXist-db. <screenshot><graphic fileref="resources/webdav_xp_mnp4.png"/></screenshot>
</para>
</section>
<section id="macosx">
<title>Mac OS X Finder</title>
<para>The eXist-db database can be accessed easily with the Mac OS X Finder. First select in the Finder "Go"
and "Connect to Server..." <screenshot><graphic fileref="resources/webdav_macosx_1.png"/></screenshot>
</para>
<para>Fill in the eXist-db WebDAV URL http://localhost:8080/exist/webdav/db/ <screenshot><graphic fileref="resources/webdav_macosx_2.png"/></screenshot>
</para>
<para>Enter a username and password... <screenshot><graphic fileref="resources/webdav_macosx_3.png"/></screenshot>
</para>
<para>And the database is accessible! <screenshot><graphic fileref="resources/webdav_macosx_4.png"/></screenshot>
</para>
<note>
<para>In the last few OSX releases Apple repetitively changed their WebDAV implementation
significantly, repetitively introducing new bugs and problems. The main issue is that
Finder requires exact document sizes reported for PROPFIND where as eXist-db by default
reports a guesstimated size as mentioned in the Compatibility chapter</para>
<para>As a workaround, eXist-db detects the OSX finder via the "user-agent" HTTP header and switches for PROPFIND
into a kind of OSX compatibility mode where all XML documents in a collection are serialized
to determine the exact sizes of these documents. This is a rather expensive and
time consuming operation for large documents and for collections with many documents.</para>
<para>I recommend to use <ulink url="http://www.panic.com/transmit/">Transmit</ulink> or
<ulink url="http://cyberduck.ch/">Cyberduck</ulink> instead.</para>
</note>
</section>
<section id="oxygenxml">
<title>oXygen XML Editor</title>
<para>
<itemizedlist>
<listitem>
<para>Select <command>File -&gt; Open URL</command>.</para>
</listitem>
<listitem>
<para>Fill <command>User</command> and <command>Password</command>.</para>
</listitem>
<listitem>
<para>Enter <command>Server URL</command> http://localhost:8080/exist/webdav/db/.</para>
</listitem>
<listitem>
<para>Click <command>Browse</command>.</para>
</listitem>
</itemizedlist>
<screenshot>
<graphic fileref="resources/webdav_oxygen.png"/>
</screenshot>
</para>
<note>
<para>Note on SSL connections in oXygen: You may encounter an error: "Error:
sun.security.validator.ValidatorException: PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification
path to requested target."</para>
<para>In order to avoid this error, you'll need to add the Server certificate to your trusted certificates keystore (<ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#CustomizingStores">more info</ulink>).</para>
</note>
<note>
<para>Warning: When saving a document to the WebDAV server via oXygen, remember to double check that
the document path in the File URL field at the top of the dialog does really contain the URL to
which you want to save the document. It happens very easily that you click on another folder or
resource by mistake and thus overwrite the wrong resource. </para>
</note>
</section>
<section id="xmlspy">
<title>XML Spy</title>
<para>
<itemizedlist>
<listitem>
<para>Select <command>File -&gt; Open URL</command></para>
</listitem>
<listitem>
<para>Enter <command>Username, Password</command>
</para>
</listitem>
<listitem>
<para>Enter <command>Server URL</command> without a slash on the end (otherwise you'll see
2x 'db')</para>
</listitem>
</itemizedlist>
<screenshot>
<graphic fileref="resources/webdav_xmlspy.png"/>
</screenshot>
</para>
</section>
<section id="kde">
<title>KDE Konqueror</title>
<para>Enter an URL like <command>webdav://localhost:8080/exist/webdav/db</command>. Use
<command>webdavs://</command> for WebDAV over SSL. <screenshot><graphic fileref="resources/webdav_konqueror.png"/></screenshot>
</para>
</section>
<section id="libreoffice">
<title>LibreOffice</title>
<para>For LibreOffice and OpenOffice.org the recommended way for opening documents
that are stored in eXist-db is using the 'native' WebDAV client, as documented in
the <ulink url="http://help.libreoffice.org/Common/Opening_a_Document_Using_WebDAV_over_HTTPS">LibreOffice Help</ulink> documentation.</para>
<note>
<para>Warning: When using LibreOffice on OSX, do not write documents to a network share
that is mounted via Finder as documented earlier, since this could corrupt
your database. The problem has been identified but there is no solution yet. Please use
the alternative described in this chapter.</para>
</note>
<para>
The first step is configuring LibreOffice to use the LibreOffice Open/Save dialogs instead
of the dialogs that are provided by the operating system:
<screenshot><graphic fileref="resources/webdav_libreoffice_settings.gif"/></screenshot>
Now it is possible to type an URL in the File-Open dialog. Enter <ulink url="http://localhost:8080/exist/webdav/db/">http://localhost:8080/exist/webdav/db/</ulink> and provide your login credentials. Now the dialogbox
shows the content of the database:
<screenshot><graphic fileref="resources/webdav_libreoffice_open.gif"/></screenshot>
</para>
</section>
</section>
<section id="revert">
<title>Reverting to the old WebDAV implementation</title>
<para>Before eXist-db version 1.4.1 a custom implementation was used. This implementation has been
deprecated because it was not stable enough and many WebDAV clients could not connect to the
server. Although not recommended, it is possible to switch back to the old implementation by
modifying the WebDAV configuration entry in the file <command>WEB-INF/controller-config.xml</command>.
Modify the line
<synopsis format="linespecific">&lt;forward pattern="/webdav/" servlet="milton"/&gt;</synopsis> into
<synopsis format="linespecific">&lt;forward pattern="/webdav/" servlet="WebDAVServlet"/&gt;</synopsis>.
</para>
</section>
</chapter>
</book>