Changes

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. The following services are provided:

This article describes different ways * Run one of deploying and configuring these servicesthe {{Code|basexhttp}} or {{Code|basexhttp. bat}} scripts. Call the script with the {{Code|stop}} keyword to gracefully shut down the server.* If you have installed BaseX on ''Windows'', click on the '''BaseX can be deployed as follows:HTTP Server (Start)''' icon.

* as standalone application, by running the Both an instance of [https://www.eclipse.org/jetty/ Jetty] and BaseX [[Startup#HTTP Server|BaseX HTTP Database Server]]will be started. By default,* as web servlet in a [[#Servlet Container|Servlet Container]]Jetty listens to the port 8080, and* as web servlet, using the [[#MavenDatabase Server|MavenBaseX Database Server]]is accessible on port 1984. After startup, you can access a plain HTML welcome page via http://localhost:8080.

AuthenticationUnless you have already chosen an admin password yet (e.g., via the Windows installer or a previous installation), you can do so by invoking the {{Command|PASSWORD}} command on your terminal:

* If a user is defined in the <codepre>webbasexhttp -c PASSWORDBaseX [HTTP Server]...[main] INFO org.eclipse.jetty.util.log - Logging initialized @239ms to org.eclipse.jetty.util.log.Slf4jLog...HTTP STOP Server was started (port: 8081).HTTP Server was started (port: 8080).xmlPassword: _</codepre> file via  The Jetty logging level can be adjusted by adding the following properties to the key start script: <codepre lang="xml">-Dorg.eclipse.jetty.util.log.class=org.basexeclipse.jetty.util.log.StdErrLog -D{classref}.userLEVEL=DEBUG</codepre>, no password must  Various [[Command-Line_Options#HTTP Server|command-line options]] are available to simplify batch processing. The [[Start_Scripts|start script]] can be specifiedadjusted for individual purposes (e.g. if the default memory limit is too restrictive).* If 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 [https://basex.org/download download site], or compile it by calling <code>adminmvn compile war:war</code> user is specified for an APIin 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], all features will be available without restrictionetc.).* Predefined authentication methods and default users cannot be overwritten 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 clientdefault URL path (e.g. http://localhost:8080/rest) with a custom one (e.g. http://localhost:8080/basex/rest).

In order to deploy BaseX HTTP Services in a servlet container, you can download the WAR distribution of BaseX from the To run on [httphttps://basextomcat.apache.org/download download siteApache Tomcat], or compile it by calling start the Tomcat server and add any <code>mvn compile war:*.war</code> in distribution to deploy via the <code>basex-api</code> directoryTomcat web interface. The WAR file can then be deployed following By default, the instructions of the corresponding servlet container ([interface is accessible via http://www.eclipse.orglocalhost:8080/jettymanager/documentation/current/quickstart-deploying-webapps.html jetty], [http://tomcat.apache.org/tomcat-7.0-doc/deployer-howto.html tomcat], etc.).

If you use Jetty (which is Check out the default HTTP server of BaseX), the server configuration is available sources via the {{Code[[Developing with Eclipse|jettyEclipse]] or [[Git]].xml}} file, which is stored Execute <code>mvn install</code> in the {{Code|WEB-INF}} main project directory next to the {{Code|web.xml}}. For detailed configuration refer to the [httpand then <code>mvn install jetty:run</code> in the <code>basex-api</www.eclipse.org/jetty/documentation/current/jetty-xml-configcode> subdirectory.html This will start a Jetty Documentation]instance in which the servlets will be deployed.

To run on [http://tomcatThe same options as in the case of deployment apply in a servlet container.apacheIn this case, however, there is no WAR archive.org/ Apache Tomcat]Instead, start Jetty looks up all files in the Tomcat server and add any directory <code>*[https://github.warcom/BaseXdb/basex/tree/master/basex-api/src/main/webapp basex-api/src/main/webapp]</code> distribution to deploy via . Jetty and servlet options can be configured in the Tomcat {{Code|jetty.xml}} and {{Code|web interface. By default, xml}} files as described above in the [[#Configuration|Servlet Container Configuration]]. The Jetty stop port can be changed in the interface is accessible via http[https://localhost:8080www.eclipse.org/jetty/documentation/managercurrent/jetty-maven-plugin.html/Maven Jetty Plugin] sesion in the {{Code|pom.xml}} file.

==Configuration=Services=

All The following services are available and enabled by default: {| class="wikitable"|- valign="top"! Name! Standard Path! Description|- valign="top"| [[RESTXQ]]| <code>/</code>| Write enriched APIs and full web applications with XQuery.|- valign="top"| [[WebSockets]]| <code>ws/</code>| Bidirectional client/server communication.|- valign="top"| [[REST]]| <code>rest/</code>| Straightforward access to XML databases and its resources.|- valign="top"| [[WebDAV]]| <code>webdav/</code>| Database access via the file system.|- valign="top"| Default| <code>static/</code>| Access to static server resources (HTML, JavaScript, CSS, images, …).|} The [[DBA]] is a web-based database options 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= Unless BaseX is deployed as servlet, the location of the web application directory can be adjusted via the {{Option|WEBPATH}} option, and compression of HTTP responses can be specified in enabled via the {{CodeOption|web.xmlGZIP}} fileoption. They need to  Further database options can be defined as context parameters and prefixed with in the {{Code|org.basexweb.xml}}file. The most important options for the web application context are as follows:

|-valign="top"

|-valign="top"|<code>[[Options#USER{{Option|USER]]</code>}}

|-valign="top"|<code>[[Options#HTTPLOCAL{{Option|HTTPLOCAL]]</code>}}

|-valign="top"|<code>[[Options#RESTXQPATH{{Option|RESTXQPATH]]</code>}}

|-valign="top"|<code>[[Options#RESTPATH{{Option|RESTPATH]]</code>}}

|-valign="top"|<code>[[Options#AUTHMETHOD{{Option|AUTHMETHOD]]</code>}}

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

<pre classlang="brush:xml"> <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>

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 is specific to the servlet container. For example, in Jetty it can be done by [http://www.eclipse.org/jetty/documentation/current/override-web-xml.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.

Different credentials can be assigned to the REST and WebDAV To enable or disable a specific service by specifying local init parameters. In , the following example, an alternative user is specified for corresponding servlet entry in the REST service:{{Code|web.xml}} file needs to be removed/commented.

<pre class="brush: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>=Authentication==

To enable or disable one of the provided services, the corresponding servlet entry in the {{Code|web.xml}} file needs to be removed/commented. The default URL paths are listed in the following table: {| class<pre lang="wikitablexml" >|- valign="top"<servlet>! Service! URL! Usage| <servlet- valign="top"| Default web server| {{Code|http:name>REST<//[host]:[port]/[servlet_context_path]/static}}servlet-name>| Access your standard web files (e <servlet-class>org.basex.ghttp. HTML, JavaScript or CSS)rest.RESTServlet</servlet-class>| <init- valign="top"param>| [[RESTXQ]] <param-name>org.basex.user</param-name>| {{Code|http:/ <param-value>rest-user</[host]:[port]/[servlet_context_path]}}| Create XQuery web services and applications.|param- valign="top"value>| [[REST]]| {{Code|http://[host]:[port] </[servlet_context_path]/rest}}| Access XML database and its resources.|init- valign="top"param>| [[WebDAV]]</servlet>| {{Code|http://[host]:[port]/[servlet_context_path]/webdav}} or<br/pre>{{Code|webdav://[host]:[port]/[servlet_context_path]/webdav}} (depending on client)| Access databases via the filesystem.|}

Check out With cURL, internet browsers, and other tools, you can specify basic authentication credentials within the BaseX sources via [[Developing with Eclipse|Eclipse]] or [[Git]]. Execute <code>mvn install</code> in request string as plain text, using the main project directory and then format <code>mvn install jettyUSER:runPASSWORD@URL</code> in the <code>basex-api</code> sub-directory. This will start a Jetty instance in which the servlets will be deployed.:

==Configuration== 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 [http://docs.codehaus.org/display/JETTY/Maven+Jetty+Plugin Maven Jetty Plugin] sesion in the {{Code|pom.xml}} file. =User Management= By default, RESTXQ uses the admin user, whereas the REST and WebDAV services require client-side authentication.A default user can be specified via [[Command-Line Options#BaseX HTTP Server|command-line arguments]]. In the <code>web.xml</code> file, both a global and a servlet-specific user can be added (see above). If the HTTP server is started with no pre-defined user, the credentials must be passed on by the client via [http://en.wikipedia.org/wiki/Basic_access_authentication Basic Authentication] or [http://en.wikipedia.org/wiki/Digest_authentication 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 <code>USER:PASSWORD@URL</code>. An example: : <code>http://admin:admin@localhost:89848080/</code>

* Updated: `<code>jetty.xml` </code> configuration file (required for Jetty 9).

* Updated: Authentication readded re-added to RESTXQ.