Difference between revisions of "Request Module"
Jump to navigation
Jump to search
Line 250: | Line 250: | ||
=Attribute Functions= | =Attribute Functions= | ||
− | ==request:attribute | + | ==request:attribute== |
− | |||
− | |||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|request:attribute | + | |{{Func|request:attribute|$name as xs:string|xs:string}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the | + | |Returns the value of an attribute of the HTTP request. If the attribute does not exist, an empty sequence is returned. |
+ | |- | ||
+ | | '''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:attribute== | + | ==request:attribute-names== |
+ | |||
+ | {{Mark|Introduced with BaseX 9.3:}} | ||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|request:attribute| | + | |{{Func|request:attribute-names||xs:string*}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the | + | |Returns the names of all HTTP request attributes. |
− | |||
− | |||
− | |||
− | |||
− | |||
|} | |} | ||
Revision as of 12:51, 11 July 2019
This 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 Applications.
The module is related to Adam Retter’s EXQuery Request Module draft.
Contents
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 therequest
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 has been specified, 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
Signatures | request:attribute($name as xs:string) as xs:string
|
Summary | Returns the value of an attribute of the HTTP request. If the attribute does not exist, an empty sequence is returned. |
Example |
|
request:attribute-names
Signatures | request:attribute-names() as xs:string*
|
Summary | Returns the names of all HTTP request attributes. |
request:set-attribute
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
- 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.