Chapter 16. WebApp extension functions

Table of Contents

1. Request
2. Response
3. Session

These XQuery functions are used to implement Web Applications directly in XQuery.

They are available only within Qizx Server.

1. Request

These functions have the predefined prefix request.

They provide access to the properties of an HTTP request: parameters, headers, query, remote user and host, cookies.

Two functions also allow redirecting the request, either by using an HTTP redirect: request:redirect-to(), or by forwarding it to another XQSP script: request:forward().

 

request:get-content-length( )

Returns the length, in bytes, of the request body.

Returned value [ type xs:integer ]: The length in bytes.

request:get-content-type( )

Returns the MIME type of the body of the request.

Returned value [ type xs:string ]: The MIME type as a string: e.g "text/html".

request:get-content-encoding( )

Returns the name of the character encoding used in the body of this request. .

This function returns an empty sequence if the request does not specify a character encoding.

Returned value [ type xs:string ]: The name of the character encoding.

request:get-method( )

Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT.

Returned value [ type xs:string ]: "GET", "POST", or "PUT" (other methods are not supported).

request:get-protocol( )

Returns the name and version of the protocol the request uses in the form protocol/majorVersion.minorVersion, for example, HTTP/1.1.

Returned value [ type xs:string ]: The protocol.

request:get-scheme( )

Returns the name of the scheme used to make this request, for example, http, https, or ftp.

Returned value [ type xs:string ]: The scheme.

request:get-context-path( )

Returns the portion of the request URI that indicates the context of the request. .

The context path always comes first in a request URI. The path starts with a "/" character but does not end with a "/" character. For servlets in the default (root) context, this method returns "". The container does not decode this string.

Returned value [ type xs:string ]: The context of the request.

request:get-path-info( )

Returns any extra path information associated with the URL the client sent when it made this request.

The extra path information follows the servlet path but precedes the query string. .

Returned value [ type xs:string ]: The path information.

request:get-query-string( )

Returns the query string that is contained in the request URL after the path. This method returns empty() if the URL does not have a query string. .

Returned value [ type xs:string ]: The query string.

request:get-servlet-path( )

Returns the part of this request's URL that calls the servlet. This includes either the servlet name or a path to the servlet, but does not include any extra path information or a query string.

Returned value [ type xs:string ]: The Servlet path.

request:user-name( )

Returns the name of the current authenticated user.

Returned value [ type xs:string ]: The name of user, or empty sequence if no authentication.

request:user-agent( )

Returns the name of the user agent that intiated the request.

Returned value [ type xs:string ]: The user agent .

request:get-remote-host( )

Returns the fully qualified name of the client that sent the request. If the engine cannot or chooses not to resolve the hostname (to improve performance), this method returns the dotted-string form of the IP address.

Returned value [ type xs:string ]: The name of the client machine that sent the request.

request:get-remote-addr( )

Returns the Internet Protocol (IP) address of the client that sent the request.

Returned value [ type xs:string ]: The IP address of the client.

request:get-remote-port( )

Returns the port of the client that sent the request.

Returned value [ type xs:int ]: The integer port number.

request:get-server-name( )

Returns the host name of the server that received the request.

Returned value [ type xs:string ]: The server name.

request:get-server-port( )

Returns the port number on which this request was received.

Returned value [ type xs:int ]: The integer port number.

request:get-attribute( $name as xs:string )

Returns the value of the named request attribute as an item, or empty() if no attribute of the given name exists.

Parameter $name [ type xs:string ]: 

Returned value [ type item() ]: An item or the empty sequence.

request:set-attribute( $name as xs:string, $value as item() )

Stores an attribute on this request. .

Parameter $name [ type xs:string ]: attribute name.

Parameter $value [ type item() ]: value set.

Returned value [ type empty() ]: none.

request:get-attribute-names( )

Returns a sequence of the names of the attributes available to this request.

Returned value [ type xs:string* ]: Name sequence.

