Changes

BaseX provides access to stored database resources and to This page is part of the XQuery engine via [[REST]], [[RESTXQGetting Started]] and [[WebDAV]] servicesSection. This article It describes different ways of deploying and configuring these services. The services how BaseX can be deployed in 3 different ways:* as used to both provide simple APIs and build complex web servlets in a J2EE servlet container,* for development purposes, using maven, and* as a standalone applicationapplications.<br/><br/>

=Servlet ContainerStartup=

In order to deploy BaseX HTTP Services in a servlet container, you need to download the WAR distribution * Run one of BaseX from the [http://basex{{Code|basexhttp}} or {{Code|basexhttp.org/download download site]bat}} scripts. The WAR file can then be deployed following Call the script with the instructions of {{Code|stop}} keyword to gracefully shut down the corresponding servlet container ([http://docsserver.codehaus.org/display/JETTY/WebAppDeployer jetty]* If you have installed BaseX on ''Windows'', [http://tomcat.apache.org/tomcat-6.0-doc/deployer-howto.html tomcat]click on the '''BaseX HTTP Server (Start)''' icon.

Configuring port, context path, etc. can be done following the corresponding instructions of the used servlet container. This is needed if Unless you want to replace the default URL path have already chosen an admin password yet (e.g. http://localhost:8080/rest, via the Windows installer or a previous installation) with a custom one (e.g. http://localhost, you can do so by invoking the {{Command|PASSWORD}} command on your terminal:8080/BaseX711/rest).

There are two modes in which the BaseX web application The Jetty logging level can access databases (note that, with {{Version|7.3}}, be adjusted by adding the '''client mode''' has been replaced with following properties to the '''server mode''')start script:* '''local mode''': the web application will communicate with a local database context.* '''server mode''': after the first call of one of the provided HTTP services, the web application will start a [[Startup#BaseX_Server|database server]]. This server can then also be addressed from other clients outside the web application.

The operation mode can be configured as explained further below<pre lang="xml">-Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.StdErrLog -D{classref}.LEVEL=DEBUG</pre>

'''Note:''' if the web application stores data in the local file system of the servlet container, then by default it will use a separate directory as home directory. This is because, in many production environments, the servlet container runs as a dedicated user without a {{CodeVarious [[Command-Line_Options#HTTP Server|$HOME}} directory. However BaseX needs command-line options]] are available to store somewhere it's settings and datasimplify batch processing. This is why, even when running a servlet container with a normal user The [[Start_Scripts|start script]] can be adjusted for individual purposes (ie.eg. one which has a {{Code|$HOME}} directory), the web application will not use by if the default the settings stored in {{Code|$HOME/.basex}} and will have a different set (or empty setmemory limit is too restrictive) of databases than the one in the case of the standalone HTTP server. However, this behavior can be changed by manually setting the BaseX home directory to {{Code|$HOME}}, in which case the web application will use the same databases as in the case of the standalone server.

==Available Services==To enable or disable one of the provided services, the corresponding BaseX can also be deployed as web servlet entry in the {{Code|web.xml}} file needs to be removed/commented. The default URL paths are listed in the following tablea 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 [https://basex.org/download download site], or compile it by calling <code>mvn compile war:war</code> in the <code>basex-api</code> directory. The WAR file can then be deployed following the instructions of the corresponding servlet container ([https://www.eclipse.org/jetty/documentation/current/quickstart-deploying-webapps.html Jetty], [https://tomcat.apache.org/tomcat-9.0-doc/deployer-howto.html 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:8080/basex/rest). If you use Jetty (which is the default HTTP server of BaseX), the server configuration is defined in the {{Code|jetty.xml}} file, which is stored in the {{Code|WEB-INF}} directory next to the {{Code|web.xml}}. For detailed configuration, refer to the [https://www.eclipse.org/jetty/documentation/current/jetty-xml-config.html Jetty Documentation]. To run on [https://tomcat.apache.org/ Apache Tomcat], start the Tomcat server and add any <code>*.war</code> 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 [[Developing with Eclipse|Eclipse]] or [[Git]]. Execute <code>mvn install</code> in the main project directory and then <code>mvn install jetty:run</code> in the <code>basex-api</code> subdirectory. 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 <code>[https://github.com/BaseXdb/basex/tree/master/basex-api/src/main/webapp basex-api/src/main/webapp]</code>. Jetty and servlet options can be configured in the {{Code|jetty.xml}} and {{Code|web.xml}} files as described above in the [[#Configuration|Servlet Container Configuration]]. The Jetty stop port can be changed in the [https://www.eclipse.org/jetty/documentation/current/jetty-maven-plugin.html Maven Jetty Plugin] sesion in the {{Code|pom.xml}} file. =Services= The following services are available and enabled by default: {| class="wikitable" |- valign="top"! Name! Standard Path! Description

| REST| {{Code|http://[host[WebSockets]:[port]| <code>ws/[servlet_context_path]</rest}}code>| access XML database and its resources, see [[REST]]Bidirectional client/server communication.

| RESTXQ|{{Code|http://[host[REST]:[port]| <code>rest/[servlet_context_path]</restxq}}code>| create XQuery Web Services, see [[RESTXQ]]Straightforward access to XML databases and its resources.

| WebDAV| {{Code|http://[host]:[portWebDAV]/[servlet_context_path]/webdav}} or| <br/code>{{Code|webdav:/</[host]:[port]/[servlet_context_path]/webdav}} (depending on client)code>| Database access databases via the filesystem, see [[WebDAV]]file system.

| Web ServerDefault| {{Code|http:<code>static/</[host]:[port]/[servlet_context_path]}}code>| access your standard web files Access to static server resources (e.g. HTML, JavaScript or , CSS, images, …).

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:8080/dba/. =Configuration=Configuring Database Access==The following options are available to configure Unless BaseX is deployed as servlet, the location of the web application directory can be adjusted via the way {{Option|WEBPATH}} option, and compression of HTTP responses can be enabled via the databases are accessed{{Option|GZIP}} option. These  Further database options can be set defined as context parameters in the {{Code|web.xml}} file or as Java system variables (e.g. using <code>-Dorg.basex.mode=local</code> from The most important options for the command line).web application context are: 

|-valign="top"! width='70' "160" | Option! width="90" |Default

|-valign="top"|{{Option|USER}}| {{Code|orgadmin}}| If a user is specified, no credentials must be passed on by the client.basex.mode|- valign="top"|{{Option|HTTPLOCAL}}| {{Code|localfalse}}| Operation mode. By default, a database server instance will be started, as soon as the servlets will work with a local first HTTP service is called. The database context server can be disabled by setting this flag to {{Code|orgtrue}}.basex.path|- valign="top"|{{Option|RESTXQPATH}}. With |{{VersionCode|7.3}}|Relative or absolute directory referencing the [[RESTXQ]] modules. By default, the option points to the standard web application directory.|- valign="top"|{{CodeOption|clientRESTPATH}} mode has been replaced with a new |{{Code|server.}} mode, which is equivalent to the default mode of |Relative or absolute directory referencing queries and command-scripts that can be invoked via the [[REST#Standalone ApplicationGET_Requests|Standalone Applicationrun operation]]: a BaseX database server instance will be started with the first call of a serviceREST. By default, which is then available for other clients, toothe option points to the standard web application directory.|-valign="top"| {{CodeOption|org.basex.userAUTHMETHOD}}<br/>|{{Code|org.basex.passwordBasic}}| -| Login data. By The default, no user and password is specified, and the credentials must be passed on authentication method proposed by the clientserver. Please check by yourself if it is safe to store your credentials in the The available methods are {{Code|web.xmlBasic}} file. The default user credentials can be found under [[Startup#BaseX_Clientand {{Code|Startup: BaseX Client]]Digest}}.

Additionally, all database main All options, which are usually stored in the {{Code|.basex}} configuration file ({{Code|DBPATH}}, {{Code|HTTPPATH}}, etc.), can be specified as well by prefixing the key prefixed with {{Code|org.basex.}}. Local file paths in options may be absolute or relative. If an option references a relative pathis specified, it its root will be prefixed with the servlet root servlet’s ({{Code|webapp}}) path. Some examples follow: <pre classlang="brush:xml"> <context-param> <param-name>org.basex.dbpath</param-name> <param-value>data</param-value> </context-param> <context!-param> <param-name>orgwill be rewritten to ...basex.httppath</paramwebapp/WEB-INF/data --name> <param-value>httpWEB-INF/data</param-value> </context-param> <context-param> <param-name>org.basex.repopath</param-name> <param!--value>repo</paramwill be kept as is -value> </context-param> <context-param> <param-namevalue>org.f:/basex.lang</param-name> <param-value>Englishrepository</param-value> </context-param>

Context parameters can be requested from XQuery via [[Process_Module#proc:property-names|proc:property-names]] and [[Process_Module#proc:property|proc:property]]. How to set these options in the {{Code|web.xml}} of the BaseX web application is specific to the servlet container. For example, in Jetty it is can be done using by [http://docswww.codehauseclipse.org/displayjetty/JETTYdocumentation/current/override+-web-xml.xml an html overriding the web.xml]file. Another option is to directly edit the {{Code|WEB-INF/web.xml}} file in the WAR archive (WAR files are simple ZIP files).Refer to the sample [https://github.com/BaseXdb/basex/blob/master/basex-api/src/main/webapp/WEB-INF/web.xml web.xml] of the {{Code|basex-api}} package. To enable or disable a specific service, the corresponding servlet entry in the {{Code|web.xml}} file needs to be removed/commented. ==Authentication== No credentials need to be supplied if a default user is assigned to a service in the {{Code|web.xml}} file. In the following example, the user {{Code|rest-user}} is specified for the REST service:

<pre lang=Maven="xml"><servlet> <servlet-name>REST</servlet-name> <servlet-class>org.basex.http.rest.RESTServlet</servlet-class> <init-param> <param-name>org.basex.user</param-name> <param-value>rest-user</param-value> </init-param></servlet></pre>

Checkout If the sources of <code>basex</code> and <code>basexHTTP server is started with no pre-api</code> as described under [defined user, the credentials must be passed on by the client via [Integrate#Check_Out|Integratehttps: Check Out]]//en.wikipedia. Execute <code>mvn install<org/code> in the <code>basex<wiki/code> project folder and then <code>mvn install jettyBasic_access_authentication Basic Authentication] or [https:run</code> in the <code>basex-api</code> project folderen.wikipedia. This will start a Jetty instance org/wiki/Digest_authentication Digest Authentication], depending on the chosen authentication method in which the servlets will be deployedconfiguration.

==Configuration==The same options as in the case of deployment in a servlet container apply. In this caseWith cURL, howeverinternet browsers, there is no WAR archive. Insteadand other tools, Jetty uses you can specify basic authentication credentials within the directory {{Code|basex-api/src/main/webapp}}. For configuring various Jetty runtime options, such request string as port, context pathplain text, etc. refer to using the [httpformat <code>USER:PASSWORD@URL<//docs.codehaus.org/display/JETTY/Maven+Jetty+Plugin Maven Jetty Plugin]. These should be entered in the {{Code|pom.xml}} file of the {{Code|basex-api}} project.code>:

Detailed description how to start and setup Users are specified in a {{Code|users.xml}} file, which is stored in the standalone BaseX HTTP server can found under database directory (see [[Startup#BaseX HTTP Server|Startup: BaseX HTTP ServerUser Management]]for more information).

 * Updated: {{Code|client}} mode replaced with {{Code|server}} mode ({{Code|org.basex.mode}})