WebSocket Module

This XQuery Module contains functions for accessing specific WebSocket functions. 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 assigned to the http://basex.org/modules/ws namespace. The module must be imported in the query prolog:

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

• In this document, the namespace is bound to the ws prefix.
• As sessions are side-effecting operations, all functions are flagged as non-deterministic. As a result, some query optimizations will be suppressed.

General Functions

ws:id

Signatures	ws:id() as xs:string
Summary	Returns the ID of the current WebSocket.
Errors	not-found: No WebSocket with the specified id exists.

ws:ids

Signatures	ws:ids() as xs:string*
Summary	Returns the ids of all currently registered WebSocket.

ws:path

Signatures	ws:path($id as xs:string) as xs:string
Summary	Returns the path of the WebSocket with the specified $id.
Errors	not-found: No WebSocket with the specified id exists.

ws:close

Signatures	ws:close($id as xs:string) as empty-sequence()
Summary	Closes the connection of the WebSocket with the specified $id.
Errors	not-found: No WebSocket with the specified id exists.

Sending Data

ws:send

Signatures

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

Summary

Sends a $message to the clients with the specified $ids. Ids that cannot be assigned to clients will be ignored. The message will be handled as follows: Items of type xs:base64Binary and xs:hexBinary will be transmitted as binary messages. Function items (maps, arrays) will be serialized as JSON and transmitted as string messages. All other items will be serialized with the default serialization options and transmitted as string messages.

ws:broadcast

Signatures	ws:broadcast($message as xs:anyAtomicType) as empty-sequence()
Summary	Broadcasts a $message to all connected clients except to the caller. Invocations of this convenience function are equivalent to ws:send($message, ws:ids()[. != ws:id()]). See ws:send for more details on the message handling.

ws:emit

Signatures	ws:emit($message as xs:anyAtomicType) as empty-sequence()
Summary	Emits a $message to all connected clients. Invocations of this function are equivalent to ws:send($message, ws:ids()). See ws:send for more details on the message handling.

WebSocket Attributes

ws:get

Signatures	ws:get($id as xs:string, $name as xs:string) as item()* ws:get($id as xs:string, $name as xs:string, $default as item()*) as item()*
Summary	Returns the value of an attribute with the specified $name from the WebSocket with the specified $id. If the attribute is unknown, an empty sequence or the optionally specified $default value will be returned instead.
Errors	not-found: No WebSocket with the specified id exists.

ws:set

Signatures	ws:set($id as xs:string, $name as xs:string, $value as item()*) as empty-sequence()
Summary	Returns the specified value of the attribute with the specified $name from the WebSocket with the specified $id.
Errors	not-found: No WebSocket with the specified id exists. set: The supplied value cannot be materialized.

ws:delete

Signatures	ws:delete($id as xs:string, $name as xs:string) as empty-sequence()
Summary	Deletes an attribute with the specified $name from the WebSocket with the specified $id.
Errors	not-found: No WebSocket with the specified id exists.

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(map {
    'type': 'Connect',
    'id': $id
  })
  return ws:broadcast($message)
};

Explanation:

• 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(map { 'message': $message })
  return ws:emit($message)
};

Explanation:

• 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

Code	Description
set	The supplied value cannot be materialized.
not-found	No WebSocket with the specified id exists.

Changelog

This module was introduced with Version 9.1.