Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
* [[RESTXQ]] allows you to write web applications with XQuery,* [[REST]] offers a RESTful API for accessing database resources via URLs, and* [[WebDAV]] provides access to databases via the file system.=Startup=
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 HTTP Server (Start)''' icon. The services can be deployed as follows:
* as standalone application by running the Various [[StartupCommand-Line_Options#HTTP Server|BaseX HTTP Servercommand-line options]],* as web servlet in a are available to simplify batch processing. The [[#Servlet ContainerStart_Scripts|Servlet Container]], and* as web servlet, using [[#Maven|Mavenstart script]]can be adjusted for individual purposes (e.g. if the default memory limit is too restrictive).<br/><br/>
=Servlet Container=An instance of the [https://www.eclipse.org/jetty/ Jetty Web Server] will be started, which by default listens to the port {{Code|8984}}. Additionally, the BaseX [[Database Server]] will be started, accessible on port {{Code|1984}}. The command-line output will look something like that (the JSP warning message [https://stackoverflow.com/questions/3521654/missing-jsp-support-in-jetty-or-confusing-log-message can be ignored]):
In order to deploy <syntaxhighlight lang="xml">BaseX [HTTP Services in a servlet container, you may download the WAR distribution of BaseX from the Server][http://basexmain] INFO org.eclipse.jetty.util.log - Logging initialized @375ms to org/download download site.eclipse.jetty.util.log.Slf4jLog[main] or compile it via <code>mvn compile warINFO org.eclipse.jetty.server.Server - jetty-9.4.21.v20190926; built:war</code> in the <code>basex2019-09-api</code> package26T16:41:09. The WAR file can then be deployed following the instructions of the corresponding servlet container (154Z; git: 72970db61a2904371e1218a95a3bef5d79788c33; jvm 13+33[http://wwwmain] INFO org.eclipse.org/jetty.webapp.StandardDescriptorProcessor - NO JSP Support for /documentation/current/quickstart-deploying-webapps, did not find org.eclipse.html jetty], [http://tomcat.apachejsp.JettyJspServlet...org/tomcat-7Server was started (port: 1984).0-doc/deployer-howtoHTTP Server was started (port: 8984).html tomcat]HTTP STOP Server was started (port: 8985).</syntaxhighlight>
Configuring portAfter startup, context path, etc. you 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. access an HTML welcome page via http://localhost:8080/BaseX711/rest)8984.
If run on a The Jetty server you may use a {{Code|jetty.xml}} file for detailed server configuration. You logging level can e.g. enable SSL connections or Jetty logging. Place be adjusted by adding the {{Code|jetty.xml}} right next following properties to the {{Code|web.xml}}. For detailed configuration refer to the [httpstart script://wiki.eclipse.org/Jetty/Reference/jetty.xml Jetty Documentation]. A sample [https://github.com/BaseXdb/basex/blob/master/basex-api/src/main/webapp/WEB-INF/jetty.xml jetty.xml] is placed in the basex-api package.
To run on [http://tomcat<syntaxhighlight lang="xml">-Dorg.eclipse.jetty.util.apachelog.class=org/ Apache Tomcat], start the tomcat server and add any <code>*.wareclipse.jetty.util.log.StdErrLog -D{classref}.LEVEL=DEBUG</codesyntaxhighlight> distribution to deploy using the Tomcat web interface. By default, the interface is accessible via http://localhost:8080/manager/html/.
==Configuration==BaseX can also be deployed as web servlet in a servlet container or with Maven:
All database ==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:8984/basex/rest). If you use Jetty (which is the default HTTP server of BaseX), the server configuration is available via 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> 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 <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 specified 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.They need =Services= 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 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|WEBPATH}} option, and compression of HTTP responses can be enabled via the {{Option|GZIP}} option. Further database options can be represented 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:
|<code>[[Options#USER|USER]]</code>|{{CodeOption|adminUSER}}| Applies to REST and WebDAV service: 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.|-|<code>[[Options#USER|PASSWORD]]</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:
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, specific credentials are set 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> <init-param> <param-name>org.basex.password</param-name> <param-value>(:87!7X3$o3p</param-value> </init-param> </servlet></pre>=Authentication==
==Available Services==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:
To enable or disable one of the provided services, the corresponding <syntaxhighlight lang="xml"><servlet entry in the {{Code|web> <servlet-name>REST</servlet-name> <servlet-class>org.xml}} file needs to be removedbasex.http.rest.RESTServlet</commentedservlet-class> <init-param> <param-name>org.basex. The default URL paths are listed in the following table:user</param-name> <param-value>rest-user</param-value> </init-param></servlet></syntaxhighlight>
{| class="wikitable" |If the HTTP server is started with no pre- valign="top"! Service! URL! Usage|- valign="top"| Default web server| {{Code|http://defined user, the credentials must be passed on by the client via [host]https:[port]/[servlet_context_path]/static}}| Access your standard web files (een.gwikipedia. HTML, JavaScript or CSS).|- valign="top"| [[RESTXQ]]| {{Code|http:org/wiki/[hostBasic_access_authentication Basic Authentication]:or [port]/[servlet_context_path]}}| Create XQuery web services and applications.|- valign="top"| [[REST]]| {{Code|httphttps://[host]:[port]/[servlet_context_path]/rest}}| Access XML database and its resourcesen.wikipedia.|- valign="top"| [[WebDAV]]| {{Code|http://[host]:[port]/[servlet_context_path]org/webdav}} or<brwiki/>{{Code|webdav://[hostDigest_authentication Digest Authentication]:[port]/[servlet_context_path]/webdav}} (depending on clientthe server setting)| Access databases via the filesystem.|}
=Maven=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:
Checkout the BaseX sources via [[Developing with Eclipse|Eclipse]] or [[Git]]. Execute : <code>mvn install</code> in the <code>basex-core</code> project folder and then <code>mvn install jettyhttp:run</code> in the <code>basex-api</code> 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 <code>[httpsadmin://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 [httpadmin@localhost:8984//docs.codehaus.org/display/JETTY/Maven+Jetty+Plugin Maven Jetty Plugin] sesion in the {{Code|pom.xml}} file. =User Management= By default, the REST and WebDAV services require client-side authentication.Default credentials can be stored server-side in the <code>web.xml</code> file or specified via[[Command-Line Options#BaseX HTTP Server|command-line arguments]].If the HTTP server is started with no pre-defined credentials, users and passwords can be sent via[http://en.wikipedia.org/wiki/Basic_access_authentication HTTP Basic Authentication] or[http://en.wikipedia.org/wiki/Digest_authentication Digest Authentication].
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 <code>USER:PASSWORD@URL</code>. An example:=Changelog=
=Changelog=;Version 8.6* Updated: Authentication readded to RESTXQ.* Updated: No password must be specified in the <code>web.xml</code> file anymore.* Updated: Server-side user and authentication method is now enforced (cannot be overwritten by client).
→Maven
This page is part of the [[Getting Started]] Section. It describes how BaseX can be used as [[Web Application]]to both provide simple APIs and build complex web applications. The following three HTTP services are available:
{| class="wikitable"
! Description
|-
|{{Code|admin}}
| Applies to REST and WebDAV service: If no password a user is specified, it no credentials must be passed on by the client. Please check by yourself if it is safe to store your credentials in plain text.
|-
|<code>[[Options#HTTPLOCAL{{Option|HTTPLOCAL]]</code>}}
|{{Code|false}}
|Operation mode. By default, a database server instance will be started, as soon as the first HTTP service is called. The database server can be disabled by setting this flag to {{Code|true}}.
|-
|<code>[[Options#RESTXQPATH{{Option|RESTXQPATH]]</code>}}
|{{Code|.}}
|Relative or absolute directory referencing the [[RESTXQ]] modules. By default, the option points to the standard web application directory.
|-
|<code>[[Options#RESTPATH{{Option|RESTPATH]]</code>}}
|{{Code|.}}
|Relative or absolute directory referencing queries and command-scripts that can be invoked via the [[REST#GET_Requests|run operation]] of REST. By default, the option points to the standard web application directory.
|-
|<code>[[Options#AUTHMETHOD{{Option|AUTHMETHOD]]</code>}}
|{{Code|Basic}}
|The default authentication method proposed by the server. The available methods are {{Code|Basic}} and {{Code|Digest}}.
|}
<pre classsyntaxhighlight lang="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></presyntaxhighlight>
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 basex-api package.
Users are specified in a {{Code|users.xml}} file, which is stored in the database directory (see [[User Management]] for more information).
;Version 9.0* Updated: <code>http://admin:admin@localhost:8984/jetty.xml</code>configuration file (required for Jetty 9).
;Version 8.0
