Difference between revisions of "Web Application"

From BaseX Documentation
Jump to navigation Jump to search
Line 26: Line 26:
  
 
==Configuring Available Services==
 
==Configuring Available Services==
To enable or disable one of the provided services, the corresponding servlet entry in the {{Mono|web.xml}} file needs to be removed/commented.
+
To enable or disable one of the provided services, the corresponding servlet entry in the {{Mono|web.xml}} file needs to be removed/commented. The default URL paths are listed in the following table:
 +
 
 +
{| class="wikitable"
 +
|- valign="top"
 +
! Service
 +
! URL
 +
! usage
 +
|- valign="top"
 +
| REST
 +
| <nowiki>http://[host]:[port]/[servlet_context_path]/rest</nowiki>
 +
| access the BaseX-XML-database, see [[REST]]
 +
|- valign="top"
 +
| RESTXQ
 +
| <nowiki>http://[host]:[port]/[servlet_context_path]/restxq</nowiki>
 +
| facility to make your modules a web application, see [[RESTXQ]]
 +
|- valign="top"
 +
| WebDAV
 +
| <nowiki>http://[host]:[port]/[servlet_context_path]/webdav</nowiki> or<br/><nowiki>webdav://[host]:[port]/[servlet_context_path]/webdav</nowiki> (depending on the WebDAV client)
 +
| the BaseX-XML-database in a filesystem representation, see [[WebDAV]]
 +
|- valign="top"
 +
| Webserver
 +
| <nowiki>http://[host]:[port]/[servlet_context_path]</nowiki>
 +
| place your web stuff there (e.g. HTML, JavaScript or CSS).
 +
|}
  
 
==Configuring Database Access==
 
==Configuring Database Access==

Revision as of 14:47, 22 March 2012

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 3 different ways:

  • as a standalone application,
  • as web servlets in a J2EE servlet container,
  • and for development purposes, using maven.

Standalone: BaseX HTTP Server

Detailed description how to start and setup the standalone BaseX HTTP server can found under Startup: BaseX HTTP Server and Startup Options: BaseX HTTP Server.

Servlet Container

In order to deploy BaseX HTTP Services in a servlet container, one needs to download the WAR distribution of BaseX from the download site. The downloaded WAR file can be then deployed following the instructions of the corresponding servlet container (jetty, tomcat).

Servlet Container Configuration

Configuring port, context path, etc. can be done following the corresponding instructions of the used servlet container. This is needed if the default URL path (e.g. http://localhost:8080/rest instead of http://localhost:8080/BaseX711/rest ) is not desired.

Database Access

There are two ways in which the BaseX web application can access databases:

  • either a dedicated database server should be manually started,
  • or the web application will access and store data on the local file system.

The operation mode can be configured as explained further below.

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 $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 $HOME directory), the web application will not use by the default the settings stored in $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 $HOME, in which case the web application will use the same databases as in the case of the standalone server.

Configuring 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
REST http://[host]:[port]/[servlet_context_path]/rest access the BaseX-XML-database, see REST
RESTXQ http://[host]:[port]/[servlet_context_path]/restxq facility to make your modules a web application, see RESTXQ
WebDAV http://[host]:[port]/[servlet_context_path]/webdav or
webdav://[host]:[port]/[servlet_context_path]/webdav (depending on the WebDAV client)
the BaseX-XML-database in a filesystem representation, see WebDAV
Webserver http://[host]:[port]/[servlet_context_path] place your web stuff there (e.g. HTML, JavaScript or CSS).

Configuring Database Access

The following options are available to configure the way the databases are accessed. These can be set in the web.xml file or as Java system variables (e.g. using -Dorg.basex.mode=client from the command line).

Option Default Description
org.basex.mode local Operation mode. By default, the value is "local": the servlets will access and store data locally using org.basex.path. If "client" is specified, all operations are performed on a remote server instance (the login data of which is stored in the .basex configuration file).
org.basex.user - 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 web.xml file. The default user credentials can be found under Startup: BaseX Client.
org.basex.password - Database user password.

Additionally, all database main options (DBPATH, HTTPPATH, etc can be overwritten by adding additional context-param elements and prefixing the name with "org.basex.". Relative paths will be prefixed with the servlet path. Some examples follow:

 
  <context-param>
    <param-name>org.basex.dbpath</param-name>
    <param-value>data</param-value>
  </context-param>
  <context-param>
    <param-name>org.basex.httppath</param-name>
    <param-value>http</param-value>
  </context-param>
  <context-param>
    <param-name>org.basex.repopath</param-name>
    <param-value>repo</param-value>
  </context-param>
  <context-param>
    <param-name>org.basex.lang</param-name>
    <param-value>English</param-value>
  </context-param>

How to set these options in the web.xml of the BaseX web application is specific to the servlet container. For example, in Jetty it is done using an overriding web.xml. Another option is to decompress the WAR file, edit the WEB-INF/web.xml file and again compress the WAR file.

Maven

Checkout the sources of basex and basex-api as described under Integrate: Check Out. Execute mvn install in the basex project folder and then mvn install jetty:run in the basex-api 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 uses the directory basex-api/src/main/webapp. For configuring various Jetty runtime options, such as port, context path, etc. refer to the Maven Jetty Plugin. These should be entered in the pom.xml file of the basex-api project.