Request Module

This 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 EXQuery Request Module.

Conventions

All functions in this module are assigned to the http://exquery.org/ns/request namespace, which must be dynamically imported:

import module namespace request = "http://exquery.org/ns/restxq/request";
...

In this documentation, the namespace is bound to the request prefix.

The following example will be referenced in the function definitions. It demonstrates 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:port() 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 {{{1}}}.

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 {{{1}}}.

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.

HTTP Parameter Functions

request:parameter-names

Signatures	request:parameter-names() as xs:string*
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-param annotations.
Example	For the example given in the introduction, this function would return name.

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 parameter in an HTTP request. If the parameter does not exist, an empty sequence or the optionally specified default value is returned instead.
Example	For the example given in the introduction, the function call request:parameter('name') would return ferret.

HTTP Header Functions

request:header-names

Signatures	request:header-names() as xs:string*
Summary	Returns the names of all headers available from the HTTP request.

request:header

Signatures	request:header($name as xs:string) as xs:string? header:parameter($name as xs:string, $default as xs:string) as xs:string
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.
Examples	The following example will return the Hostname and the port of the calling client: request:parameter('Host')

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

request:cookie

Signatures	request:cookie($name as xs:string) as xs:string* header: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.
Examples	The following example will return the Hostname and the port of the calling client: request:parameter('Host')

Changelog

This module was introduced with Version 7.5.