Web Application

BaseX provides access to stored database resources and to the XQuery engine via REST, RESTXQ and WebDAV services. This article describes different ways of deploying and configuring these services. The services can be deployed in three different ways:

• as web servlets in a J2EE Servlet Container,
• for development purposes, using Maven, and
• as standalone application by running the BaseX HTTP Server.
  
  

Servlet Container

In order to deploy BaseX HTTP Services in a servlet container, you may download the WAR distribution of BaseX from the download site. The WAR file can then be deployed following the instructions of the corresponding servlet container (jetty, tomcat).

Configuring port, context path, etc. can be done by following the corresponding instructions of the used servlet container. This is needed if you want to replace the default URL path (e.g. http://localhost:8080/rest) with a custom one (e.g. http://localhost:8080/BaseX711/rest).

If run on a Jetty server you may use a jetty.xml file for detailed server configuration. You can e.g. enable SSL connections or Jetty logging. Place the jetty.xml right next to the web.xml. For detailed configuration refer to the Jetty Documentation. A sample jetty.xml is placed in the basex-api package.

Database Access

The following two modes exists to run the BaseX Web Application:

• Server Mode: the web application will start a database server. This server can then also be addressed from other clients outside the web application.
• Local Mode: the web application will communicate with a local database context.

By default, web applications use the Server Mode. The operation mode can be configured as explained below.

Configuration

All database options can be specified in the web.xml file by prefixing the key with org.basex.. The most important options for the web application context are as follows:

Option	Default	Description
USER	admin	User name. By default, the admin user is specified. If no user is specified, the credentials must be passed on by the client. Please check by yourself if it is safe to store your credentials in plain text.
PASSWORD	admin	Login data. By default, the admin password is specified. If no password is specified, it must be passed on by the client. Please check by yourself if it is safe to store your credentials in plain text.
HTTPLOCAL	false	Version 7.5: Operation mode. By default, the servlets will work in client/server mode, and a database server instance will be started along with the web server. If set to false, all servlets will communicate with a local database context which is not accessible from outside.
RESTXQPATH	.	Version 7.5: RESTXQ directory. By default, all RESTXQ modules are located in the standard web application directory.

Path options may contain an absolute or relative path. If a relative path is specified, its root will be the servlet (webapp) path:

 
  <context-param>
    <param-name>org.basex.dbpath</param-name>
    <!-- will be rewritten to ..../webapp/WEB-INF/data -->
    <param-value>WEB-INF/data</param-value>
  </context-param>
  <context-param>
    <param-name>org.basex.repopath</param-name>
    <!-- will be kept as is -->
    <param-value>f:/basex/repository</param-value>
  </context-param>

How to set these options in the web.xml of the BaseX web application is specific to the servlet container. For example, in Jetty it is done by overriding the web.xml file. Another option is to directly edit the WEB-INF/web.xml file in the WAR archive (WAR files are simple ZIP files). Refer to the sample web.xml of the basex-api package.

Available Services

To enable or disable one of the provided services, the corresponding servlet entry in the web.xml file needs to be removed/commented. The default URL paths are listed in the following table:

Service	URL	Usage
REST	http://[host]:[port]/[servlet_context_path]/rest	Access XML database and its resources; see REST.
RESTXQ	http://[host]:[port]/[servlet_context_path]/restxq	Create XQuery web services and applications; see RESTXQ.
WebDAV	http://[host]:[port]/[servlet_context_path]/webdav or webdav://[host]:[port]/[servlet_context_path]/webdav (depending on client)	Access databases via the filesystem; see WebDAV.
Web Server	http://[host]:[port]/[servlet_context_path]	Access your standard web files (e.g. HTML, JavaScript or CSS).

Maven

Checkout the sources of basex and basex-api via Maven or Eclipse. Execute mvn install in the basex project folder and then mvn install jetty:run in the basex-api project folder. This will start a Jetty instance in which the servlets will be deployed.

Configuration

The same options as in the case of deployment in a servlet container apply. In this case, however, there is no WAR archive. Instead, Jetty looks up all files in the directory basex-api/src/main/webapp. Jetty and servlet options can be configured in the jetty.xml and web.xml files as described above in the Servlet Container Configuration. The Jetty stop port can be changed in the Maven Jetty Plugin sesion in the pom.xml file.

User Management

If the HTTP server is started with no pre-defined credentials, users and passwords can be sent via HTTP basic authentication with each HTTP request. Login data can be stored server-side in the web.xml file, or specified as command-line arguments.

For multi-user access place a .basexperm in the server root. Refer to User_Management article.

With cURL, and most browsers, you can specify the user name and password with each HTTP request within the request string as plain text, using the format USER:PASSWORD@URL. An example:

http://admin:admin@localhost:8984/

Changelog

Version 7.5

• Added: jetty.xml: configuration for Jetty Server
• Updated: server replaced with httplocal mode

Version 7.3

• Updated: client mode replaced with server mode

Version 7.2

• Web Application concept revised