Difference between revisions of "Web Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replacement - "syntaxhighlight" to "pre")
 
(50 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
=Conventions=
 
=Conventions=
  
−
All functions in this module are assigned to the <code><nowiki>http://basex.org/modules/web</nowiki></code> namespace, which is statically bound to the {{Code|web}} prefix.<br/>
+
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/web</nowiki></code> namespace, which is statically bound to the {{Code|web}} prefix.<br/>
−
All errors are assigned to the <code><nowiki>http://basex.org/errors</nowiki></code> namespace, which is statically bound to the {{Code|bxerr}} prefix.
 
  
 
=Functions=
 
=Functions=
Line 11: Line 10:
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|web:content-type|$path as xs:string|xs:string}}<br/>
+
|<pre>web:content-type(
−
|-
+
  $path as xs:string
 +
) as xs:string</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Returns the content type of a path by analyzing its file suffix. <code>application/octet-stream</code> is returned if the file suffix is unknown.
 
|Returns the content type of a path by analyzing its file suffix. <code>application/octet-stream</code> is returned if the file suffix is unknown.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
Line 26: Line 27:
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|web:create-url|$url as xs:string, $parameters as map(item(), item()*)|xs:string}}<br/>
+
|<pre>web:create-url(
−
|-
+
  $href        as xs:string,
 +
  $parameters as map(*),
 +
  $anchor      as xs:string  := ()
 +
) as xs:string</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Creates a new URL from the specified <code>$url</code> string and the <code>$parameters</code> specified in a map. The keys and and values of the map entries will be converted to strings, URL-encoded (see [[#web:encode-url|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.
+
|Creates a new URL from the specified {{Code|$href}} string, query string <code>$parameters</code> and an optional {{Code|$anchor}} reference. The keys and values of the map entries will be converted to strings, URL-encoded (see {{Function||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.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
Line 42: Line 47:
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|web:encode-url|$string as xs:string|xs:string}}<br/>
+
|<pre>web:encode-url(
−
|-
+
  $string as xs:string
 +
) as xs:string</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Encodes a string to a URL. Spaces are rewritten to {{Code|+}}; {{Code|*}}, {{Code|-}}, {{Code|.}} and {{Code|_}} are adopted; and all other non-ASCII characters and special characters are percent-encoded.
 
|Encodes a string to a URL. Spaces are rewritten to {{Code|+}}; {{Code|*}}, {{Code|-}}, {{Code|.}} and {{Code|_}} are adopted; and all other non-ASCII characters and special characters are percent-encoded.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
Line 57: Line 64:
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|web:decode-url|$string as xs:string|xs:string}}<br/>
+
|<pre>web:decode-url(
−
|-
+
  $string as xs:string
 +
) as xs:string</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Decodes a URL to the original string. Percent-encoded characters are decoded to their UTF8 codepoints, and {{Code|+}} characters are rewritten to spaces.
 
|Decodes a URL to the original string. Percent-encoded characters are decoded to their UTF8 codepoints, and {{Code|+}} characters are rewritten to spaces.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* <code><nowiki>web:decode-url("%E6%97%A5%E6%9C%AC%E8%AA%9E")</nowiki></code> returns <code>日本語</code>.
 
* <code><nowiki>web:decode-url("%E6%97%A5%E6%9C%AC%E8%AA%9E")</nowiki></code> returns <code>日本語</code>.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|BXWE0001|#Errors}} Specified URI is invalid.
+
|{{Error|invalid|#Errors}} the string contains invalid XML characters.
−
|-
+
|}
−
| '''Errors'''
+
 
−
|{{Error|BXWE0002|#Errors}} Specified URI contains invalid XML characters.
+
==web:forward==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>web:forward(
 +
  $path        as xs:string,
 +
  $parameters  as map(*)    := ()
 +
) as element(rest:forward)</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Creates a server-side [[RESTXQ#Forwards and Redirects|RESTXQ forward request]] to the specified {{Code|$path}}:
 +
* The client will not get notified of this forwarding.
 +
* Supplied query parameters will be attached to parameters of the current request.
 +
* The {{Code|$parameter}} argument is processed as described in {{Function||web:create-url}}.
 +
|- valign="top"
 +
| '''Examples'''
 +
|
 +
The function call <code><nowiki>web:forward('/a/b')</nowiki></code> creates the following result (which will be interpreted as forwarding if RESTXQ is used):
 +
<pre lang="xml">
 +
<rest:forward>/a/b</rest:forward>
 +
</pre>
 
|}
 
|}
  
Line 78: Line 108:
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|web:redirect|$location as xs:string|element(rest:response)}}<br/>{{Func|web:redirect|$location as xs:string, $parameters as map(item(), item()*)|element(rest:response)}}<br/>
+
|<pre>web:redirect(
−
|-
+
  $url        as xs:string,
 +
  $parameters as map(*)    := (),
 +
  $anchor      as xs:string  := ()
 +
) as element(rest:response)</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Creates a [[RESTXQ#Forwards and Redirects|RESTXQ redirection]] to the specified location. The returned response will only work if no other items are returned by the RESTXQ function.<br/>If <code>$parameters</code> are specified, they will be appended as query parameters to the URL as described for [[#web:create-url|web:create-url]].
+
|Creates a [[RESTXQ#Forwards and Redirects|RESTXQ redirection]] to the specified {{Code|$url}}. The returned response will only work if no other items are returned by the RESTXQ function.<br/>The {{Code|$parameters}} and {{Code|$anchor}} arguments are processed as described in (see {{Function||web:create-url}}).
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
−
|The query <code><nowiki>web:redirect('/a/b')</nowiki></code> returns the following response element:
+
|
−
<pre class="brush:xml">
+
The query <code><nowiki>web:redirect('/a/b')</nowiki></code> returns the following result (which will be interpreted as redirection if RESTXQ is used):
 +
<pre lang="xml">
 
<rest:response xmlns:rest="http://exquery.org/ns/restxq">
 
<rest:response xmlns:rest="http://exquery.org/ns/restxq">
 
   <http:response xmlns:http="http://expath.org/ns/http-client" status="302">
 
   <http:response xmlns:http="http://expath.org/ns/http-client" status="302">
Line 97: Line 132:
  
 
==web:response-header==
 
==web:response-header==
−
 
−
{{Mark|Updated with Version 8.4}}: serialization method <code>raw</code> was removed (now obsolete).
 
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|web:response-header||element(rest:response)}}<br/>{{Func|web:response-header|$headers as map(*)|element(rest:response)}}<br/>{{Func|web:response-header|$headers as map(*), $output as map(xs:string, xs:string)|element(rest:response)}}<br/>
+
|<pre>web:response-header(
−
|-
+
  $output  as map(*)?  := (),
 +
  $headers as map(*)?  := (),
 +
  $atts    as map(*)?  := ()
 +
) as element(rest:response)</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Creates a [[RESTXQ#Response|RESTXQ response header]] with a default caching directive and default serialization parameters.<br/>
+
|Creates a [[RESTXQ#Response|RESTXQ response header]].<br/>
 +
Serialization parameters and header values can be supplied via the <code>$output</code> and <code>$headers</code> arguments, and status and message attributes can be attached to the HTTP response element with the <code>$atts</code> argument.
 +
* <code>media-type</code>: <code>application/octet-stream</code>
 
Header options can be supplied via the <code>$headers</code> argument. Empty string values can be specified to invalidate default values. By default, the following header options will be returned:
 
Header options can be supplied via the <code>$headers</code> argument. Empty string values can be specified to invalidate default values. By default, the following header options will be returned:
 
* <code>Cache-Control</code>: <code>max-age=3600,public</code>
 
* <code>Cache-Control</code>: <code>max-age=3600,public</code>
−
Serialization parameters can be supplied via the <code>$output</code> argument. Empty string values can be specified to invalidate default values. By default, the following serialization parameters will be returned:
+
|- valign="top"
−
* <code>media-type</code>: <code>application/octet-stream</code>
 
−
|-
 
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
−
* The function call <code>web:response-header()</code> returns the following response element:
+
* The function call <code>web:response-header()</code> returns:
−
<pre class="brush:xml">
+
<pre lang="xml">
 
<rest:response xmlns:rest="http://exquery.org/ns/restxq">
 
<rest:response xmlns:rest="http://exquery.org/ns/restxq">
−
   <http:response xmlns:http="http://expath.org/ns/http-client">
+
   <http:response xmlns:http="http://expath.org/ns/http-client"/>
−
    <http:header name="Cache-Control" value="max-age=3600,public"/>
+
   <output:serialization-parameters xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization"/>
−
  </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>
 
</rest:response>
 
</pre>
 
</pre>
−
* If the following RESTXQ function is called by a web browser…<br/>
+
* The following expression returns a media-type for binary data, a caching directive, and the OK status:<br/>
−
<pre class="brush:xquery">
+
<pre lang='xquery'>
 +
web:response-header(
 +
  map { 'media-type': 'application/octet-stream' },
 +
  map { 'Cache-Control': 'max-age=3600,public' },
 +
  map { 'status': 200, 'message': 'OK' }
 +
)
 +
</pre>
 +
* The following RESTXQ function returns the contents of a file to the client with correct media type:<br/>
 +
<pre lang='xquery'>
 
declare %rest:path('media/{$file}') function local:get($file) {
 
declare %rest:path('media/{$file}') function local:get($file) {
 
   let $path := 'path/to/' || $file
 
   let $path := 'path/to/' || $file
Line 135: Line 176:
 
};
 
};
 
</pre>
 
</pre>
−
…a file resource with the correct content-type will be returned to user (provided that it exists in the web server's file system).
+
|}
 +
 
 +
==web:error==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>web:error(
 +
  $status  as xs:integer,
 +
  $message  as xs:string
 +
) as none</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Raises an error with the QName {{Code|rest:error}}, the specified {{Code|$message}} and the specified {{Code|$status}} as error value.<br/>Calls to this function are equivalent to <code>fn:error(xs:QName('rest:error'), $message, $status)</code>.
 +
 
 +
See [[RESTXQ#Raise Errors|RESTXQ: Raise Errors]] to learn how the function is helpful in web applications.
 +
|- valign="top"
 +
| '''Examples'''
 +
|
 +
* <code><nowiki>web:error(404, "The requested resource cannot be found.")</nowiki></code>
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|status|#Errors}} The supplied status code is invalid.
 
|}
 
|}
  
Line 143: Line 206:
 
! width="110"|Code
 
! width="110"|Code
 
|Description
 
|Description
−
|-
+
|- valign="top"
−
|{{Code|BXWE0001}}
+
|{{Code|invalid}}
−
|Specified URL is invalid.
+
|A string contains invalid XML characters.
−
|-
+
|- valign="top"
−
|{{Code|BXWE0002}}
+
|{{Code|status}}
−
|Specified URL contains invalid XML characters.
+
|The supplied status code is invalid.
 
|}
 
|}
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 9.3
 +
* Added: {{Function||web:error}}, {{Function||web:forward}}
 +
 +
;Version 9.2
 +
* Updated: {{Function||web:create-url}}, {{Function||web:redirect}}: third argument added.
 +
 +
;Version 9.0
 +
* Updated: {{Function||web:response-header}}: third argument added; default parameters removed.
 +
* Updated: error codes updated; errors now use the module namespace
  
 
;Version 8.4
 
;Version 8.4
−
 
+
* Updated: {{Function||web:response-header}}: serialization method <code>raw</code> was removed (now obsolete).
−
* Updated: [[#web:response-header|web:response-header]]: serialization method <code>raw</code> was removed (now obsolete).
 
  
 
;Version 8.2
 
;Version 8.2
−
 
+
* Added: {{Function||web:encode-url}}, {{Function||web:decode-url}}.
−
* Added: [[#web:encode-url|web:encode-url]], [[#web:decode-url|web:decode-url]].
 
  
 
The module was introduced with Version 8.1.
 
The module was introduced with Version 8.1.
−
 
−
[[Category:XQuery]]
 

Latest revision as of 18:39, 1 December 2023

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

Conventions[edit]

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

Functions[edit]

web:content-type[edit]

Signature 
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

web:create-url[edit]

Signature 
web:create-url(
  $href        as xs:string,
  $parameters  as map(*),
  $anchor      as xs:string  := ()
) as xs:string
Summary Creates a new URL from the specified $href string, query string $parameters and an optional $anchor reference. The keys 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

web:encode-url[edit]

Signature 
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.

web:decode-url[edit]

Signature 
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 invalid: the string contains invalid XML characters.

web:forward[edit]

Signature 
web:forward(
  $path        as xs:string,
  $parameters  as map(*)     := ()
) as element(rest:forward)
Summary Creates a server-side RESTXQ forward request to the specified $path:
  • The client will not get notified of this forwarding.
  • Supplied query parameters will be attached to parameters of the current request.
  • The $parameter argument is processed as described in web:create-url.
Examples

The function call web:forward('/a/b') creates the following result (which will be interpreted as forwarding if RESTXQ is used): 

<rest:forward>/a/b</rest:forward>

web:redirect[edit]

Signature 
web:redirect(
  $url         as xs:string,
  $parameters  as map(*)     := (),
  $anchor      as xs:string  := ()
) as element(rest:response)
Summary Creates a RESTXQ redirection to the specified $url. The returned response will only work if no other items are returned by the RESTXQ function.
The $parameters and $anchor arguments are processed as described in (see 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>

web:response-header[edit]

Signature 
web:response-header(
  $output   as map(*)?  := (),
  $headers  as map(*)?  := (),
  $atts     as map(*)?  := ()
) as element(rest:response)
Summary Creates a RESTXQ response header.

Serialization parameters and header values can be supplied via the $output and $headers arguments, and status and message attributes can be attached to the HTTP response element with the $atts argument.

  • 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:
<rest:response xmlns:rest="http://exquery.org/ns/restxq">
  <http:response xmlns:http="http://expath.org/ns/http-client"/>
  <output:serialization-parameters xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization"/>
</rest:response>
  • The following expression returns a media-type for binary data, a caching directive, and the OK status:
web:response-header(
  map { 'media-type': 'application/octet-stream' },
  map { 'Cache-Control': 'max-age=3600,public' },
  map { 'status': 200, 'message': 'OK' }
)
  • The following RESTXQ function returns the contents of a file to the client with correct media type:
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)
  )
};

web:error[edit]

Signature 
web:error(
  $status   as xs:integer,
  $message  as xs:string
) as none
Summary Raises an error with the QName rest:error, the specified $message and the specified $status as error value.
Calls to this function are equivalent to fn:error(xs:QName('rest:error'), $message, $status).

See RESTXQ: Raise Errors to learn how the function is helpful in web applications.

Examples
  • web:error(404, "The requested resource cannot be found.")
Errors status: The supplied status code is invalid.

Errors[edit]

Code Description
invalid A string contains invalid XML characters.
status The supplied status code is invalid.

Changelog[edit]

Version 9.3
Version 9.2
Version 9.0
  • Updated: web:response-header: third argument added; default parameters removed.
  • Updated: error codes updated; errors now use the module namespace
Version 8.4
Version 8.2

The module was introduced with Version 8.1.

Retrieved from "https://old.docs.basex.org/index.php?title=Web_Module&oldid=16887"