Difference between revisions of "Request Module"
Jump to navigation
Jump to search
Line 44: | Line 44: | ||
|- | |- | ||
| '''Example''' | | '''Example''' | ||
− | |For the example given in the introduction, this | + | |For the example given in the introduction, this function would return {{Code|foo}}. |
|} | |} | ||
Line 55: | Line 55: | ||
| '''Summary''' | | '''Summary''' | ||
|Returns the Hostname component of the URI of an HTTP request. | |Returns the Hostname component of the URI of an HTTP request. | ||
+ | |- | ||
+ | | '''Example''' | ||
+ | |For the example given in the introduction, this function would return {{Code|example.com}}. | ||
|} | |} | ||
Line 65: | Line 68: | ||
| '''Summary''' | | '''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. | |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 {{Code|8042}}. | ||
|} | |} | ||
Line 76: | Line 82: | ||
|Returns the Path component of the URI of an HTTP request. | |Returns the Path component of the URI of an HTTP request. | ||
|- | |- | ||
− | | ''' | + | | '''Example''' |
− | | | + | |For the example given in the introduction, this function would return {{Code|/over/there}}.<br/> |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | </ | ||
|} | |} | ||
Line 95: | Line 94: | ||
| '''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 has been specified, an empty sequence is returned. | ||
+ | |- | ||
+ | | '''Example''' | ||
+ | |For the example given in the introduction, this function would return {{Code|name=ferret}}.<br/> | ||
|} | |} | ||
Line 105: | Line 107: | ||
| '''Summary''' | | '''Summary''' | ||
|Returns the complete URI of an HTTP request as it has been specified by the client. | |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 {{Code|foo://example.com:8042/over/there?name=ferret}}.<br/> | ||
|} | |} | ||
Line 159: | Line 164: | ||
| '''Summary''' | | '''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 Strings|%restxq:query-param]] annotations. | |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 Strings|%restxq:query-param]] annotations. | ||
+ | |- | ||
+ | | '''Example''' | ||
+ | |For the example given in the introduction, this function would return {{Code|name}}.<br/> | ||
|} | |} | ||
Line 170: | Line 178: | ||
|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 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 {{Code|request:parameter('name')}} would return {{Code|ferret}}.<br/> |
− | |||
− | |||
− | |||
− | |||
− | |||
− | } | ||
</pre> | </pre> | ||
|} | |} | ||
Line 234: | Line 236: | ||
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
request:parameter('Host') | request:parameter('Host') | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
</pre> | </pre> | ||
|} | |} |
Revision as of 00:06, 9 September 2012
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.
Contents
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.