Difference between revisions of "WebDAV"

From BaseX Documentation
Jump to navigation Jump to search
(48 intermediate revisions by 6 users not shown)
Line 1: Line 1:
This page is part of the [[Developer Section]]. It describes how to use the WebDAV API of BaseX.
+
This page presents one of the [[Web Application]] services. It describes how to use the WebDAV file system interface.
  
BaseX offers access to the databases and documents using the [http://en.wikipedia.org/wiki/Webdav WebDAV] protocol. WebDAV provides convenient means to access and edit XML documents by representing BaseX databases and documents in the form of a file system hierarchy.
+
BaseX offers access to the databases and documents using the [https://en.wikipedia.org/wiki/Webdav WebDAV] protocol. WebDAV provides convenient means to access and edit XML documents by representing BaseX databases and documents in the form of a file system hierarchy.  
  
==Starting WebDAV==
+
The implementation in BaseX is based on the [http://milton.io Milton library]. Currently, only Basic Authentication is supported.
  
The WebDAV implementation of BaseX is provided by a module (servlet) which runs in the BaseX HTTP server. Please check the [[Startup#BaseX HTTP Server|Startup: BaseX HTTP Server]] page for details on how to start the HTTP Server. The WebDAV service can either use the local databases or connect to a remote BaseX Server, as described in the [[Startup_Options#BaseX_HTTP_Server|startup options]] page.
+
=Usage=
  
==Accessing WebDAV==
+
By default, the BaseX HTTP server makes the WebDAV service accessible at {{Code|http://localhost:8984/webdav/}}. If no default credentials are specified, they will be requested by the client ([[Web Application#User Management|see further]]). It can be accessed by either <code>http:&#47;&#47;<httphost>:<httpport>/webdav/</code> or <code>webdav://<httphost>:<httpport>/webdav/</code>, depending on your WebDAV client.
  
The BaseX WebDAV Server can be accessed using either with a <code>http:&#47;&#47;<httphost>:<httpport>/webdav/</code> or <code>webdav://<httphost>:<httpport>/webdav/</code> URL, depending on the used WebDAV client. By default, after
+
Please note that the file size of XML documents will be displayed as 0 bytes, as the actual file size can only be determined if the full document is being returned and serialized. This may cause problems with some WebDAV clients (e.g. NetDrive or WebDrive).
starting the HTTP server, the following URL will be provided: <code>http://localhost:8984/webdav/</code>.
 
  
==Authorization==
+
=Authorization=
  
The WebDAV service uses the database user credentials in order to perform authentication and authorization. If database user and password are explicitly specified when starting the BaseX HTTP Server using the corresponding [[Startup_Options#BaseX_HTTP_Server|startup options]], WebDAV will not request additional user authentication from the client.
+
The WebDAV service uses the database user credentials in order to perform authentication and authorization. Initial user name and password are both set to <code>admin</code>. If database user and password are explicitly specified when starting the BaseX HTTP Server using the corresponding [[Command-Line Options#BaseX_HTTP_Server|startup options]], WebDAV will not request additional user authentication from the client.
  
==WebDAV Clients==
+
=Root Directory=
  
===oXygen Editor===
+
In the WebDAV root directory, all existing databases are listed. As new resources can only be stored inside a database, it is not possible to store files in the root directory. If a file is copied on top level, a new database will be created, which contains this resource.
  
Please have a look at our tutorial [[Integrating oXygen|How to integrate oXygen]] in BaseX.
+
=Resources=
  
===Windows 7===
+
==XML Documents==
* Open "Map network drive..." by right-clicking on "My Computer"
 
* Click on the link "Connect to a Web site that you can use to store your documents and pictures."<br/>
 
[[File:Webdav-explorer01.png]]<br/><br/>
 
* Click "Next", select "Choose a custom network location" and click "Next" again.<br/>
 
[[File:Webdav-explorer03.png]]<br/><br/>
 
* Enter the URL address of the BaseX WebDAV Server and click "Next".<br/>
 
[[File:Webdav-explorer04.png]]<br/>
 
If a message saying that the folder is not valid, this is because Microsoft WebClient is not configured to use Baseic HTTP authentication. Please check [http://support.microsoft.com/kb/928692/en this Microsoft article] in order to enable Basic HTTP authentication.<br/><br/>
 
* Enter a name for the network location and click "Next".<br/>
 
[[File:Webdav-explorer06.png]]<br/><br/>
 
* The BaseX WebDAV can be accessed from the Explorer window.<br/>
 
[[File:Webdav-explorer07.png]]<br/>
 
  
===Windows XP===
+
Uploaded files that start with an angle bracket will be stored as XML files. XML entities will be decoded during this process.
  
* In the "My Network Places" folder, double click on "Add Network Place":
+
If a file is downloaded, the characters with the following code points will be encoded as entities:
[[File:WinXP01.png]]<br/>
+
 
* Confirm the upcoming introductory dialog:
+
* 160 (non-breaking space)
[[File:WinXP02.png]]<br/>
+
* 8192–8207, 8232–8239, 8287–8303 (see [https://en.wikipedia.org/wiki/General_Punctuation General Punctuation])
* Select "Choose another network location" in the next dialog:
+
 
[[File:WinXP03.png]]<br/>
+
==Binary Files==
* Next, specify the BaseX WebDAV URL:
+
 
[[File:WinXP04.png]]<br/>
+
If XML parsing files, or if the first character of the input is no angle bracket, the file will be stored as binary resource.
* Enter the user/password combination to connect to the WebDAV service:
+
 
[[File:WinXP05.png]]<br/>
+
=Locking=
* Assign a name to your WebDAV connection:
+
 
[[File:WinXP06.png]]<br/>
+
The BaseX WebDAV implementation supports locking. It can be utilized with clients which support this feature (e.g. [[oXygen|oXygen Editor]]). [https://tools.ietf.org/html/rfc4918#section-6.2 EXCLUSIVE and SHARED] locks are supported, as well as [https://tools.ietf.org/html/rfc4918#section-7 WRITE] locks.
* Finish the wizard:
+
 
[[File:WinXP07.png]]<br/>
+
'''Note:''' WebDAV locks are stored in a database called <code>~webdav</code>. If the database is deleted, it will automatically be recreated along with the next lock operations. If a resource remains locked, it can be unlocking by removing the correspondent <code><w:lockinfo></code> entry.
* You can now see all BaseX databases in the Windows Explorer:
+
 
[[File:WinXP08.png]]<br/>
+
=WebDAV Clients=
 +
 
 +
Please check out the following tutorials to get WebDAV running on different operating systems and with oXygen:
 +
 
 +
* [[WebDAV: Windows 7|Windows 7 and up]]
 +
* [[WebDAV: Windows XP|Windows XP]]
 +
* [[WebDAV: Mac OSX|Mac OSX 10.4+]]
 +
* [[WebDAV: GNOME|GNOME and Nautilus]]
 +
* [[WebDAV: KDE|KDE]]
 +
* [[Integrating oXygen|oXygen Editor]]
 +
 
 +
=Changelog=
 +
 
 +
;Version 7.7
 +
* Added: [[#Locking|Locking]]
 +
 
 +
;Version 7.0
 +
* WebDAV API introduced

Revision as of 12:40, 2 July 2020

This page presents one of the Web Application services. It describes how to use the WebDAV file system interface.

BaseX offers access to the databases and documents using the WebDAV protocol. WebDAV provides convenient means to access and edit XML documents by representing BaseX databases and documents in the form of a file system hierarchy.

The implementation in BaseX is based on the Milton library. Currently, only Basic Authentication is supported.

Usage

By default, the BaseX HTTP server makes the WebDAV service accessible at http://localhost:8984/webdav/. If no default credentials are specified, they will be requested by the client (see further). It can be accessed by either http://<httphost>:<httpport>/webdav/ or webdav://<httphost>:<httpport>/webdav/, depending on your WebDAV client.

Please note that the file size of XML documents will be displayed as 0 bytes, as the actual file size can only be determined if the full document is being returned and serialized. This may cause problems with some WebDAV clients (e.g. NetDrive or WebDrive).

Authorization

The WebDAV service uses the database user credentials in order to perform authentication and authorization. Initial user name and password are both set to admin. If database user and password are explicitly specified when starting the BaseX HTTP Server using the corresponding startup options, WebDAV will not request additional user authentication from the client.

Root Directory

In the WebDAV root directory, all existing databases are listed. As new resources can only be stored inside a database, it is not possible to store files in the root directory. If a file is copied on top level, a new database will be created, which contains this resource.

Resources

XML Documents

Uploaded files that start with an angle bracket will be stored as XML files. XML entities will be decoded during this process.

If a file is downloaded, the characters with the following code points will be encoded as entities:

Binary Files

If XML parsing files, or if the first character of the input is no angle bracket, the file will be stored as binary resource.

Locking

The BaseX WebDAV implementation supports locking. It can be utilized with clients which support this feature (e.g. oXygen Editor). EXCLUSIVE and SHARED locks are supported, as well as WRITE locks.

Note: WebDAV locks are stored in a database called ~webdav. If the database is deleted, it will automatically be recreated along with the next lock operations. If a resource remains locked, it can be unlocking by removing the correspondent <w:lockinfo> entry.

WebDAV Clients

Please check out the following tutorials to get WebDAV running on different operating systems and with oXygen:

Changelog

Version 7.7
Version 7.0
  • WebDAV API introduced