Request Module

From BaseX Documentation
Revision as of 23:42, 8 September 2012 by CG (talk | contribs) (→‎URI Functions)
Jump to navigation Jump to search

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.

General Functions

request:method

Signatures request:method() as xs:string
Summary Returns the Method of the HTTP request.

URI Functions

The following example show what components a URI consists of (the examples is derived from RFC 3986): 

 foo://example.com:8042/over/there/index.dtb?type=animal
 \_/   \_________/ \__/\___________________/ \_________/
  |         |       |           |                 |
scheme   hostname  port        path             query

request:scheme

Signatures request:scheme() as xs:string
Summary Returns the Scheme component of the URI of an HTTP request.

request:hostname

Signatures request:hostname() as xs:string
Summary Returns the Hostname component of the URI of an HTTP request.

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.

request:path

Signatures request:port() as xs:string
Summary Returns the Path component of the URI of an HTTP request.
Examples The following RESTXQ function can e.g. be called via http://localhost:8984/restxq/hey/john: 
module namespace test = 'http://basex.org/examples/test';
import module namespace request = "http://exquery.org/ns/restxq/request";
declare %restxq:path("/path-check") function test:get($req, $name) {
  'Path of this page: ' || request:path()
};

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.

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.

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.

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.
Examples The following RESTXQ function can e.g. be called via http://localhost:8984/restxq/get?user=John: 
module namespace test = 'http://basex.org/examples/test';
import module namespace request = "http://exquery.org/ns/restxq/request";
declare %restxq:path("/get") function test:get() {
  'The user name is ' || request:parameter('user')
};

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')

request:session-id

Signatures request:session-id() as xs:string
Summary Returns the session ID of a servlet request.
Examples The following RESTXQ function can be called via http://localhost:8984/restxq/id: 
module namespace test = 'http://basex.org/examples/test';
import module namespace request = "http://exquery.org/ns/restxq/request";
declare
  %restxq:path("/id")
  function test:id()
{
  'ID: ' || request:session-id()
};

request:attribute

Signatures request:attribute($key as xs:string) as xs:string?
Summary Returns the value of an attribute bound to the current session, or an empty sequence if no value was bound.
Examples The following RESTXQ function can e.g. be called via http://localhost:8984/restxq/get?key=user: 
module namespace test = 'http://basex.org/examples/test';
import module namespace request = "http://exquery.org/ns/restxq/request";
declare
  %restxq:path("/get")
  %restxq:query-param("key", "{$key}", "")
  %restxq:request("{$req}")
  function test:get($req, $key)
{
  'Value of ' || $key || ': ' || request:get-attribute($req, $key)
};

request:update-attribute

Signatures request:update-attribute($key as xs:string, $value as xs:string) as empty-sequence()
Summary Binds an attribute with the specified value to the current session.
Examples The following RESTXQ function can e.g. be called via http://localhost:8984/restxq/set?key=user&value=john: 
module namespace test = 'http://basex.org/examples/test';
import module namespace request = "http://exquery.org/ns/restxq/request";
declare
  %restxq:path("/set")
  %restxq:query-param("key", "{$key}", "")
  %restxq:query-param("value", "{$value}", "")
  %restxq:request("{$req}")
  function test:set($req, $key, $value)
{
  request:set-attribute($req, $key, $value),
  'Attribute was set.'
};

Changelog

This module was introduced with Version 7.5.

Retrieved from "http://docs.basex.org/index.php?title=Request_Module&oldid=8242"