Difference between revisions of "Request Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replace - "{| width='100%'" to "{|")
(47 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 mainly useful in the context of [[Web Application]]s.
+
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 mainly derived from Adam Retter’s upcoming [http://exquery.github.com/expath-specs-playground/request-module-1.0-specification.html EXQuery Request Module].
+
The module is based on the [http://exquery.github.com/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. Prior to {{Version|9.2}}, the module needed to be imported in the query prolog:
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
 
import module namespace request = "http://exquery.org/ns/request";
 
import module namespace request = "http://exquery.org/ns/request";
 
...
 
...
 
</pre>
 
</pre>
 +
* If any of the functions is called outside the servlet context, <code>[[XQuery Errors#BaseX Errors|basex:http]]</code> is raised.
  
In this documentation, the namespace is bound to the {{Code|request}} prefix.
+
The following example illustrated what components a URI may consist of (the example is derived from [http://tools.ietf.org/html/rfc3986 RFC 3986]):
  
The following example will be referenced in the function definitions. It demonstrates 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
Line 25: Line 25:
  
 
==request:method==
 
==request:method==
{|
+
 
 +
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|request:method||xs:string}}
 
|{{Func|request:method||xs:string}}
 
|-
 
|-
Line 37: Line 38:
  
 
==request:scheme==
 
==request:scheme==
{|
+
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|request:scheme||xs:string}}
 
|{{Func|request:scheme||xs:string}}
 
|-
 
|-
Line 50: Line 51:
  
 
==request:hostname==
 
==request:hostname==
{|
+
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|request:hostname||xs:string}}
 
|{{Func|request:hostname||xs:string}}
 
|-
 
|-
Line 63: Line 64:
  
 
==request:port==
 
==request:port==
{|
+
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|request:port||xs:integer}}
 
|{{Func|request:port||xs:integer}}
 
|-
 
|-
Line 76: Line 77:
  
 
==request:path==
 
==request:path==
{|
+
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|request:path||xs:string}}
 
|{{Func|request:path||xs:string}}
 
|-
 
|-
Line 89: Line 90:
  
 
==request:query==
 
==request:query==
{|
+
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|request:query||xs:string?}}
 
|{{Func|request:query||xs:string?}}
 
|-
 
|-
 
| '''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.
 
|-
 
|-
 
| '''Example'''
 
| '''Example'''
|For the example given in the introduction, this function would return {{Code|name=ferret}}.<br/>
+
|For the example given in the introduction, this function would return <code>name=ferret</code>.<br/>
 
|}
 
|}
  
 
==request:uri==
 
==request:uri==
{|
+
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|request:uri||xs:anyURI}}
 
|{{Func|request:uri||xs:anyURI}}
 
|-
 
|-
Line 111: Line 112:
 
|-
 
|-
 
| '''Example'''
 
| '''Example'''
|For the example given in the introduction, this method would return {{Code|foo://example.com:8042/over/there?name=ferret}}.<br/>
+
|For the example given in the introduction, this method would return <code>foo://example.com:8042/over/there?name=ferret</code>.<br/>
 +
|}
 +
 
 +
==request:context-path==
 +
 
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|request:context-path||xs:string}}
 +
|-
 +
| '''Summary'''
 +
|Returns the context of the request. For servlets in the default (root) context, this method returns an empty string.
 
|}
 
|}
  
Line 117: Line 129:
  
 
==request:address==
 
==request:address==
{|
+
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|request:address||xs:string}}
 
|{{Func|request:address||xs:string}}
 
|-
 
|-
Line 127: Line 139:
  
 
==request:remote-hostname==
 
==request:remote-hostname==
{|
+
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|request:remote-hostname||xs:string}}
 
|{{Func|request:remote-hostname||xs:string}}
 
|-
 
|-
Line 137: Line 149:
  
 
==request:remote-address==
 
==request:remote-address==
{|
+
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|request:remote-address||xs:string}}
 
|{{Func|request:remote-address||xs:string}}
 
|-
 
|-
Line 147: Line 159:
  
 
==request:remote-port==
 
==request:remote-port==
{|
+
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|request:remote-port||xs:string}}
 
|{{Func|request:remote-port||xs:string}}
 
|-
 
|-
Line 159: Line 171:
  
 
==request:parameter-names==
 
==request:parameter-names==
{|
+
 
 +
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|request:parameter-names||xs:string*}}
 
|{{Func|request:parameter-names||xs:string*}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the names of all query parameters available from the HTTP request. If [[RESTXQ]] is used, this function may help to find query parameters that have not been bound by [[RESTXQ#Query Parameters|%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]].
 
|-
 
|-
 
| '''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/>
 +
|-
 +
| '''Errors'''
 +
|{{Error|parameter|#Errors}} the request has invalid parameters.
 
|}
 
|}
  
 
==request:parameter==
 
==request:parameter==
{|
+
 
 +
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|request:parameter|$name as xs:string|xs:string*}}<br/>{{Func|request:parameter|$name as xs:string, $default as xs:string|xs:string*}}
 
|{{Func|request:parameter|$name as xs:string|xs:string*}}<br/>{{Func|request:parameter|$name as xs:string, $default as xs:string|xs:string*}}
 
|-
 
|-
 
| '''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.
 
|-
 
|-
 
| '''Example'''
 
| '''Example'''
 
|For the example given in the introduction, the function call {{Code|request:parameter('name')}} would return {{Code|ferret}}.<br/>
 
|For the example given in the introduction, the function call {{Code|request:parameter('name')}} would return {{Code|ferret}}.<br/>
 +
|-
 +
| '''Errors'''
 +
|{{Error|parameter|#Errors}} the request has invalid parameters.
 
|}
 
|}
  
Line 187: Line 207:
  
 
==request:header-names==
 
==request:header-names==
{|
+
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|request:header-names||xs:string*}}
 
|{{Func|request:header-names||xs:string*}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the names of all headers available from the HTTP request. If [[RESTXQ]] is used, this function may help to find headers that have not been bound by [[RESTXQ#HTTP Headers|%restxq:header-param]] annotations.
+
|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='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
|{{Func|request:header|$name as xs:string|xs:string?}}<br/>{{Func|header:parameter|$name as xs:string, $default as xs:string|xs:string}}
+
|{{Func|request:header|$name as xs:string|xs:string?}}<br/>{{Func|request:header|$name as xs:string, $default as xs:string|xs:string}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 209: Line 229:
  
 
==request:cookie-names==
 
==request:cookie-names==
{|
+
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|request:cookie-names||xs:string*}}
 
|{{Func|request:cookie-names||xs:string*}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the names of all cookies in the HTTP headers available from the HTTP request. If [[RESTXQ]] is used, this function may help to find cookies that have not been bound by [[RESTXQ#Cookies|%restxq:cookie-param]] annotations.
+
|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='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
|{{Func|request:cookie|$name as xs:string|xs:string*}}<br/>{{Func|header:cookie|$name as xs:string, $default as xs:string|xs:string}}
+
|{{Func|request:cookie|$name as xs:string|xs:string?}}<br/>{{Func|request:cookie|$name as xs:string, $default as xs:string|xs:string}}
 
|-
 
|-
 
| '''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==
 +
 +
{{Mark|Introduced with BaseX 9.3:}}
 +
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|request:attribute-names||xs:string*}}
 +
