Difference between revisions of "Web Application"
(18 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
− | BaseX can be used | + | 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 services are provided: |
− | + | {| class="wikitable" | |
− | + | |- valign="top" | |
− | + | ! Name | |
+ | ! Standard Path | ||
+ | ! Description | ||
+ | |- valign="top" | ||
+ | | [[RESTXQ]] | ||
+ | | <code>/</code> | ||
+ | | Write enriched APIs and full web applications with XQuery. | ||
+ | |- valign="top" | ||
+ | | [[WebSockets]] | ||
+ | | <code>ws/</code> | ||
+ | | Bidirectional client/server communication. | ||
+ | |- valign="top" | ||
+ | | [[REST]] | ||
+ | | <code>rest/</code> | ||
+ | | Straightforward access to XML databases and its resources. | ||
+ | |- valign="top" | ||
+ | | [[WebDAV]] | ||
+ | | <code>webdav/</code> | ||
+ | | Database access via the file system. | ||
+ | |- valign="top" | ||
+ | | Default | ||
+ | | <code>static/</code> | ||
+ | | Access to static server resources (HTML, JavaScript, CSS, images, …). | ||
+ | |} | ||
− | + | ==Deployment== | |
− | * as standalone application by running the [[Startup#HTTP Server|BaseX HTTP Server]], | + | This article describes different ways of deploying and configuring these services. BaseX 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 in a [[#Servlet Container|Servlet Container]], and | ||
− | * as web servlet, using [[#Maven|Maven]]. | + | * as web servlet, using [[#Maven|Maven]]. |
=Servlet Container= | =Servlet Container= | ||
− | In order to deploy BaseX HTTP Services in a servlet container, you | + | 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.). |
− | + | 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 | + | 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 | + | 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== | ||
− | + | Initial 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: | |
− | They need to be | ||
− | The most important options for the web application context are as follows: | ||
{| class="wikitable" | {| class="wikitable" | ||
Line 35: | Line 58: | ||
|<code>[[Options#USER|USER]]</code> | |<code>[[Options#USER|USER]]</code> | ||
|{{Code|admin}} | |{{Code|admin}} | ||
− | | | + | | If a user is specified, no credentials must be passed on by the client. |
− | |||
− | |||
− | |||
− | |||
|- | |- | ||
|<code>[[Options#HTTPLOCAL|HTTPLOCAL]]</code> | |<code>[[Options#HTTPLOCAL|HTTPLOCAL]]</code> | ||
Line 58: | Line 77: | ||
|} | |} | ||
− | + | Local file paths in options may be absolute or relative. If a relative path is specified, its root will be the servlet ({{Code|webapp}}) path: | |
<pre class="brush:xml"> | <pre class="brush: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> | |
</pre> | </pre> | ||
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. | 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 | + | 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: | ||
<pre class="brush:xml"> | <pre class="brush: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> | |
− | |||
− | |||
− | |||
− | |||
</pre> | </pre> | ||
− | + | 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, 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). | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
=Maven= | =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. | |
==Configuration== | ==Configuration== | ||
− | The same options as in the case of deployment in a servlet container | + | 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. |
− | = | + | =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 | ;Version 8.0 |
Revision as of 11:22, 22 October 2018
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 services are provided:
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, …). |
Contents
Deployment
This article describes different ways of deploying and configuring these services. BaseX can be deployed as follows:
- as standalone application, by running the BaseX HTTP Server,
- as web servlet in a Servlet Container, and
- as web servlet, using Maven.
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
Initial 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 .
|
Local file paths in options may be absolute or relative. 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.
To enable or disable a specific service, the corresponding servlet entry in the 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:
<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:
Users are specified in a users.xml
file, which is stored in the database directory (see User Management for more information).
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.
Changelog
- 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 withhttplocal
mode
- Version 7.3
- Updated:
client
mode replaced withserver
mode
- Version 7.2
- Web Application concept revised