Configuration

Application Properties

jmix.webdav.applications

Maps document formats to external applications that should open these documents. For each application you can configure a set of file extensions in the "extensions" property.

For example, the following mapping makes the system to open PPT and PPTX files with Microsoft PowerPoint:

"ms-powerpoint":{\
  "name":"Microsoft PowerPoint",\
  "protocols":{"writable":"ms-powerpoint:ofe%7Cu%7C","read_only":"ms-powerpoint:ofv%7Cu%7C"},\
  "extensions":["ppt","pptx"]\
  }

Default value:

{"ms-word":{"name":"Microsoft Word","protocols":{"writable":"ms-word:ofe%7Cu%7C",\
  "read_only":"ms-word:ofv%7Cu%7C"},"extensions":["docx","doc","rtf"]},\
  "ms-excel":{"name":"Microsoft Excel","protocols":{"writable":"ms-excel:ofe%7Cu%7C",\
  "read_only":"ms-excel:ofv%7Cu%7C"},"extensions":["xls","xlsx"]},\
  "ms-powerpoint":{"name":"Microsoft PowerPoint",\
  "protocols":{"writable":"ms-powerpoint:ofe%7Cu%7C","read_only":"ms-powerpoint:ofv%7Cu%7C"},\
  "extensions":["ppt","pptx"]}}

Example value for LibreOffice:

jmix.webdav.applications = {"vnd.libreoffice.command":\
  {"name":"LibreOffice","protocols":\
  {"writable":"vnd.libreoffice.command:ofe|u|",\
  "read_only":"vnd.libreoffice.command:ofv|u|"},\
  "extensions":["odt", "ods", "odp", "doc", "docx", "xls", "xlsx", "ppt", "pptx"]}}

jmix.webdav.authentication-method

Defines the authentication type.

Default value: basic.

Although it is not recommended, you can set digest in this property and avoid setting up HTTPS on the server. In this case, do not forget to change the jmix.webdav.url-prefix property for generating links with correct server protocol and port. Also note that all users must have hashed passwords stored separately in the database. The add-on updates these passwords when you change the password for a user, so you have to do it for each user after setting up the digest authentication.

jmix.webdav.auto-generate-unique-resource-uri

If this property is set to false and a newly uploaded document has the URI already assigned to another document, the unique constraint violation occurs.

If this property is set to true and the URI is already assigned to some document, then the new path will be automatically generated with the {id}.extension format.

Default value: true.

jmix.webdav.document-versions-cleaning-cron

This property allows you to change the schedule of WebdavDocumentVersionsCleaningJob as cron expression if necessary.

The default value is 0 0 0 1 * ? * (once a month).

jmix.webdav.expired-lock-cleaning-cron

This property allows you to change the schedule of ExpiredLockCleaningJob as cron expression if necessary.

The default value is 0 0 0/2 ? * * (every two hours).

jmix.webdav.file-storage

Defines a file storage used for storing WebDAV files.

By default, a file storage returned by FileStorageLocator.getDefault() is used.

jmix.webdav.lock-timeout

Defines the default interval in milliseconds for a document locking.

Default value: 600000.

jmix.webdav.use-default-document-versions-cleaner-quartz-configuration

This property allows you to disable the default configuration that creates and schedules the WebdavDocumentVersionsCleaningJob job.

Default value: true.

jmix.webdav.use-default-expired-lock-cleaner-quartz-configuration

This property allows you to disable the default configuration that creates and schedules the ExpiredLockCleaningJob job.

Default value: true.

jmix.webdav.url-prefix

Defines the prefix for WebDAV document link.

Default value: https://localhost:8443/webdav.

It must match the root URL of the application with the additional /webdav path.

jmix.webdav.versioning-enabled

Enables versioning for all attributes of the WebdavDocument type without @WebdavSupport annotation.

Default value: true.

Configuring HTTPS

HTTPS on the server is required to authenticate desktop applications. Below are simple instructions for setting up HTTPS in your development environment.

The use of a self-signed certificate is appropriate only for testing. Always use SSL certificates issued by a trusted authority for running production applications.

Creating a Keystore File

  1. Generate a keystore using the keytool utility provided by JDK:

    keytool -genkey -keyalg RSA -alias localhost -keystore localhost.jks -validity 365 -keysize 2048

    You will be asked for the keystore password and then for some names. Remember the password and the names.

  2. Export certificate from the keystore:

    keytool -export -keystore localhost.jks -storepass <password> -alias localhost -file localhost.cer

    Use the password entered on the first step instead of <password>.

  3. Register the certificate as trusted in your operating system.

    • On macOS:

      • Double-click on localhost.cer file in Finder. The Keychain Access application will open.

      • Find your certificate under the name entered on the first step as "your first and last name" on the Certficates tab.

      • Double-click the certificate and select Trust → When using this certificate: Always Trust.

Generate trusted certificate

Some use cases like opening WebDAV files in recent LibreOffice and Firefox versions may not work with self-signed certificates. Trusted certificates can be obtained from SSL-providers or generated with certbot. But for the development purposes you can issue your own root certificate and sign development server’s certificate with it. To simplify this task we recommend to use mkcert generation/maintenance tool. You can skip this section in case you are ok with HTTPS warnings and restrictions.

  1. Install mkcert from the following repo: https://github.com/FiloSottile/mkcert. You can build it either from source (requires golang to be installed) and copy binary to /usr/local/bin or use binaries provided by vendor.

  2. Once having mkcert in path you can generate and install root certificate:

    mkcert -install

  3. Navigate to keystore directory and create signed certificates for your development server:

    mkcert -pkcs12 localhost 127.0.0.1 ::1

  4. Create .jks keystore file with certificates for your project:

    keytool -importkeystore -srckeystore localhost+2.p12 -srcstoretype pkcs12 -destkeystore localhost.jks

Configuring Server

This section explains how to use the certificate generated in the previous section in your application when it runs from the IDE or as an executable JAR.

  1. Create src/main/resources/<base-package>/keystore directory and copy localhost.jks into it.

  2. Set the following properties in the application.properties file replacing <base-package> and <password> with actual values:

    # Enables HTTPS
server.ssl.enabled=true
# The format used for the keystore
server.ssl.key-store-type = JKS
# The path to the keystore containing the certificate
server.ssl.key-store = classpath:<base-package>/keystore/localhost.jks
# The password used to generate the keystore
server.ssl.key-store-password = <password>
# The alias mapped to the certificate
server.ssl.key-alias = localhost

# Changes the server's port
server.port = 8443

Maintenance Tasks

The WebDAV add-on contains a few maintenance tasks described below. To execute them regularly, include the Quartz add-on in your project as described in the Quartz / Installation section.

ExpiredLockCleaningJob

Removes expired lock objects. This job runs every two hours by default.

To change the job schedule, use the jmix.webdav.expired-lock-cleaning-cron property.

WebdavDocumentVersionsCleaningJob

Removes WebdavDocumentVersion instances, which do not have links to documents. This job runs once in a month by default.

To change the job schedule, use the jmix.webdav.document-versions-cleaning-cron property.