request:get-header-names( )

Returns a sequence of all the header names this request contains. .

Returned value [ type xs:string* ]: Name sequence.

request:header-names( )

Returns a sequence of all the header names this request contains. Alias of get-header-names().

Returned value [ type xs:string* ]: Name sequence.

request:header( $name as xs:string )

Alias of get-header().

Parameter $name [ type xs:string ]: a String specifying the header name.

Returned value [ type xs:string ]: a String containing the value of the requested header, or empty() if the request does not have a header of that name.

request:get-header( $name as xs:string )

Parameter $name [ type xs:string ]: a String specifying the header name.

Returned value [ type xs:string ]: a String containing the value of the requested header, or empty() if the request does not have a header of that name.

request:parameter-names( )

Returns a sequence of all the header names this request contains. Alias of get-parameter-names().

Returned value [ type xs:string* ]: Name sequence.

request:get-parameter-names( )

Returns a sequence of all the header names this request contains.

Returned value [ type xs:string* ]: Name sequence.

request:has-parameter( $name as xs:string )

Returns true if the request bears this parameter (even though it has an empty value).

Parameter $name [ type xs:string ]: Name of the parameter.

Returned value [ type xs:boolean ]: 

request:parameter( $name as xs:string )

Returns the string value of a simple parameter. .

Note: File parts of a multipart POST return a void value.

Parameter $name [ type xs:string ]: name of the required parameter .

Returned value [ type xs:string ]: The string value of parameter, or an empty sequence if not found.

request:get-parameter( $name as xs:string )

Returns the string value of a simple parameter. .

Note: File parts of a multipart POST return a void value.

Parameter $name [ type xs:string ]: name of the required parameter .

Returned value [ type xs:string ]: The string value of the parameter, or an empty sequence if not found.

request:set-parameter( $name as xs:string, $value as xs:string )

Parameter $name [ type xs:string ]: 

Parameter $value [ type xs:string ]: 

Returned value [ type empty() ]: none.

request:get-cookie-names( )

Returns a sequence of all the cookie names this request contains.

Returned value [ type xs:string* ]: The cookie name sequence.

request:get-cookie( $name as xs:string )

Returns the value of a cookie found by its name.

Parameter $name [ type xs:string ]: Cookie name.

Returned value [ type xs:string ]: The string value of the cookie.

request:redirect-to( $pageURL as xs:string )

Performs a redirect to any URL. This method uses the redirect mechanism of HTTP (code 307), therefore doing a roundtrip to the client. .

Parameter $pageURL [ type xs:string ]: URL of the page to redirect to.

Returned value [ type empty() ]: none.

request:forward( $pageURI as xs:string )

Forwards the request to another XQSP script, without client roundtrip. .

Parameter $pageURI [ type xs:string ]: URI of the requested page: this must be a path relative to the web application.

Returned value [ type empty() ]: This functions never returns: it transfers control to the new XQSP script.

2. Response

These functions have the predefined prefix response.

They provide means of preparing the HTTP response: as such they should be called before generating any content, since in general they condition the HTTP response and headers. 

response:set-header( $name as xs:string, $value as xs:string )

Sets a response header with the given name and value. If the header had already been set, the new value overwrites the previous one.

Parameter $name [ type xs:string ]: the name of the header.

Parameter $value [ type xs:string ]: the header value.

Returned value [ type empty() ]: none.

response:error( $code as xs:int, $message as xs:string )

Sends an error response to the client using the specified status.

Parameter $code [ type xs:int ]: HTTP status.

Parameter $message [ type xs:string ]: descriptive message.

Returned value [ type empty() ]: none.

response:set-content-type( $type as xs:string )

Sets the content type of the response being sent to the client. The content type may include the type of character encoding used, for example, text/html; charset=ISO-8859-4.

Parameter $type [ type xs:string ]: content type.

Returned value [ type empty() ]: none.

response:set-encoding( $encoding as xs:string )

