WebSocket Functions

This module contains functions for accessing and addressing WebSocket connections. This module is mainly useful in the context of WebSockets.

Conventions

• The module will be available if the basex-api library is found in the classpath. This is the case if you use one of the complete distributions of BaseX (zip, exe, war).
• All functions and errors are in the http://basex.org/modules/ws namespace, to which the ws prefix is statically bound.
• As WebSocket operations are side-effecting, all functions are flagged as nondeterministic. As a result, some query optimizations will be suppressed.

General Functions

ws:id

ws:id() as xs:string

ws:ids

ws:ids() as xs:string*admin

ws:path

ws:path(  $id  as xs:string) as xs:stringadmin

ws:close

Updated: A close status and a reason can be supplied.

ws:close(  $id      as xs:string,  $status  as xs:integer  := 1000,  $reason  as xs:string  := '') as empty-sequence()admin

Sending Data

ws:send

ws:send(  $message  as item(),  $ids      as xs:string*) as empty-sequence()admin

ws:broadcast

ws:broadcast(  $message  as item()) as empty-sequence()admin

ws:emit

ws:emit(  $message  as item()) as empty-sequence()admin

ws:ping

Added: New function.

ws:ping(  $id  as xs:string) as empty-sequence()admin

ws:eval

Updated: All options of job:eval except service are supported.

Updated: The query result is sent as a single message, and errors are reported to the client.

Updated: A function item can be invoked instead of a query.

ws:eval(  $query     as (xs:string|xs:anyURI|fn(*)),  $bindings  as (map((xs:string|xs:QName), item()*)|array(*))?  := (),  $options   as map(*)?  := {}) as xs:stringadmin

declare
  %ws:message('/tasks', '{$message}')
function local:message($message) {
  ws:eval('prof:sleep(10000), "Your message has been processed."')
};

WebSocket Attributes

ws:get

ws:get(  $id       as xs:string,  $key      as xs:string,  $default  as item()*  := ()) as item()*admin

ws:set

ws:set(  $id     as xs:string,  $key    as xs:string,  $value  as item()*) as empty-sequence()admin

ws:delete

ws:delete(  $id   as xs:string,  $key  as xs:string) as empty-sequence()admin

Examples

Example 1

import module namespace ws = "http://basex.org/modules/ws";

declare
  %ws:connect('/')
function local:connect() as empty-sequence() {
  let $id := ws:id()
  let $message := json:serialize({ 'type': 'Connect', 'id': $id })
  return ws:broadcast($message)
};

• The function has a %ws:connect annotation. It gets called if a client successfully creates a WebSocket connection to the path / (check out WebSockets for further information).
• A JSON response is generated, which contains the new client id and a Connect string.
• This response will be sent to all other connected clients.

Example 2

import module namespace ws = "http://basex.org/modules/ws";

declare
  %ws:message('/', '{$message}')
function local:message(
  $message as xs:string
) as empty-sequence() {
  let $message := json:serialize({ 'message': $message })
  return ws:emit($message)
};

• The function has a %ws:message annotation. It gets called if a client sends a new message.
• A JSON response is generated, which contains the message string.
• This response will be sent to all connected clients (including the calling client).

Errors

Changelog

• Added: ws:ping
• Updated: ws:close: optional close status and reason.
• Updated: ws:eval: job options and serialization parameters.
• Updated: ws:eval: a function item can be invoked instead of a query.

• Added: ws:eval

• Added: New module added.