Difference between revisions of "Web Application"
Line 134: | Line 134: | ||
;Version 8.0 | ;Version 8.0 | ||
+ | * Added: digest authentication | ||
* Updated: user management | * Updated: user management | ||
* Updated: default user/password disabled in web.xml | * Updated: default user/password disabled in web.xml |
Revision as of 02:20, 11 December 2014
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:
- as standalone application by running the BaseX HTTP Server,
- as web servlets in a J2EE Servlet Container, and
- for development purposes, using Maven.
Contents
Servlet Container
In order to deploy BaseX HTTP Services in a servlet container, you may download the WAR distribution of BaseX from the download site or compile it via mvn compile war:war
in the basex-api
package. The WAR file can then be deployed following the instructions of the corresponding servlet container (jetty, tomcat).
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).
If run on a Jetty server you may use a jetty.xml
file for detailed server configuration. You can e.g. enable SSL connections or Jetty logging. Place the jetty.xml
right next to the web.xml
. For detailed configuration refer to the Jetty Documentation. A sample jetty.xml is placed in the basex-api package.
To run on Apache Tomcat, start the tomcat server and add any *.WAR
distribution to deploy using the Tomcat web interface (by default located at http://localhost:8080/manager/html/ ).
Configuration
All database options can be specified in the web.xml
file by prefixing the key with org.basex.
.
The most important options for the web application context are as follows:
Option | Default | Description |
---|---|---|
USER | 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 admin user was specified as default.
|
PASSWORD | admin
|
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 admin password was specified as default.
|
HTTPLOCAL | false
|
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 true , all servlets will communicate with a local database context which is not accessible from outside.
|
RESTXQPATH | .
|
RESTXQ directory. By default, all RESTXQ modules are located in the standard web application directory. |
AUTHMETHOD | Basic
|
Version 8.0: Authentication method. Basic and Digest is available.
|
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>
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 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 each HTTP service by specifying local init parameters. In the following example, the global credentials are overwritten and reset 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/> </init-param> <init-param> <param-name>org.basex.password</param-name> <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 Before: http://[host]:[port]/[servlet_context_path]
|
Access your standard web files (e.g. HTML, JavaScript or CSS). |
RESTXQ | http://[host]:[port]/[servlet_context_path] Before: http://[host]:[port]/[servlet_context_path]/restxq |
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 orwebdav://[host]:[port]/[servlet_context_path]/webdav (depending on client)
|
Access databases via the filesystem. |
Maven
Checkout the BaseX sources via Eclipse or Git. Execute mvn install
in the basex-core
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 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
Default login data can be stored server-side in the web.xml
file or specified via
command-line arguments. If the HTTP server is started with
no pre-defined credentials, users and passwords can be sent via
HTTP Basic Authentication
with each HTTP request. Since Version 8.0,
Digest Authentication is available
as well, with support for all qop directives (auth
and auth-int
).
Users are specified in a users.xml
file, which is stored in the database directory (see User Management for more information).
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 USER:PASSWORD@URL
. An example:
Changelog
- 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 withhttplocal
mode
- Version 7.3
- Updated:
client
mode replaced withserver
mode
- Version 7.2
- Web Application concept revised