Difference between revisions of "Web Application"

From BaseX Documentation
Jump to navigation Jump to search
 
(196 intermediate revisions by 4 users not shown)
Line 1: Line 1:
BaseX provides access to stored database resources and to the XQuery engine via [[REST]], [[RESTXQ]] and [[WebDAV]] services. This article describes different way of deploying and configuring these services. The services can be deployed in 3 different ways:
+
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.
* as a standalone application,
 
* as web servlets in a J2EE servlet container,
 
* and for development purposes, using maven.
 
  
=Standalone: BaseX HTTP Server=
+
=Startup=
Detailed description how to start and setup the standalone BaseX HTTP server can found under [[Startup#BaseX HTTP Server|Startup: BaseX HTTP Server]] and [[Startup_Options#BaseX_HTTP_Server|Startup Options: BaseX HTTP Server]].
 
  
=Servlet Container=
+
* Run one of the {{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.
  
In order to deploy BaseX HTTP Services in a servlet container, one needs to download the WAR distribution of BaseX from the [http://basex.org/products/download/all-downloads download site]. The downloaded WAR file can be then deployed following the instructions of the corresponding servlet container ([http://docs.codehaus.org/display/JETTY/WebAppDeployer jetty], [http://tomcat.apache.org/tomcat-6.0-doc/deployer-howto.html tomcat]).
+
Various [[Command-Line_Options#HTTP Server|command-line options]] are available to simplify batch processing. The [[Start_Scripts|start script]] can be adjusted for individual purposes (e.g. if the default memory limit is too restrictive).
  
==Database Access==
+
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]):
  
There are two ways in which the BaseX web application can access databases:
+
<syntaxhighlight lang="xml">
* either a dedicated [[Startup#BaseX_Server|database server]] should be manually started,
+
BaseX [HTTP Server]
* or the web application will access and store data on the local file system.
+
[main] INFO org.eclipse.jetty.util.log - Logging initialized @375ms to org.eclipse.jetty.util.log.Slf4jLog
The operation mode can be configured as explained further below.
+
[main] INFO org.eclipse.jetty.server.Server - jetty-9.4.21.v20190926; built: 2019-09-26T16:41:09.154Z; git: 72970db61a2904371e1218a95a3bef5d79788c33; jvm 13+33
<br/>
+
[main] INFO org.eclipse.jetty.webapp.StandardDescriptorProcessor - NO JSP Support for /, did not find org.eclipse.jetty.jsp.JettyJspServlet
<br/>
+
...
<b>Note:</b> when 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 {{Mono|$HOME}} directory. However BaseX needs to store somewhere it's settings and data. This is why, even when running a servlet container with a normal user (i.e. one which has a {{Mono|$HOME}} directory), the web application will not use by the default the settings stored in {{Mono|$HOME/.basex}} and will have a different set (or empty set) 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 {{Mono|$HOME}}, in which case the web application will use the same databases as in the case of the standalone server.
+
Server was started (port: 1984).
 +
HTTP Server was started (port: 8984).
 +
HTTP STOP Server was started (port: 8985).
 +
</syntaxhighlight>
  
==Servlet Container Configuration==
+
After startup, you can access an HTML welcome page via http://localhost:8984.
Configuring port, context path, etc. can be done following the corresponding instructions of the used servlet container.
 
  
==Configuring Available Services==
+
The Jetty logging level can be adjusted by adding the following properties to the start script:
To enable or disable one of the provided services, the corresponding servlet entry in the {{Mono|web.xml}} file needs to be removed/commented.
+
 
 +
<syntaxhighlight lang="xml">
 +
-Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.StdErrLog -D{classref}.LEVEL=DEBUG
 +
</syntaxhighlight>
 +
 
 +
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>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 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:
  
==Configuring Database Access==
 
The following options are available to configure the way the databases are accessed. These can be set in the {{Mono|web.xml}} file or as Java system variables (e.g. using <code>-Dorg.basex.path="/some/path"</code> from the command line).
 
 
{| class="wikitable"  
 
{| class="wikitable"  
 
|- valign="top"
 
|- valign="top"
! width='70' | Option
+
! Name
 +
! Standard Path
 
! Description
 
! Description
 
|- valign="top"
 
|- valign="top"
| {{Mono|org.basex.path}}
+
| [[RESTXQ]]
| Path to the BaseX home directory, in which the {{Mono|.basex}} configuration file will be placed. By default, no value is specified; as a result, the default servlet context path will be used.
+
| <code>/</code>
 +
| Write enriched APIs and full web applications with XQuery.
 
|- valign="top"
 
|- valign="top"
| {{Mono|org.basex.mode}}
+
| [[WebSockets]]
| Operation mode. By default, the value is "{{Mono|local}}": the servlets will access and store data locally using {{Mono|org.basex.path}}. If "{{Mono|client}}" is specified, all operations are performed on a remote server instance (the login data of which is stored in the {{Mono|.basex}} configuration file).
+
| <code>ws/</code>
 +
| Bidirectional client/server communication.
 
|- valign="top"
 
|- valign="top"
| {{Mono|org.basex.user}}
+
| [[REST]]
| Database user. By default, no value is specified, and the credentials must be specified by the client. Note that it is a clear security risk to store user credentials in the {{Mono|web.xml}} file. The default user credentials can be found under [[Startup#BaseX_Client|Startup: BaseX Client]].
+
| <code>rest/</code>
 +
| Straightforward access to XML databases and its resources.
 
|- valign="top"
 
|- valign="top"
| {{Mono|org.basex.password}}
+
| [[WebDAV]]
| Database user password.
+
| <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 defined as context parameters in the {{Code|web.xml}} file. The most important options for the web application context are:
 +
 
 +
{| class="wikitable"
 +
|-
 +
! width="160" | Option
 +
! width="90" |Default
 +
! Description
 +
|-
 +
|{{Option|USER}}
 +
|{{Code|admin}}
 +
| If a user is specified, no credentials must be passed on by the client.
 +
|-
 +
|{{Option|HTTPLOCAL}}
 +
|{{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}}.
 +
|-
 +
|{{Option|RESTXQPATH}}
 +
|{{Code|.}}
 +
|Relative or absolute directory referencing the [[RESTXQ]] modules. By default, the option points to the standard web application directory.
 +
|-
 +
|{{Option|RESTPATH}}
 +
|{{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.
 +
|-
 +
|{{Option|AUTHMETHOD}}
 +
|{{Code|Basic}}
 +
|The default authentication method proposed by the server. The available methods are {{Code|Basic}} and {{Code|Digest}}.
 
|}
 
|}
  
=Maven=
+
All options are prefixed with {{Code|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 ({{Code|webapp}}) path:
 +
 
 +
<syntaxhighlight lang="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>
 +
</syntaxhighlight>
 +
 
 +
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.
 +
 
 +
To enable or disable a specific service, the corresponding servlet entry in the {{Code|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:
 +
 
 +
<syntaxhighlight lang="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>
 +
</syntaxhighlight>
 +
 
 +
If the HTTP server is started with no pre-defined user, the credentials must be passed on by the client via [https://en.wikipedia.org/wiki/Basic_access_authentication Basic Authentication] or [https://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:8984/</code>
 +
 
 +
Users are specified in a {{Code|users.xml}} file, which is stored in the database directory (see [[User Management]] for more information).
 +
 
 +
=Changelog=
 +
 
 +
;Version 9.0
 +
* Updated: <code>jetty.xml</code> configuration file (required for Jetty 9).
 +
 
 +
;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).
 +
 
 +
;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: {{Code|jetty.xml}}: configuration for Jetty Server
 +
* Updated: {{Code|server}} replaced with {{Code|httplocal}} mode
 +
 
 +
;Version 7.3
  
Checkout the sources of basex and basex-api as described under [[Integrate#Check_Out|Integrate: Check Out]]. Execute <code>mvn install</code> in the basex project folder and then <code>mvn install jetty:run</code> in the basex-api project folder. This will start a Jetty instance in which the servlets will be deployed.
+
* Updated: {{Code|client}} mode replaced with {{Code|server}} mode
  
==Configuration==
+
;Version 7.2
The same options as in the case of deployment in a servlet container apply. For configuring various Jetty runtime options, such as port, context path, etc. refer to the [http://docs.codehaus.org/display/JETTY/Maven+Jetty+Plugin Maven Jetty Plugin]. These should be entered in the {{Mono|pom.xml}} file of the {{Mono|basex-api}} project.
 
  
[[Category:Server]]
+
* Web Application concept revised
[[Category:REST]]
 
[[Category:Developer]]
 
[[Category:Instructions]]
 

Latest revision as of 12:47, 2 July 2020

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[edit]

  • 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[edit]

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 mvn compile war:war in the basex-api 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 *.war distribution to deploy via the Tomcat web interface. By default, the interface is accessible via http://localhost:8080/manager/html/.

Maven[edit]

Check out the BaseX sources via Eclipse or Git. Execute mvn install in the main project directory and then mvn install jetty:run in the basex-api 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 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.

Services[edit]

The following services are available and enabled by default:

Name Standard Path Description
RESTXQ / Write enriched APIs and full web applications with XQuery.
WebSockets ws/ Bidirectional client/server communication.
REST rest/ Straightforward access to XML databases and its resources.
WebDAV webdav/ Database access via the file system.
Default static/ 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[edit]

Unless BaseX is deployed as servlet, the location of the web application directory can be adjusted via the WEBPATH option, and compression of HTTP responses can be enabled via the GZIP 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:

Option Default Description
USER admin If a user is specified, no credentials must be passed on by the client.
HTTPLOCAL 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 true.
RESTXQPATH . Relative or absolute directory referencing the RESTXQ modules. By default, the option points to the standard web application directory.
RESTPATH . Relative or absolute directory referencing queries and command-scripts that can be invoked via the run operation of REST. By default, the option points to the standard web application directory.
AUTHMETHOD Basic The default authentication method proposed by the server. The available methods are Basic and Digest.

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:

<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 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[edit]

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>
  <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>

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 USER:PASSWORD@URL. An example:

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

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

Changelog[edit]

Version 9.0
  • Updated: jetty.xml configuration file (required for Jetty 9).
Version 8.6
  • Updated: Authentication readded to RESTXQ.
  • Updated: No password must be specified in the web.xml 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