Difference between revisions of "Request Module"

From BaseX Documentation
Jump to navigation Jump to search
 
(87 intermediate revisions by 2 users 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 mainly useful in combination with the [[RESTXQ]] API. Note that all functions will also be defined in the upcoming [http://exquery.github.com/expath-specs-playground/request-module-1.0-specification.html EXQuery Request Module].
+
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 based on the [http://exquery.github.io/expath-specs-playground/request-module-1.0-specification.html EXQuery Request Module] draft.
  
 
=Conventions=
 
=Conventions=
  
−
All functions in this module are assigned to the {{Code|http://exquery.org/ns/request}} namespace, which must be dynamically imported:
+
* 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 class="brush:xquery">
+
<pre>
−
import module namespace request = "http://exquery.org/ns/restxq/request";
+
  foo://example.com:8042/over/there?name=ferret&code=7
−
...
+
  \_/   \_________/ \__/\_________/ \________________/
 +
  |        |      |      |              |
 +
scheme  hostname  port    path          query
 
</pre>
 
</pre>
−
 
−
In this documentation, the namespace is bound to the {{Code|request}} prefix.
 
  
 
=General Functions=
 
=General Functions=
  
 
==request:method==
 
==request:method==
−
{|
+
 
−
|-
+
{| width='100%'
−
| width='90' | '''Signatures'''
+
|- valign="top"
−
|{{Func|request:method||xs:string}}
+
| 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 25: Line 32:
  
 
=URI Functions=
 
=URI Functions=
−
 
−
The following example show what components a URI consists of (the examples is derived from [http://tools.ietf.org/html/rfc3986 RFC 3986]):
 
−
<pre>
 
−
  foo://example.com:8042/over/there?name=ferret
 
−
  \_/  \_________/ \__/\_________/ \_________/
 
−
  |        |      |    |          |
 
−
scheme  hostname  port    path      query
 
−
</pre>
 
  
 
==request:scheme==
 
==request:scheme==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:scheme||xs:string}}
+
|<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'''
 +
|For the example given in the introduction, this function would return {{Code|foo}}.
 
|}
 
|}
  
 
==request:hostname==
 
==request:hostname==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:hostname||xs:string}}
+
|<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'''
 +
|For the example given in the introduction, this function would return {{Code|example.com}}.
 
|}
 
|}
  
 
==request:port==
 
==request:port==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:port||xs:integer}}
+
|<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'''
 +
|For the example given in the introduction, this function would return {{Code|8042}}.
 
|}
 
|}
  
 
==request:path==
 
==request:path==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:port||xs:string}}
+
|<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"
−
| '''Examples'''
+
| '''Example'''
−
|The following RESTXQ function could e.g. be called via <code><nowiki>http://localhost:8984/restxq/path-check</nowiki></code>:
+
|For the example given in the introduction, this function would return {{Code|/over/there}}.<br/>
−
<pre class="brush:xquery">
 
−
module namespace test = 'http://basex.org/examples/test';
 
−
import module namespace request = "http://exquery.org/ns/restxq/request";
 
−
declare %restxq:path("/path-check") function test:get($req, $name) {
 
−
  'Path of this page: ' || request:path()
 
−
};
 
−
</pre>
 
 
|}
 
|}
  
 
==request:query==
 
==request:query==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:query||xs:string?}}
+
|<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 has been specified, an empty sequence is returned.
+
|Returns the Query component of the URI of an HTTP request. If no query component exists, an empty sequence is returned.
 +
|- valign="top"
 +
| '''Example'''
 +
|For the example given in the introduction, this function would return <code>name=ferret&code=7</code>.<br/>
 
|}
 
|}
  
 
==request:uri==
 
==request:uri==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:uri||xs:anyURI}}
+
|<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'''
 +
|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 107: Line 125:
  
 
==request:address==
 
==request:address==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:address||xs:string}}
+
|<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 117: Line 135:
  
 
==request:remote-hostname==
 
==request:remote-hostname==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:remote-hostname||xs:string}}
+
|<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 127: Line 145:
  
 
==request:remote-address==
 
==request:remote-address==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:remote-address||xs:string}}
+
|<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 137: Line 155:
  
 
==request:remote-port==
 
==request:remote-port==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:remote-port||xs:string}}
+
|<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.
 
|}
 
|}
  
−
=HTTP Parameter Functions=
+
=Parameter Functions=
  
 
==request:parameter-names==
 
