Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
* In this documentation, the namespace is bound to the {{Code|request}} prefix.
* The following example demonstrates what components a URI may consist of (the example is derived from [http://tools.ietf.org/html/rfc3986 RFC 3986]):
[[Category:XQuery]]
no edit summary
This [[Module Library|XQuery Module]] contains functions for retrieving information on an HTTP request that has triggered the query. It is mainly mostly useful in the context of when building [[Web Application]]s.
The module is mainly derived from Adam Retter’s upcoming based on the [http://exquery.github.com/expath-specs-playground/request-module-1.0-specification.html EXQuery Request Module]draft.
=Conventions=
* This The module will be available if the {{Code|basex-api}} library is included found in the classpath. This is the case if you use one of the complete distributions of BaseX (zip, exe, war) of BaseX.* All functions are assigned to the {{Code|<code><nowiki>http://exquery.org/ns/request</nowiki></code> namespace, which is statically bound to the {{Code|request}} namespaceprefix. Prior to {{Version|9.2}}, which must the module needed to be dynamically importedin the query prolog:
<pre class="brush:xquery">
import module namespace request = "http://exquery.org/ns/request";
...
</pre>
* 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>
foo://example.com:8042/over/there?name=ferret
==request:method==
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:method||xs:string}}
|-
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:scheme||xs:string}}
|-
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:hostname||xs:string}}
|-
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:port||xs:integer}}
|-
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:path||xs:string}}
|-
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:query||xs:string?}}
|-
| '''Summary'''
|Returns the Query component of the URI of an HTTP request. If no query has been specifiedcomponent exists, an empty sequence is returned.
|-
| '''Example'''
|For the example given in the introduction, this function would return {{Code|<code>name=ferret}}</code>.<br/>
|}
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:uri||xs:anyURI}}
|-
|-
| '''Example'''
|For the example given in the introduction, this method would return {{Code|<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.
|}
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:address||xs:string}}
|-
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:remote-hostname||xs:string}}
|-
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:remote-address||xs:string}}
|-
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:remote-port||xs:string}}
|-
==request:parameter-names==
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:parameter-names||xs:string*}}
|-
| '''Summary'''
|Returns the names of all query and form field parameters available from the HTTP request. If With [[RESTXQ]] is used, this function may help can be used to find query access parameters that have not been statically bound by [[RESTXQ#Query Parameters|%restxqrest:query-param]] annotations.
|-
| '''Example'''
|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==
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:parameter|$name as xs:string|xs:string*}}<br/>{{Func|request:parameter|$name as xs:string, $default as xs:string|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 {{Code|request:parameter('name')}} would return {{Code|ferret}}.<br/>
|-
| '''Errors'''
|{{Error|parameter|#Errors}} the request has invalid parameters.
|}
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:header-names||xs:string*}}
|-
| '''Summary'''
|Returns the names of all headers available from the HTTP request. If [[RESTXQ]] is used, this function may help can be used to find access headers that have not been statically bound by [[RESTXQ#HTTP Headers|%restxqrest:header-param]] annotations.
|}
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:header|$name as xs:string|xs:string?}}<br/>{{Func|request:header|$name as xs:string, $default as xs:string|xs:string}}
|-
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|request:cookie-names||xs:string*}}
|-
| '''Summary'''
|Returns the names of all cookies in the HTTP headers available from the HTTP request. If [[RESTXQ]] is used, this function may help can be used to find access cookies that have not been statically bound by [[RESTXQ#Cookies|%restxqrest:cookie-param]] annotations.
|}
{| width='100%'
|-
| width='90120' | '''Signatures'''|{{Func|request:cookie|$name as xs:string|xs:string*?}}<br/>{{Func|request:cookie|$name as xs:string, $default as xs:string|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==
{{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=
;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.
