Web Module

From BaseX Documentation

Jump to: navigation, search

This XQuery Module provides convenience functions for building web applications with RESTXQ.

Contents

[edit] Conventions

All functions in this module are assigned to the http://basex.org/modules/web namespace, which is statically bound to the web prefix.
All errors are assigned to the http://basex.org/errors namespace, which is statically bound to the bxerr prefix.

[edit] Functions

[edit] web:content-type

Signatures web:content-type($path as xs:string) as xs:string
Summary Returns the content type of a path by analyzing its file suffix. application/octet-stream is returned if the file suffix is unknown.
Examples
  • web:content-type("sample.mp3") returns audio/mpeg

[edit] web:create-url

Signatures web:create-url($url as xs:string, $parameters as map(item(), item()*)) as xs:string
Summary Creates a new URL from the specified $url string and the $parameters specified in a map. The keys and and values of the map entries will be converted to strings, URL-encoded (see web:encode-url), and appended to the url as query parameters. If a map entry has more than a single item, all of them will be appended as single parameters.
Examples
  • web:create-url('http://find.me', map { 'q': 'dog' }) returns http://find.me?q=dog
  • web:create-url('search', map { 'year': (2000,2001), 'title':() }) returns search?year=2000&year=2001

[edit] web:encode-url

Signatures web:encode-url($string as xs:string) as xs:string
Summary Encodes a string to a URL. Spaces are rewritten to +; *, -, . and _ are adopted; and all other non-ASCII characters and special characters are percent-encoded.
Examples
  • web:encode-url("this is a test!.html") returns this+is+a+test%21.html.

[edit] web:decode-url

Signatures web:decode-url($string as xs:string) as xs:string
Summary Decodes a URL to the original string. Percent-encoded characters are decoded to their UTF8 codepoints, and + characters are rewritten to spaces.
Examples
  • web:decode-url("%E6%97%A5%E6%9C%AC%E8%AA%9E") returns 日本語.
Errors BXWE0001: Specified URI is invalid.
Errors BXWE0002: Specified URI contains invalid XML characters.

[edit] web:redirect

Signatures web:redirect($location as xs:string) as element(rest:response)
web:redirect($location as xs:string, $parameters as map(item(), item()*)) as element(rest:response)
Summary Creates a RESTXQ redirection to the specified location. The returned response will only work if no other items are returned by the RESTXQ function.
If $parameters are specified, they will be appended as query parameters to the URL as described for web:create-url.
Examples
  • The query web:redirect('/a/b') returns the following result (which will be interpreted as redirection if RESTXQ is used):
<rest:response xmlns:rest="http://exquery.org/ns/restxq">
  <http:response xmlns:http="http://expath.org/ns/http-client" status="302">
    <http:header name="location" value="/a/b"/>
  </http:response>
</rest:response>
  • The first RESTXQ function creates an initial database, and redirects to a second function that will access this database:
declare %updating %rest:path('/app/init') function local:init() {
  db:create('app', <root/>, 'root.xml'),
  db:output(web:redirect('/app/main'))
};

declare %rest:path('/app/main') function local:update() {
  'Stored documents: ' || count(db:open('app'))
};

[edit] web:response-header

Signatures web:response-header() as element(rest:response)
web:response-header($output as map(*)) as element(rest:response)
web:response-header($output as map(*), $headers as map(xs:string, xs:string)) as element(rest:response)
Summary Creates a RESTXQ response header with a default caching directive and default serialization parameters.

Serialization parameters can be supplied via the $output argument. Empty string values can be specified to invalidate default values. By default, the following serialization parameters will be returned:

  • media-type: application/octet-stream

Header options can be supplied via the $headers argument. Empty string values can be specified to invalidate default values. By default, the following header options will be returned:

  • Cache-Control: max-age=3600,public
Examples
  • The function call web:response-header() returns the following response element:
<rest:response xmlns:rest="http://exquery.org/ns/restxq">
  <http:response xmlns:http="http://expath.org/ns/http-client">
    <http:header name="Cache-Control" value="max-age=3600,public"/>
  </http:response>
  <output:serialization-parameters xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization">
    <output:media-type value="application/octet-stream"/>
  </output:serialization-parameters>
</rest:response>
  • If the following RESTXQ function is called by a web browser…
declare %rest:path('media/{$file}') function local:get($file) {
  let $path := 'path/to/' || $file
  return (
    web:response-header(map { 'media-type': web:content-type($path) }),
    file:read-binary($path)
  )
};

…a file resource with the correct content-type will be returned to user (provided that it exists in the web server's file system).

[edit] Errors

Code Description
BXWE0001 Specified URL is invalid.
BXWE0002 Specified URL contains invalid XML characters.

[edit] Changelog

Version 8.4
Version 8.2

The module was introduced with Version 8.1.

Personal tools
Namespaces
Variants
Actions
Navigation
Print/export