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, which is statically bound to the ws
prefix. Prior to Version 9.2, the module needed to be imported in the query prolog:
import module namespace ws = "http://basex.org/modules/ws";
...
- 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.
|
ws:eval
Template:Mark
Signatures
|
ws:eval($query as xs:anyAtomicItem) as xs:string
ws:eval($query as xs:anyAtomicItem, $bindings as map(*)?) as xs:string
ws:eval($query as xs:anyAtomicItem, $bindings as map(*)?, $options as map(*)?) as xs:string
|
Summary
|
Schedules the evaluation of the supplied $query and returns the result to the calling WebSocket client. The query can be a URI or a string, and variables and context items can be declared via $bindings (see xquery:eval for more details). The following $options can be supplied:
base-uri : sets the base-uri property for the query. This URI will be used when resolving relative URIs, such as with fn:doc .
id : sets a custom job id. The id must not start with the standard job prefix, and it can only be assigned if no job with the same name exists.
Query scheduling is recommendable if the immediate query execution might be too time consuming and lead to a timeout.
|
Errors
|
overflow : Query execution is rejected, because too many jobs are queued or being executed.
id : The specified id is invalid or has already been assigned.
|
Examples
|
- Cache query result. The returned id can be used to pick up the result with jobs:result:
declare
%ws:message('/tasks', '{$message}')
function local:message($message) {
ws:eval('Your message has been processed.')
};
|
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
- Version 9.2
This module was introduced with Version 9.1.