|-
 +
| '''Summary'''
 +
|Returns the names of all HTTP request attributes.
 +
|}
 +
 +
==request:attribute==
 +
 +
{{Mark|Updated with BaseX 9.3:}} return type generalized, default argument added.
 +
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|request:attribute|$name as xs:string|item()*}}<br/>{{Func|request:attribute|$name as xs:string, $default as item()*|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'''
 +
|
 +
* {{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==
 +
 +
{{Mark|Introduced with BaseX 9.3:}}
 +
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|request:set-attribute|$name as xs:string, $value as item()*|empty-sequence()}}
 +
|-
 +
| '''Summary'''
 +
|Binds the specified {{Code|$value}} to the request attribute with the specified {{Code|$name}}.
 +
|-
 +
| '''Errors'''
 +
|{{Error|attribute|#Errors}} The supplied value cannot be materialized.
 +
|}
 +
 +
=Errors=
 +
 +
{| class="wikitable" width="100%"
 +
! width="110"|Code
 +
|Description
 +
|-
 +
|{{Code|attribute}}
 +
|An attribute cannot be retrieved or stored.
 +
|-
 +
|{{Code|parameter}}
 +
|Request has invalid parameters.
 
|}
 
|}
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 9.3
 +
 +
* Added: [[#request:attribute-names|request:attribute-names]], [[#request:set-attribute|request:set-attribute]]
 +
* Updated: [[#request:attribute|request:attribute]]: return type generalized, default argument added
 +
 +
;Version 7.9
 +
 +
* Updated: The returned values of [[#request:parameter-names|request:parameter-names]], [[#request:parameter|request:parameter]] now also include form field parameters.
 +
 +
;Version 7.8
 +
 +
* Added: [[#request:context-path|request:context-path]]
 +
 +
;Version 7.7
 +
 +
* Added: [[#request:attribute|request:attribute]]
  
 
This module was introduced with Version 7.5.
 
This module was introduced with Version 7.5.
 
[[Category:XQuery]]
 

Revision as of 16:23, 8 August 2019

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

  • 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. Prior to Version 9.2, the module needed to be imported in the query prolog:
import module namespace request = "http://exquery.org/ns/request";
...
  • 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
  \_/   \_________/ \__/\_________/ \_________/
   |         |       |       |          |
 scheme   hostname  port    path      query

General Functions

request:method

Signatures request:method() as xs:string
Summary Returns the Method of the HTTP request.

URI Functions

request:scheme

Signatures 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

Signatures 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

Signatures 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

Signatures 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

Signatures 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.

request:uri

Signatures 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.

request:context-path

Signatures 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

request:address

Signatures request:address() as xs:string
Summary Returns the IP address of the server.

request:remote-hostname

Signatures request:remote-hostname() as xs:string
Summary Returns the fully qualified hostname of the client that sent the request.

request:remote-address

Signatures request:remote-address() as xs:string
Summary Returns the IP address of the client that sent the request.

request:remote-port

Signatures request:remote-port() as xs:string
Summary Returns the TCP port of the client socket that triggered the request.

Parameter Functions

request:parameter-names

Signatures 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

Signatures request:parameter($name as xs:string) as xs:string*
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('name') would return ferret.
Errors parameter: the request has invalid parameters.

Header Functions

request:header-names

Signatures 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

Signatures request:header($name as xs:string) as xs:string?
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

request:cookie-names

Signatures 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

Signatures request:cookie($name as xs:string) as xs:string?
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

request:attribute-names

Template:Mark

Signatures request:attribute-names() as xs:string*
Summary Returns the names of all HTTP request attributes.

request:attribute

Template:Mark return type generalized, default argument added.

Signatures request:attribute($name as xs:string) as item()*
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

Template:Mark

Signatures 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 attribute: The supplied value cannot be materialized.

Errors

Code Description
attribute An attribute cannot be retrieved or stored.
parameter Request has invalid parameters.

Changelog

Version 9.3
Version 7.9
Version 7.8
Version 7.7

This module was introduced with Version 7.5.