==request:parameter-names==
−
{|
+
 
−
|-
+
{| width='100%'
−
| width='90' | '''Signatures'''
+
|- valign="top"
−
|{{Func|request:parameter-names||xs:string*}}
+
| 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. This function can be used to find or check query parameters that have not been bound by [[RESTXQ#Query Strings|%restxq:query-param]] annotations.
+
|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'''
 +
|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='90' | '''Signatures'''
+
|- valign="top"
−
|{{Func|request:parameter|$name as xs:string|xs:string*}}<br/>{{Func|request:parameter|$name as xs:string, $default as xs:string|xs:string*}}
+
| 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"
−
| '''Examples'''
+
| '''Example'''
−
|The following RESTXQ function can e.g. be called via <code><nowiki>http://localhost:8984/restxq/get?user=John</nowiki></code>:
+
|For the example given in the introduction, the function call {{Code|request:parameter('code')}} would return {{Code|7}}.<br/>
−
<pre class="brush:xquery">
+
|- valign="top"
−
module namespace test = 'http://basex.org/examples/test';
+
| '''Errors'''
−
import module namespace request = "http://exquery.org/ns/restxq/request";
+
|{{Error|parameter|#Errors}} the request has invalid parameters.
−
declare %restxq:path("/get") function test:get() {
 
−
  'The user name is ' || request:parameter('user')
 
−
};
 
−
</pre>
 
 
|}
 
|}
  
−
=HTTP Header Functions=
+
=Header Functions=
  
 
==request:header-names==
 
==request:header-names==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:header-names||xs:string*}}
+
|<pre>request:header-names() as xs:string*</pre>
−
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Returns the names of all headers available from the HTTP request.
+
|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%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:header|$name as xs:string|xs:string?}}<br/>{{Func|header:parameter|$name as xs:string, $default as xs:string|xs:string}}
+
|<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 HTTP 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.
−
|-
 
−
| '''Examples'''
 
−
|The following example will return the Hostname and the port of the calling client:
 
−
<pre class="brush:xquery">
 
−
request:parameter('Host')
 
−
</pre>
 
 
|}
 
|}
  
−
=HTTP Cookie Functions=
+
=Cookie Functions=
  
 
==request:cookie-names==
 
==request:cookie-names==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:cookie-names||xs:string*}}
+
|<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.
+
|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%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:cookie|$name as xs:string|xs:string*}}<br/>{{Func|header:cookie|$name as xs:string, $default as xs:string|xs:string}}
+
|<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.
−
|-
 
−
| '''Examples'''
 
−
|The following example will return the Hostname and the port of the calling client:
 
−
<pre class="brush:xquery">
 
−
request:parameter('Host')
 
−
</pre>
 
 
|}
 
|}
  
−
==request:session-id==
+
=Attribute Functions=
 +
 
 +
==request:attribute-names==
  
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:session-id||xs:string}}
+
|<pre>request:attribute-names() as xs:string*</pre>
−
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Returns the session ID of a servlet request.
+
|Returns the names of all HTTP request attributes.
−
|-
 
−
| '''Examples'''
 
−
|The following RESTXQ function can be called via <code><nowiki>http://localhost:8984/restxq/id</nowiki></code>:
 
−
<pre class="brush:xquery">
 
−
module namespace test = 'http://basex.org/examples/test';
 
−
import module namespace request = "http://exquery.org/ns/restxq/request";
 
−
declare
 
−
  %restxq:path("/id")
 
−
  function test:id()
 
−
{
 
−
  'ID: ' || request:session-id()
 
−
};
 
−
</pre>
 
 
|}
 
|}
  
 
==request:attribute==
 
==request:attribute==
  
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:attribute|$key as xs:string|xs:string?}}
+
|<pre>request:attribute(
−
|-
+
  $name    as xs:string,
 +
  $default  as item()*    := ()
 +
) as item()*</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Returns the value of an attribute bound to the current session, or an empty sequence if no value was bound.
+
|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"
−
| '''Examples'''
+
| '''Example'''
−
|The following RESTXQ function can e.g. be called via <code><nowiki>http://localhost:8984/restxq/get?key=user</nowiki></code>:
+
|
−
<pre class="brush:xquery">
+
* {{Code|request:attribute("javax.servlet.error.request_uri")}} returns the original URI of a caught error.
−
module namespace test = 'http://basex.org/examples/test';
+
* {{Code|request:attribute("javax.servlet.error.message")}} returns the error message of a caught error.
−
import module namespace request = "http://exquery.org/ns/restxq/request";
 
−
declare
 
−
  %restxq:path("/get")
 
−
  %restxq:query-param("key", "{$key}", "")
 
−
  %restxq:request("{$req}")
 
−
  function test:get($req, $key)
 
−
{
 
−
  'Value of ' || $key || ': ' || request:get-attribute($req, $key)
 
−
};
 
−
</pre>
 
 
|}
 
|}
  
−
==request:update-attribute==
+
==request:set-attribute==
  
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|request:update-attribute|$key as xs:string, $value as xs:string|empty-sequence()}}
+
|<pre>request:set-attribute(
−
|-
+
  $name  as xs:string,
 +
  $value as item()*
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Binds an attribute with the specified value to the current session.
+
|Binds the specified {{Code|$value}} to the request attribute with the specified {{Code|$name}}.
−
|-
+
|}
−
| '''Examples'''
+
 
−
|The following RESTXQ function can e.g. be called via <code><nowiki>http://localhost:8984/restxq/set?key=user&value=john</nowiki></code>:
+
=Errors=
−
<pre class="brush:xquery">
+
 
−
module namespace test = 'http://basex.org/examples/test';
+
{| class="wikitable" width="100%"
−
import module namespace request = "http://exquery.org/ns/restxq/request";
+
! width="110"|Code
−
declare
+
|Description
−
  %restxq:path("/set")
+
|- valign="top"
−
  %restxq:query-param("key", "{$key}", "")
+
|{{Code|parameter}}
−
  %restxq:query-param("value", "{$value}", "")
+
|Request has invalid parameters.
−
  %restxq:request("{$req}")
 
−
  function test:set($req, $key, $value)
 
−
{
 
−
  request:set-attribute($req, $key, $value),
 
−
  'Attribute was set.'
 
−
};
 
−
</pre>
 
 
|}
 
|}
  
 
=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.
−
 
−
[[Category:XQuery]]
 

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.

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 the request 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:attribute("javax.servlet.error.request_uri") returns the original URI of a caught error.
  • request:attribute("javax.servlet.error.message") returns the error message of a caught error.

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
Version 7.9
Version 7.8
Version 7.7

This module was introduced with Version 7.5.

Retrieved from "http://docs.basex.org/index.php?title=Request_Module&oldid=16470"