Main Page » XQuery » Functions » Request Functions

Request Functions

This 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.
  • 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

request:method

Signature
request:method() as xs:string
SummaryReturns the Method of the HTTP request.

URI Functions

request:scheme

Signature
request:scheme() as xs:string
SummaryReturns the Scheme component of the URI of an HTTP request.
ExamplesFor the example given in the introduction, this function would return foo.

request:hostname

Signature
request:hostname() as xs:string
SummaryReturns the Hostname component of the URI of an HTTP request.
ExamplesFor the example given in the introduction, this function would return example.com.

request:port

Signature
request:port() as xs:integer
SummaryReturns the Port component of the URI of an HTTP request, or a default port if it has not been explicitly specified in the URI.
ExamplesFor the example given in the introduction, this function would return 8042.

request:path

Signature
request:path() as xs:string
SummaryReturns the Path component of the URI of an HTTP request.
ExamplesFor the example given in the introduction, this function would return /over/there.

request:query

Signature
request:query() as xs:string?
SummaryReturns the Query component of the URI of an HTTP request. If no query component exists, an empty sequence is returned.
ExamplesFor the example given in the introduction, this function would return name=ferret&code=7.

request:uri

Signature
request:uri() as xs:anyURI
SummaryReturns the complete URI of an HTTP request as it has been specified by the client.
ExamplesFor the example given in the introduction, this method would return foo://example.com:8042/over/there?name=ferret&code=7.

request:context-path

Signature
request:context-path() as xs:string
SummaryReturns the context of the request. For servlets in the default (root) context, this method returns an empty string.

Connection Functions

request:address

Signature
request:address() as xs:string
SummaryReturns the IP address of the server.

request:remote-hostname

Signature
request:remote-hostname() as xs:string
SummaryReturns the fully qualified hostname of the client that sent the request.

request:remote-address

Signature
request:remote-address() as xs:string
SummaryReturns the IP address of the client that sent the request.

request:remote-port

Signature
request:remote-port() as xs:string
SummaryReturns the TCP port of the client socket that triggered the request.

Parameter Functions

request:parameter-map

Added: New function.

Signature
request:parameter-map() as map(xs:string, item()+)
SummaryReturns 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.
Errors
parameterRequest has invalid parameters.
ExamplesFor the example given in the introduction, this function would return { 'name': 'Ferret' }.

request:parameter-names

Signature
request:parameter-names() as xs:string*
SummaryReturns 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.
Errors
parameterRequest has invalid parameters.
ExamplesFor the example given in the introduction, this function would return name.

request:parameter

Signature
request:parameter(
  $name     as xs:string,
  $default  as xs:string  := ()
) as xs:string*
SummaryReturns 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.
Errors
parameterRequest has invalid parameters.
ExamplesFor the example given in the introduction, the function call request:parameter('code') would return 7.

Header Functions

request:header-map

Added: New function.

Signature
request:header-map() as map(xs:string, xs:string)
SummaryReturns 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-names

Signature
request:header-names() as xs:string*
SummaryReturns 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

Signature
request:header(
  $name     as xs:string,
  $default  as xs:string  := ()
) as xs:string?
SummaryReturns 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-map

Added: New function.

Signature
request:cookie-map() as map(xs:string, xs:string)
SummaryReturns 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-names

Signature
request:cookie-names() as xs:string*
SummaryReturns 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

Signature
request:cookie(
  $name     as xs:string,
  $default  as xs:string  := ()
) as xs:string?
SummaryReturns 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-map

Added: New function.

Signature
request:attribute-map() as map(xs:string, item()*)
SummaryReturns all HTTP request attributes. If a value is not an XDM item value, it is wrapped as a Java item.

request:attribute-names

Signature
request:attribute-names() as xs:string*
SummaryReturns the names of all HTTP request attributes.

request:attribute

Signature
request:attribute(
  $name     as xs:string,
  $default  as item()*    := ()
) as item()*
SummaryReturns the value of an attribute of the HTTP request. If the value is not an XDM item value, it is wrapped as a Java item. If the attribute does not exist, an empty sequence or the optionally specified default value is returned instead.
Examples
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

Signature
request:set-attribute(
  $name   as xs:string,
  $value  as item()*
) as empty-sequence()
SummaryBinds the specified $value to the request attribute with the specified $name.

Errors

CodeDescription
parameterRequest has invalid parameters.

Changelog

Version 12.0Version 9.3Version 7.9Version 7.8Version 7.7Version 7.5
  • Added: New module added.
⚡Generated with XQuery
 
Login | Changelog | TOC | Imprint
Request Functions