Difference between revisions of "Web Application"
Line 103: | Line 103: | ||
=Changelog= | =Changelog= | ||
− | + | ;Version 7.3 | |
+ | |||
+ | * Updated: {{Code|client}} mode replaced with {{Code|server}} mode ({{Code|org.basex.mode}}) | ||
+ | |||
+ | ;Version 7.2 | ||
* Web Application concept revised | * Web Application concept revised |
Revision as of 21:01, 2 June 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 web servlets in a J2EE servlet container,
- for development purposes, using maven, and
- as a standalone application.
Contents
Servlet Container
In order to deploy BaseX HTTP Services in a servlet container, you need to download the WAR distribution of BaseX from the download site. The WAR file can then be 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 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).
Database Access
There are two modes in which the BaseX web application can access databases:
- local mode: the web application will access and store data on the local file system.
- client mode: the application communicates with a separately started database server.
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 XML database and its resources, see REST |
RESTXQ | http://[host]:[port]/[servlet_context_path]/restxq
|
create XQuery Web Services, see RESTXQ |
WebDAV | http://[host]:[port]/[servlet_context_path]/webdav orwebdav://[host]:[port]/[servlet_context_path]/webdav (depending on client)
|
access databases via the filesystem, see WebDAV |
Web Server | http://[host]:[port]/[servlet_context_path]
|
access your standard web files (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=local
from the command line).
Option | Default | Description |
---|---|---|
org.basex.mode
|
local
|
Operation mode. By default, the servlets will work with a local database context org.basex.path . With Version 7.3, the client mode has been replaced with a new server mode, which is equivalent to the default mode of the Standalone Application: a BaseX database server instance will be started with the first call of a service, which is then available for other clients, too.
|
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, which are usually stored in the .basex
configuration file (DBPATH
, HTTPPATH
, etc.), can be specified as well by prefixing the key with org.basex.
. If an option references a relative path, it will be prefixed with the servlet root 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 directly edit the WEB-INF/web.xml
file in the WAR archive (WAR files are simple ZIP files).
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.
Standalone Application
Detailed description how to start and setup the standalone BaseX HTTP server can found under Startup: BaseX HTTP Server.
Changelog
- Version 7.3
- Updated:
client
mode replaced withserver
mode (org.basex.mode
)
- Version 7.2
- Web Application concept revised