Sets the content encoding of the response being sent to the client. .

Parameter $encoding [ type xs:string ]: Encoding name.

Returned value [ type empty() ]: none.

response:add-cookie( $name as xs:string, $value as xs:string )

Adds the specified cookie to the response.

Parameter $name [ type xs:string ]: a String specifying the name of the cookie.

Parameter $value [ type xs:string ]: a String specifying the value of the cookie.

Returned value [ type empty() ]: none.

response:add-cookie( $name as xs:string, $value as xs:string, $max-age as xs:int, $path as xs:string )

Adds the specified cookie to the response.

Parameter $name [ type xs:string ]: a String specifying the name of the cookie.

Parameter $value [ type xs:string ]: a String specifying the value of the cookie.

Parameter $max-age [ type xs:int ]: maximum age of the cookie in seconds.

Parameter $path [ type xs:string ]: a path for the pages for which the client should return the cookie.

Returned value [ type empty() ]: none.

response:add-cookie( $name as xs:string, $value as xs:string, $max-age as xs:int, $path as xs:string, $domain as xs:string, $secure as xs:boolean, $comment as xs:string )

Adds the specified cookie to the response.

Parameter $name [ type xs:string ]: a String specifying the name of the cookie.

Parameter $value [ type xs:string ]: a String specifying the value of the cookie.

Parameter $max-age [ type xs:int ]: maximum age of the cookie in seconds.

Parameter $path [ type xs:string ]: a path for the pages for which the client should return the cookie.

Parameter $domain [ type xs:string ]: Specifies the domain within which this cookie should be presented.

Parameter $secure [ type xs:boolean ]: Indicates to the browser whether the cookie should only be sent using a secure protocol, such as HTTPS or SSL.

Parameter $comment [ type xs:string ]: Specifies a comment that describes a cookie's purpose. .

Returned value [ type empty() ]: none.

3. Session

These functions handle data related to a user "session", in a wide sense, for example they include cookie handling.

They have the predefined prefix session.

session:create( )

Creates or recreates a Session.

Returned value [ type empty() ]: none.

session:exists( )

Returns true if the Session exists.

Returned value [ type xs:boolean ]: true if the Session exists.

session:get-id( )

Returns a string containing the unique identifier assigned to the session.

Returned value [ type xs:string ]: identifier.

session:get-last-accessed-time( )

Returns the last time the client sent a request associated with this session.

Returned value [ type xs:dateTime ]: access time as dateTime.

session:get-creation-time( )

Returns the time when this session was created.

Returned value [ type xs:ddateTime ]: creation time as dateTime.

session:is-new( )

Returns true if the client does not yet know about the session or if the client chooses not to join the session.

Returned value [ type xs:boolean ]: true or false.

session:invalidate( )

Invalidates this session and unbinds any objects bound to it.

Returned value [ type empty() ]: none.

session:get-max-inactive-interval( )

Returns the maximum time interval, in seconds, that the server will keep this session open between client accesses.

Returned value [ type xs:int ]: an integer specifying the number of seconds this session remains open between client requests.

session:set-max-inactive-interval( $max as xs:int )

Specifies the time, in seconds, between client requests before the servlet container will invalidate this session.

Parameter $max [ type xs:int ]: an integer specifying the number of seconds this session remains open between client requests.

Returned value [ type empty() ]: none.

session:get-attribute( $name as xs:string )

Returns the object bound with the specified name in this session.

Parameter $name [ type xs:string ]: attribute name.

Returned value [ type item() ]: the item bound, or the empty sequence if no object is bound under the name.

session:set-attribute( $name as xs:string, $value as item() )

Binds an item to this session, using the name specified.

Parameter $name [ type xs:string ]: attribute name.

Parameter $value [ type item() ]: the item to be bound.

Returned value [ type empty() ]: none.

session:get-attribute-names( )

Returns a sequence of all names of bound attributes.

Returned value [ type xs:string* ]: Name sequence.