Difference between revisions of "Web Application"

From BaseX Documentation
Jump to navigation Jump to search
(37 intermediate revisions by 2 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 ways of deploying and configuring these services. The services can be deployed in three 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. The following three HTTP services are available:
 +
 
 +
* [[REST]]   offers a straightforward RESTful API for accessing database resources via URLs,
 +
* [[RESTXQ]] allows you to write more complex APIs and full web applications with XQuery, and
 +
* [[WebDAV]] gives access to databases via the file system.
 +
 
 +
This article describes different ways of deploying and configuring these services. The services can be deployed as follows:
 +
 
 +
* as standalone application, by running the [[Startup#HTTP Server|BaseX HTTP Server]],
 +
* as web servlet in a [[#Servlet Container|Servlet Container]], and
 +
* as web servlet, using [[#Maven|Maven]].
 +
 
 +
Authentication:
 +
 
 +
* If a user is defined in the <code>web.xml</code> file via the key <code>org.basex.user</code>, no password must be specified.
 +
* If the <code>admin</code> user is specified for an API, all features will be available without restriction.
 +
* Predefined authentication methods and default users cannot be overwritten by client.
  
* as standalone application by running the [[Startup#BaseX HTTP Server|BaseX HTTP Server]],
 
* as web servlets in a J2EE [[#Servlet Container|Servlet Container]], and
 
* for development purposes, using [[#Maven|Maven]].<br/><br/>
 
  
 
=Servlet Container=
 
=Servlet Container=
  
In order to deploy BaseX HTTP Services in a servlet container, you may download the WAR distribution of BaseX from the [http://basex.org/download download site] or compile it via <code>mvn compile war:war</code> in the <code>basex-api</code> package. The WAR file can then be deployed following the instructions of the corresponding servlet container ([http://docs.codehaus.org/display/JETTY/WebAppDeployer jetty], [http://tomcat.apache.org/tomcat-7.0-doc/deployer-howto.html tomcat]).
+
In order to deploy BaseX HTTP Services in a servlet container, you can download the WAR distribution of BaseX from the [http://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 ([http://www.eclipse.org/jetty/documentation/current/quickstart-deploying-webapps.html jetty], [http://tomcat.apache.org/tomcat-7.0-doc/deployer-howto.html tomcat], etc.).
  
Configuring port, context path, etc. 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. http://localhost:8080/BaseX711/rest).
+
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 run on a Jetty server you may use a {{Code|jetty.xml}} file for detailed server configuration. You can e.g. enable SSL connections or Jetty logging. Place the {{Code|jetty.xml}} right next to the {{Code|web.xml}}. For detailed configuration refer to the [http://wiki.eclipse.org/Jetty/Reference/jetty.xml Jetty Documentation]. A sample [https://github.com/BaseXdb/basex-api/blob/master/src/main/webapp/WEB-INF/jetty.xml jetty.xml] is placed in the basex-api package.
+
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 [http://www.eclipse.org/jetty/documentation/current/jetty-xml-config.html Jetty Documentation].
  
To run on [http://tomcat.apache.org/ Apache Tomcat], start the tomcat server and add any <code>*.WAR</code> distribution to deploy using the Tomcat web interface (by default located at http://localhost:8080/manager/html/ ).
+
To run on [http://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/.
  
 
==Configuration==
 
==Configuration==
  
All database options can be specified in the {{Code|web.xml}} file by prefixing the key with {{Code|org.basex.}}.
+
All database options can be specified in the {{Code|web.xml}} file. They need to be defined as context parameters and prefixed with {{Code|org.basex.}}. The most important options for the web application context are as follows:
The most important options for the web application context are as follows:
 
  
 
{| class="wikitable"  
 
{| class="wikitable"  
Line 26: Line 38:
 
! Description
 
! Description
 
|-
 
|-
|[[Options#USER|USER]]
+
|<code>[[Options#USER|USER]]</code>
 
|{{Code|admin}}
 
|{{Code|admin}}
| User name. 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. Until {{Version|7.9}}, the {{Code|admin}} user was specified as default.
+
| If a user is specified, no credentials must be passed on by the client.
 
|-
 
|-
|[[Options#USER|PASSWORD]]
+
|<code>[[Options#HTTPLOCAL|HTTPLOCAL]]</code>
|{{Code|admin}}
+
|{{Code|false}}
| Login data. If no password is specified, it must be passed on by the client. Please check by yourself if it is safe to store your credentials in plain text. Until {{Version|7.9}}, the {{Code|admin}} password was specified as default.
+
|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}}.
 
|-
 
|-
|[[Options#HTTPLOCAL|HTTPLOCAL]]
+
|<code>[[Options#RESTXQPATH|RESTXQPATH]]</code>
|{{Code|false}}
+
|{{Code|.}}
|Operation mode. By default, the servlets will work in client/server mode, and a database server instance will be started along with the web server, which can also be addressed from other BaseX clients. If the flag is set to {{Code|true}}, all servlets will communicate with a local database context which is not accessible from outside.
+
|Relative or absolute directory referencing the [[RESTXQ]] modules. By default, the option points to the standard web application directory.
 
|-
 
|-
|[[Options#RESTXQPATH|RESTXQPATH]]
+
|<code>[[Options#RESTPATH|RESTPATH]]</code>
 
|{{Code|.}}
 
|{{Code|.}}
|[[RESTXQ]] directory. By default, all RESTXQ modules are located in the standard web application directory.
+
|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|AUTHMETHOD]]</code>
 +
|{{Code|Basic}}
 +
|The default authentication method proposed by the server. The available methods are {{Code|Basic}} and {{Code|Digest}}.
 
|}
 
|}
  
Line 58: Line 74:
 
</pre>  
 
</pre>  
  
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 done by [https://wiki.eclipse.org/Jetty/Reference/override-web.xml 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.
+
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.
  
Different credentials can be assigned to each HTTP service by specifying local init parameters. In the following example, the global credentials are overwritten and reset for the REST service:
+
Different credentials can be assigned to the REST and WebDAV service by specifying local init parameters. In the following example, an alternative user is specified for the REST service:
  
 
<pre class="brush:xml">  
 
<pre class="brush:xml">  
Line 68: Line 84:
 
     <init-param>
 
     <init-param>
 
       <param-name>org.basex.user</param-name>
 
       <param-name>org.basex.user</param-name>
       <param-value/>
+
       <param-value>rest-user</param-value>
    </init-param>
 
    <init-param>
 
      <param-name>org.basex.password</param-name>
 
      <param-value/>
 
 
     </init-param>
 
     </init-param>
 
   </servlet>
 
   </servlet>
Line 78: Line 90:
  
 
==Available Services==
 
==Available Services==
 +
 
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:
 
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:
  
Line 87: Line 100:
 
|- valign="top"
 
|- valign="top"
 
| Default web server
 
| Default web server
| {{Code|http://[host]:[port]/[servlet_context_path]/static}}<br/>Before: {{Code|http://[host]:[port]/[servlet_context_path]}}
+
| {{Code|http://[host]:[port]/[servlet_context_path]/static}}
 
| Access your standard web files (e.g. HTML, JavaScript or CSS).
 
| Access your standard web files (e.g. HTML, JavaScript or CSS).
 
|- valign="top"
 
|- valign="top"
 
| [[RESTXQ]]
 
| [[RESTXQ]]
| {{Code|http://[host]:[port]/[servlet_context_path]}}<br/>Before: {{Code|http://[host]:[port]/[servlet_context_path]/restxq}}<br/>
+
| {{Code|http://[host]:[port]/[servlet_context_path]}}
 
| Create XQuery web services and applications.
 
| Create XQuery web services and applications.
 
|- valign="top"
 
|- valign="top"
Line 105: Line 118:
 
=Maven=
 
=Maven=
  
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 jetty:run</code> in the <code>basex-api</code> project folder. This will start a Jetty instance in which the servlets will be deployed.
+
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.
  
 
==Configuration==
 
==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>[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.
+
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=
 
=User Management=
  
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] with each HTTP request. Login data can be stored server-side in the <code>web.xml</code> file, or specified as [[Command-Line Options#BaseX HTTP Server|command-line arguments]].
+
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).
  
For multi-user access, or a changed {{Code|admin}} password, you may place the [[Configuration#Configuration_Files|.basexperm]] configuration file in the server root. More details are found in the [[User Management]] article.
+
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, 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:
+
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>
 
: <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=
 
=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).
  
 
;Version 8.0
 
;Version 8.0
* Updated: default user and password removed from web.xml
+
* Added: digest authentication
 +
* Updated: user management
 +
* Updated: default user/password disabled in web.xml
  
 
;Version 7.7
 
;Version 7.7
Line 140: Line 163:
  
 
* Web Application concept revised
 
* Web Application concept revised
 
[[Category:Server]]
 
[[Category:HTTP]]
 
[[Category:Developer]]
 

Revision as of 16:49, 24 November 2017

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 three HTTP services are available:

  • REST offers a straightforward RESTful API for accessing database resources via URLs,
  • RESTXQ allows you to write more complex APIs and full web applications with XQuery, and
  • WebDAV gives access to databases via the file system.

This article describes different ways of deploying and configuring these services. The services can be deployed as follows:

Authentication:

  • If a user is defined in the web.xml file via the key org.basex.user, no password must be specified.
  • If the admin user is specified for an API, all features will be available without restriction.
  • Predefined authentication methods and default users cannot be overwritten by client.


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

Configuration

All database options can be specified in the web.xml file. They need to be defined as context parameters and prefixed with org.basex.. The most important options for the web application context are as follows:

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.

Path options may contain an absolute or relative path. If a relative path is specified, its root will be the servlet (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.

Different credentials can be assigned to the REST and WebDAV 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>

Available Services

To enable or disable one of the provided services, the corresponding servlet entry in the web.xml file needs to be removed/commented. The default URL paths are listed in the following table:

Service URL Usage
Default web server http://[host]:[port]/[servlet_context_path]/static Access your standard web files (e.g. HTML, JavaScript or CSS).
RESTXQ http://[host]:[port]/[servlet_context_path] Create XQuery web services and applications.
REST http://[host]:[port]/[servlet_context_path]/rest Access XML database and its resources.
WebDAV http://[host]:[port]/[servlet_context_path]/webdav or
webdav://[host]:[port]/[servlet_context_path]/webdav (depending on client)
Access databases via the filesystem.

Maven

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.

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

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 arguments. In the web.xml 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 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

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