Web Application

This page is part of the Getting Started Section. It describes how BaseX can be used to both provide simple APIs and build complex web applications.

=Startup=


 * Run one of the basexhttp or basexhttp.bat scripts. Call the script with the stop keyword to gracefully shut down the server.
 * If you have installed BaseX on Windows, click on the BaseX HTTP Server (Start) icon.

Various command-line options are available to simplify batch processing. The start script can be adjusted for individual purposes (e.g. if the default memory limit is too restrictive).

An instance of the Jetty Web Server will be started, which by default listens to the port 8984. Additionally, the BaseX Database Server will be started, accessible on port 1984. The command-line output will look something like that (the JSP warning message can be ignored):

 BaseX [HTTP Server] [main] INFO org.eclipse.jetty.util.log - Logging initialized @375ms to org.eclipse.jetty.util.log.Slf4jLog [main] INFO org.eclipse.jetty.server.Server - jetty-9.4.21.v20190926; built: 2019-09-26T16:41:09.154Z; git: 72970db61a2904371e1218a95a3bef5d79788c33; jvm 13+33 [main] INFO org.eclipse.jetty.webapp.StandardDescriptorProcessor - NO JSP Support for /, did not find org.eclipse.jetty.jsp.JettyJspServlet ... Server was started (port: 1984). HTTP Server was started (port: 8984). HTTP STOP Server was started (port: 8985).

After startup, you can access an HTML welcome page via http://localhost:8984.

The Jetty logging level can be adjusted by adding the following properties to the start script:

 -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.StdErrLog -D{classref}.LEVEL=DEBUG

BaseX can also be deployed as web servlet in a servlet container or with Maven:

Servlet Container
In order to deploy BaseX HTTP Services in a servlet container, you can download the WAR distribution of BaseX from the download site, or compile it by calling  in the   directory. The WAR file can then be deployed following the instructions of the corresponding servlet container (jetty, tomcat, etc.).

You can configure the port, context path, etc. by following the instructions of the corresponding 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:8984/basex/rest).

If you use Jetty (which is the default HTTP server of BaseX), the server configuration is available via the jetty.xml file, which is stored in the WEB-INF directory next to the web.xml. For detailed configuration refer to the Jetty Documentation.

To run on Apache Tomcat, start the Tomcat server and add any  distribution to deploy via the Tomcat web interface. By default, the interface is accessible via http://localhost:8080/manager/html/.

Maven
Check out the BaseX sources via Eclipse or Git. Execute  in the main project directory and then   in the   sub-directory. This will start a Jetty instance in which the servlets will be deployed.

The same options as in the case of deployment apply in a servlet container. In this case, however, there is no WAR archive. Instead, Jetty looks up all files in the directory. 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.

=Services=

The following services are available and enabled by default:

The DBA is a web-based database administration interface written in RESTXQ. It allows you to create and administrate databases, evaluate queries in realtime, view log files, manage users, etc. It is embedded in the full distributions of BaseX, and it can be accessed after startup via http://localhost:8984/dba/.

=Configuration=

Unless BaseX is deployed as servlet, the location of the web application directory can be adjusted via the option, and compression of HTTP responses can be enabled via the  option.

Further database options can be defined as context parameters in the web.xml file. The most important options for the web application context are:

All options are prefixed with org.basex.. Local file paths in options may be absolute or relative. If a relative path is specified, its root will be the servlet’s (webapp) path:

  org.basex.dbpath WEB-INF/data   org.basex.repopath f:/basex/repository 

Context parameters can be requested from XQuery via proc:property-names and proc:property. How to set these options is specific to the servlet container. For example, in Jetty it can be 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.

To enable or disable a specific service, the corresponding servlet entry in the web.xml file needs to be removed/commented.

Authentication
Different credentials can be assigned to a service by specifying local init parameters. In the following example, an alternative user is specified for the REST service:

 <servlet-name>REST</servlet-name> <servlet-class>org.basex.http.rest.RESTServlet</servlet-class> <init-param> org.basex.user</param-name> rest-user</param-value> </init-param>

If the HTTP server is started with no pre-defined user, the credentials must be passed on by the client via Basic Authentication or Digest Authentication (depending on the server setting).

With cURL, internet browsers, and other tools, you can specify basic authentication credentials within the request string as plain text, using the format. An example:



Users are specified in a users.xml file, which is stored in the database directory (see User Management for more information).

=Changelog=


 * Version 9.0
 * Updated:  configuration file (required for Jetty 9).


 * Version 8.6
 * Updated: Authentication readded to RESTXQ.
 * Updated: No password must be specified in the  file anymore.
 * Updated: Server-side user and authentication method is now enforced (cannot be overwritten by client).


 * Version 8.0
 * Added: digest authentication
 * Updated: user management
 * Updated: default user/password disabled in web.xml


 * Version 7.7
 * Added: service-specific permissions


 * 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