Difference between revisions of "Request Module"
Jump to navigation
Jump to search
(57 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
− | This [[Module Library|XQuery Module]] contains functions for retrieving information on an HTTP request that has triggered the query. It is | + | This [[Module Library|XQuery Module]] contains functions for retrieving information on an HTTP request that has triggered the query. It is mostly useful when building [[Web Application]]s. |
− | The module is | + | The module is based on the [http://exquery.github.io/expath-specs-playground/request-module-1.0-specification.html EXQuery Request Module] draft. |
=Conventions= | =Conventions= | ||
− | All functions | + | * The module will be available if the {{Code|basex-api}} library is found in the classpath. This is the case if you use one of the complete distributions of BaseX (zip, exe, war). |
+ | * All functions are assigned to the <code><nowiki>http://exquery.org/ns/request</nowiki></code> namespace, which is statically bound to the {{Code|request}} prefix. | ||
+ | * If any of the functions is called outside the servlet context, <code>[[XQuery Errors#BaseX Errors|basex:http]]</code> is raised. | ||
− | + | The following example illustrated what components a URI may consist of (the example is derived from [http://tools.ietf.org/html/rfc3986 RFC 3986]): | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
<pre> | <pre> | ||
− | foo://example.com:8042/over/there?name=ferret | + | foo://example.com:8042/over/there?name=ferret&code=7 |
− | \_/ \_________/ \__/\_________/ \ | + | \_/ \_________/ \__/\_________/ \________________/ |
− | | | | | | + | | | | | | |
− | scheme hostname port path | + | scheme hostname port path query |
</pre> | </pre> | ||
Line 25: | Line 21: | ||
==request:method== | ==request:method== | ||
+ | |||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:method() as xs:string</pre> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the Method of the HTTP request. | |Returns the Method of the HTTP request. | ||
Line 38: | Line 35: | ||
==request:scheme== | ==request:scheme== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:scheme() as xs:string</pre> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the Scheme component of the URI of an HTTP request. | |Returns the Scheme component of the URI of an HTTP request. | ||
− | |- | + | |- valign="top" |
| '''Example''' | | '''Example''' | ||
|For the example given in the introduction, this function would return {{Code|foo}}. | |For the example given in the introduction, this function would return {{Code|foo}}. | ||
Line 51: | Line 48: | ||
==request:hostname== | ==request:hostname== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:hostname() as xs:string</pre> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the Hostname component of the URI of an HTTP request. | |Returns the Hostname component of the URI of an HTTP request. | ||
− | |- | + | |- valign="top" |
| '''Example''' | | '''Example''' | ||
|For the example given in the introduction, this function would return {{Code|example.com}}. | |For the example given in the introduction, this function would return {{Code|example.com}}. | ||
Line 64: | Line 61: | ||
==request:port== | ==request:port== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:port() as xs:integer</pre> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the Port component of the URI of an HTTP request, or a default port if it has not been explicitly specified in the URI. | |Returns the Port component of the URI of an HTTP request, or a default port if it has not been explicitly specified in the URI. | ||
− | |- | + | |- valign="top" |
| '''Example''' | | '''Example''' | ||
|For the example given in the introduction, this function would return {{Code|8042}}. | |For the example given in the introduction, this function would return {{Code|8042}}. | ||
Line 77: | Line 74: | ||
==request:path== | ==request:path== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:path() as xs:string</pre> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the Path component of the URI of an HTTP request. | |Returns the Path component of the URI of an HTTP request. | ||
− | |- | + | |- valign="top" |
| '''Example''' | | '''Example''' | ||
|For the example given in the introduction, this function would return {{Code|/over/there}}.<br/> | |For the example given in the introduction, this function would return {{Code|/over/there}}.<br/> | ||
Line 90: | Line 87: | ||
==request:query== | ==request:query== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:query() as xs:string?</pre> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
− | |Returns the Query component of the URI of an HTTP request. If no query | + | |Returns the Query component of the URI of an HTTP request. If no query component exists, an empty sequence is returned. |
− | |- | + | |- valign="top" |
| '''Example''' | | '''Example''' | ||
− | |For the example given in the introduction, this function would return | + | |For the example given in the introduction, this function would return <code>name=ferret&code=7</code>.<br/> |
|} | |} | ||
==request:uri== | ==request:uri== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:uri() as xs:anyURI</pre> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the complete URI of an HTTP request as it has been specified by the client. | |Returns the complete URI of an HTTP request as it has been specified by the client. | ||
− | |- | + | |- valign="top" |
| '''Example''' | | '''Example''' | ||
− | |For the example given in the introduction, this method would return | + | |For the example given in the introduction, this method would return <code>foo://example.com:8042/over/there?name=ferret&code=7</code>.<br/> |
+ | |} | ||
+ | |||
+ | ==request:context-path== | ||
+ | |||
+ | {| width='100%' | ||
+ | |- valign="top" | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>request:context-path() as xs:string</pre> | ||
+ | |- valign="top" | ||
+ | | '''Summary''' | ||
+ | |Returns the context of the request. For servlets in the default (root) context, this method returns an empty string. | ||
|} | |} | ||
Line 118: | Line 126: | ||
==request:address== | ==request:address== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:address() as xs:string</pre> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the IP address of the server. | |Returns the IP address of the server. | ||
Line 128: | Line 136: | ||
==request:remote-hostname== | ==request:remote-hostname== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:remote-hostname() as xs:string</pre> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the fully qualified hostname of the client that sent the request. | |Returns the fully qualified hostname of the client that sent the request. | ||
Line 138: | Line 146: | ||
==request:remote-address== | ==request:remote-address== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:remote-address() as xs:string</pre> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the IP address of the client that sent the request. | |Returns the IP address of the client that sent the request. | ||
Line 148: | Line 156: | ||
==request:remote-port== | ==request:remote-port== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:remote-port() as xs:string</pre> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the TCP port of the client socket that triggered the request. | |Returns the TCP port of the client socket that triggered the request. | ||
Line 159: | Line 167: | ||
==request:parameter-names== | ==request:parameter-names== | ||
+ | |||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:parameter-names() as xs:string*</pre> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
− | |Returns the names of all query parameters available from the HTTP request. | + | |Returns the names of all query and form field parameters available from the HTTP request. With [[RESTXQ]], this function can be used to access parameters that have not been statically bound by [[RESTXQ#Query Parameters|%rest:query-param]]. |
− | |- | + | |- valign="top" |
| '''Example''' | | '''Example''' | ||
|For the example given in the introduction, this function would return {{Code|name}}.<br/> | |For the example given in the introduction, this function would return {{Code|name}}.<br/> | ||
+ | |- valign="top" | ||
+ | | '''Errors''' | ||
+ | |{{Error|parameter|#Errors}} the request has invalid parameters. | ||
|} | |} | ||
==request:parameter== | ==request:parameter== | ||
+ | |||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:parameter( |
− | |- | + | $name as xs:string, |
+ | $default as xs:string := () | ||
+ | ) as xs:string*</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the value of the named query parameter in an HTTP request. If the parameter does not exist, an empty sequence or the optionally specified default value is returned instead. | + | |Returns the value of the named query or form field parameter in an HTTP request. If the parameter does not exist, an empty sequence or the optionally specified default value is returned instead. If both query and form field parameters with the same name exist, the form field values will be attached to the query values. |
− | |- | + | |- valign="top" |
| '''Example''' | | '''Example''' | ||
− | |For the example given in the introduction, the function call {{Code|request:parameter(' | + | |For the example given in the introduction, the function call {{Code|request:parameter('code')}} would return {{Code|7}}.<br/> |
+ | |- valign="top" | ||
+ | | '''Errors''' | ||
+ | |{{Error|parameter|#Errors}} the request has invalid parameters. | ||
|} | |} | ||
Line 188: | Line 207: | ||
==request:header-names== | ==request:header-names== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:header-names() as xs:string*</pre> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
− | |Returns the names of all headers available from the HTTP request. If [[RESTXQ]] is used, this function | + | |Returns the names of all headers available from the HTTP request. If [[RESTXQ]] is used, this function can be used to access headers that have not been statically bound by [[RESTXQ#HTTP Headers|%rest:header-param]]. |
|} | |} | ||
==request:header== | ==request:header== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:header( |
− | |- | + | $name as xs:string, |
+ | $default as xs:string := () | ||
+ | ) as xs:string?</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
|Returns the value of the named header in an HTTP request. If the header does not exist, an empty sequence or the optionally specified default value is returned instead. | |Returns the value of the named header in an HTTP request. If the header does not exist, an empty sequence or the optionally specified default value is returned instead. | ||
Line 210: | Line 232: | ||
==request:cookie-names== | ==request:cookie-names== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:cookie-names() as xs:string*</pre> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
− | |Returns the names of all cookies in the HTTP headers available from the HTTP request. If [[RESTXQ]] is used, this function | + | |Returns the names of all cookies in the HTTP headers available from the HTTP request. If [[RESTXQ]] is used, this function can be used to access cookies that have not been statically bound by [[RESTXQ#Cookies|%rest:cookie-param]]. |
|} | |} | ||
==request:cookie== | ==request:cookie== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width=' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>request:cookie( |
− | |- | + | $name as xs:string, |
+ | $default as xs:string := () | ||
+ | ) as xs:string?</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
|Returns the value of the named Cookie in an HTTP request. If there is no such cookie, an empty sequence or the optionally specified default value is returned instead. | |Returns the value of the named Cookie in an HTTP request. If there is no such cookie, an empty sequence or the optionally specified default value is returned instead. | ||
+ | |} | ||
+ | |||
+ | =Attribute Functions= | ||
+ | |||
+ | ==request:attribute-names== | ||
+ | |||
+ | {| width='100%' | ||
+ | |- valign="top" | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>request:attribute-names() as xs:string*</pre> | ||
+ | |- valign="top" | ||
+ | | '''Summary''' | ||
+ | |Returns the names of all HTTP request attributes. | ||
+ | |} | ||
+ | |||
+ | ==request:attribute== | ||
+ | |||
+ | {| width='100%' | ||
+ | |- valign="top" | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>request:attribute( | ||
+ | $name as xs:string, | ||
+ | $default as item()* := () | ||
+ | ) as item()*</pre> | ||
+ | |- valign="top" | ||
+ | | '''Summary''' | ||
+ | |Returns the value of an attribute of the HTTP request. If the attribute does not exist, an empty sequence or the optionally specified default value is returned instead. | ||
+ | |- valign="top" | ||
+ | | '''Example''' | ||
+ | | | ||
+ | * {{Code|request:attribute("javax.servlet.error.request_uri")}} returns the original URI of a caught error. | ||
+ | * {{Code|request:attribute("javax.servlet.error.message")}} returns the error message of a caught error. | ||
+ | |} | ||
+ | |||
+ | ==request:set-attribute== | ||
+ | |||
+ | {| width='100%' | ||
+ | |- valign="top" | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>request:set-attribute( | ||
+ | $name as xs:string, | ||
+ | $value as item()* | ||
+ | ) as empty-sequence()</pre> | ||
+ | |- valign="top" | ||
+ | | '''Summary''' | ||
+ | |Binds the specified {{Code|$value}} to the request attribute with the specified {{Code|$name}}. | ||
+ | |} | ||
+ | |||
+ | =Errors= | ||
+ | |||
+ | {| class="wikitable" width="100%" | ||
+ | ! width="110"|Code | ||
+ | |Description | ||
+ | |- valign="top" | ||
+ | |{{Code|parameter}} | ||
+ | |Request has invalid parameters. | ||
|} | |} | ||
=Changelog= | =Changelog= | ||
+ | |||
+ | ;Version 9.3 | ||
+ | * Added: {{Function||request:attribute-names}}, {{Function||request:set-attribute}} | ||
+ | * Updated: {{Function||request:attribute}}: return type generalized, default argument added | ||
+ | |||
+ | ;Version 7.9 | ||
+ | * Updated: The returned values of {{Function||request:parameter-names}}, {{Function||request:parameter}} now also include form field parameters. | ||
+ | |||
+ | ;Version 7.8 | ||
+ | * Added: {{Function||request:context-path}} | ||
+ | |||
+ | ;Version 7.7 | ||
+ | * Added: {{Function||request:attribute}} | ||
This module was introduced with Version 7.5. | This module was introduced with Version 7.5. | ||
− | |||
− |
Latest revision as of 16:23, 9 March 2023
This XQuery Module contains functions for retrieving information on an HTTP request that has triggered the query. It is mostly useful when building Web Applications.
The module is based on the EXQuery Request Module draft.
Contents
Conventions[edit]
- The module will be available if the
basex-api
library is found in the classpath. This is the case if you use one of the complete distributions of BaseX (zip, exe, war). - All functions are assigned to the
http://exquery.org/ns/request
namespace, which is statically bound to therequest
prefix. - If any of the functions is called outside the servlet context,
basex:http
is raised.
The following example illustrated what components a URI may consist of (the example is derived from RFC 3986):
foo://example.com:8042/over/there?name=ferret&code=7 \_/ \_________/ \__/\_________/ \________________/ | | | | | scheme hostname port path query
General Functions[edit]
request:method[edit]
Signature | request:method() as xs:string |
Summary | Returns the Method of the HTTP request. |
URI Functions[edit]
request:scheme[edit]
Signature | request:scheme() as xs:string |
Summary | Returns the Scheme component of the URI of an HTTP request. |
Example | For the example given in the introduction, this function would return foo .
|
request:hostname[edit]
Signature | request:hostname() as xs:string |
Summary | Returns the Hostname component of the URI of an HTTP request. |
Example | For the example given in the introduction, this function would return example.com .
|
request:port[edit]
Signature | request:port() as xs:integer |
Summary | Returns the Port component of the URI of an HTTP request, or a default port if it has not been explicitly specified in the URI. |
Example | For the example given in the introduction, this function would return 8042 .
|
request:path[edit]
Signature | request:path() as xs:string |
Summary | Returns the Path component of the URI of an HTTP request. |
Example | For the example given in the introduction, this function would return /over/there . |
request:query[edit]
Signature | request:query() as xs:string? |
Summary | Returns the Query component of the URI of an HTTP request. If no query component exists, an empty sequence is returned. |
Example | For the example given in the introduction, this function would return name=ferret&code=7 . |
request:uri[edit]
Signature | request:uri() as xs:anyURI |
Summary | Returns the complete URI of an HTTP request as it has been specified by the client. |
Example | For the example given in the introduction, this method would return foo://example.com:8042/over/there?name=ferret&code=7 . |
request:context-path[edit]
Signature | request:context-path() as xs:string |
Summary | Returns the context of the request. For servlets in the default (root) context, this method returns an empty string. |
Connection Functions[edit]
request:address[edit]
Signature | request:address() as xs:string |
Summary | Returns the IP address of the server. |
request:remote-hostname[edit]
Signature | request:remote-hostname() as xs:string |
Summary | Returns the fully qualified hostname of the client that sent the request. |
request:remote-address[edit]
Signature | request:remote-address() as xs:string |
Summary | Returns the IP address of the client that sent the request. |
request:remote-port[edit]
Signature | request:remote-port() as xs:string |
Summary | Returns the TCP port of the client socket that triggered the request. |
Parameter Functions[edit]
request:parameter-names[edit]
Signature | request:parameter-names() as xs:string* |
Summary | Returns the names of all query and form field parameters available from the HTTP request. With RESTXQ, this function can be used to access parameters that have not been statically bound by %rest:query-param. |
Example | For the example given in the introduction, this function would return name . |
Errors | parameter : the request has invalid parameters.
|
request:parameter[edit]
Signature | request:parameter( $name as xs:string, $default as xs:string := () ) as xs:string* |
Summary | Returns the value of the named query or form field parameter in an HTTP request. If the parameter does not exist, an empty sequence or the optionally specified default value is returned instead. If both query and form field parameters with the same name exist, the form field values will be attached to the query values. |
Example | For the example given in the introduction, the function call request:parameter('code') would return 7 . |
Errors | parameter : the request has invalid parameters.
|
Header Functions[edit]
request:header-names[edit]
Signature | request:header-names() as xs:string* |
Summary | Returns the names of all headers available from the HTTP request. If RESTXQ is used, this function can be used to access headers that have not been statically bound by %rest:header-param. |
request:header[edit]
Signature | request:header( $name as xs:string, $default as xs:string := () ) as xs:string? |
Summary | Returns the value of the named header in an HTTP request. If the header does not exist, an empty sequence or the optionally specified default value is returned instead. |
Cookie Functions[edit]
request:cookie-names[edit]
Signature | request:cookie-names() as xs:string* |
Summary | Returns the names of all cookies in the HTTP headers available from the HTTP request. If RESTXQ is used, this function can be used to access cookies that have not been statically bound by %rest:cookie-param. |
request:cookie[edit]
Signature | request:cookie( $name as xs:string, $default as xs:string := () ) as xs:string? |
Summary | Returns the value of the named Cookie in an HTTP request. If there is no such cookie, an empty sequence or the optionally specified default value is returned instead. |
Attribute Functions[edit]
request:attribute-names[edit]
Signature | request:attribute-names() as xs:string* |
Summary | Returns the names of all HTTP request attributes. |
request:attribute[edit]
Signature | request:attribute( $name as xs:string, $default as item()* := () ) as item()* |
Summary | Returns the value of an attribute of the HTTP request. If the attribute does not exist, an empty sequence or the optionally specified default value is returned instead. |
Example |
|
request:set-attribute[edit]
Signature | request:set-attribute( $name as xs:string, $value as item()* ) as empty-sequence() |
Summary | Binds the specified $value to the request attribute with the specified $name .
|
Errors[edit]
Code | Description |
---|---|
parameter
|
Request has invalid parameters. |
Changelog[edit]
- Version 9.3
- Added:
request:attribute-names
,request:set-attribute
- Updated:
request:attribute
: return type generalized, default argument added
- Version 7.9
- Updated: The returned values of
request:parameter-names
,request:parameter
now also include form field parameters.
- Version 7.8
- Added:
request:context-path
- Version 7.7
- Added:
request:attribute
This module was introduced with Version 7.5.