Difference between revisions of "WebSocket Module"
m (Text replacement - "xs:anyAtomicItem" to "xs:anyAtomicType") |
|||
Line 12: | Line 12: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|ws:id||xs:string}} | |{{Func|ws:id||xs:string}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the ID of the current WebSocket. | |Returns the ID of the current WebSocket. | ||
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists. | |{{Error|not-found|#Errors}} No WebSocket with the specified id exists. | ||
Line 26: | Line 26: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|ws:ids||xs:string*}} | |{{Func|ws:ids||xs:string*}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the ids of all currently registered WebSockets. | |Returns the ids of all currently registered WebSockets. | ||
Line 37: | Line 37: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|ws:path|$id as xs:string|xs:string}} | |{{Func|ws:path|$id as xs:string|xs:string}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the path of the WebSocket with the specified {{Code|$id}}. | |Returns the path of the WebSocket with the specified {{Code|$id}}. | ||
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists. | |{{Error|not-found|#Errors}} No WebSocket with the specified id exists. | ||
Line 51: | Line 51: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|ws:close|$id as xs:string|empty-sequence()}} | |{{Func|ws:close|$id as xs:string|empty-sequence()}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Closes the connection of the WebSocket with the specified {{Code|$id}}. | |Closes the connection of the WebSocket with the specified {{Code|$id}}. | ||
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists. | |{{Error|not-found|#Errors}} No WebSocket with the specified id exists. | ||
Line 67: | Line 67: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|ws:send|$message as item(), $ids as xs:string*|empty-sequence()}} | |{{Func|ws:send|$message as item(), $ids as xs:string*|empty-sequence()}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Sends a <code>$message</code> to the clients with the specified <code>$ids</code>. Ids that cannot be assigned to clients will be ignored. The message will be handled as follows: | |Sends a <code>$message</code> to the clients with the specified <code>$ids</code>. Ids that cannot be assigned to clients will be ignored. The message will be handled as follows: | ||
Line 81: | Line 81: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|ws:broadcast|$message as xs:anyAtomicType|empty-sequence()}} | |{{Func|ws:broadcast|$message as xs:anyAtomicType|empty-sequence()}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Broadcasts a <code>$message</code> to all connected clients except to the caller. Invocations of this convenience function are equivalent to <code>ws:send($message, ws:ids()[. != ws:id()])</code>. See {{Function||ws:send}} for more details on the message handling. | |Broadcasts a <code>$message</code> to all connected clients except to the caller. Invocations of this convenience function are equivalent to <code>ws:send($message, ws:ids()[. != ws:id()])</code>. See {{Function||ws:send}} for more details on the message handling. | ||
Line 92: | Line 92: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|ws:emit|$message as xs:anyAtomicType|empty-sequence()}} | |{{Func|ws:emit|$message as xs:anyAtomicType|empty-sequence()}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Emits a <code>$message</code> to all connected clients. Invocations of this function are equivalent to <code>ws:send($message, ws:ids())</code>. See {{Function||ws:send}} for more details on the message handling. | |Emits a <code>$message</code> to all connected clients. Invocations of this function are equivalent to <code>ws:send($message, ws:ids())</code>. See {{Function||ws:send}} for more details on the message handling. | ||
Line 103: | Line 103: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|ws:eval|$query as xs:anyAtomicType|xs:string}}<br />{{Func|ws:eval|$query as xs:anyAtomicType, $bindings as map(*)?|xs:string}}<br />{{Func|ws:eval|$query as xs:anyAtomicType, $bindings as map(*)?, $options as map(*)?|xs:string}}<br /> | |{{Func|ws:eval|$query as xs:anyAtomicType|xs:string}}<br />{{Func|ws:eval|$query as xs:anyAtomicType, $bindings as map(*)?|xs:string}}<br />{{Func|ws:eval|$query as xs:anyAtomicType, $bindings as map(*)?, $options as map(*)?|xs:string}}<br /> | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Schedules the evaluation of the supplied {{Code|$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 {{Code|$bindings}} (see {{Function|XQuery|xquery:eval}} for more details). The following {{Code|$options}} can be supplied: | |Schedules the evaluation of the supplied {{Code|$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 {{Code|$bindings}} (see {{Function|XQuery|xquery:eval}} for more details). The following {{Code|$options}} can be supplied: | ||
Line 112: | Line 112: | ||
* {{Code|id}}: sets a custom job id. The id must not start with the standard <code>job</code> prefix, and it can only be assigned if no job with the same name exists. | * {{Code|id}}: sets a custom job id. The id must not start with the standard <code>job</code> 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. | Query scheduling is recommendable if the immediate query execution might be too time consuming and lead to a timeout. | ||
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{Error|overflow|#Errors}} Query execution is rejected, because too many jobs are queued or being executed. <br/>{{Error|id|#Errors}} The specified id is invalid or has already been assigned. | |{{Error|overflow|#Errors}} Query execution is rejected, because too many jobs are queued or being executed. <br/>{{Error|id|#Errors}} The specified id is invalid or has already been assigned. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 133: | Line 133: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|ws:get|$id as xs:string, $name as xs:string|item()*}}<br/>{{Func|ws:get|$id as xs:string, $name as xs:string, $default as item()*|item()*}} | |{{Func|ws:get|$id as xs:string, $name as xs:string|item()*}}<br/>{{Func|ws:get|$id as xs:string, $name as xs:string, $default as item()*|item()*}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the value of an attribute with the specified {{Code|$name}} from the WebSocket with the specified {{Code|$id}}. If the attribute is unknown, an empty sequence or the optionally specified {{Code|$default}} value will be returned instead. | |Returns the value of an attribute with the specified {{Code|$name}} from the WebSocket with the specified {{Code|$id}}. If the attribute is unknown, an empty sequence or the optionally specified {{Code|$default}} value will be returned instead. | ||
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists. | |{{Error|not-found|#Errors}} No WebSocket with the specified id exists. | ||
Line 147: | Line 147: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|ws:set|$id as xs:string, $name as xs:string, $value as item()*|empty-sequence()}} | |{{Func|ws:set|$id as xs:string, $name as xs:string, $value as item()*|empty-sequence()}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the specified {{Code|value}} of the attribute with the specified {{Code|$name}} from the WebSocket with the specified {{Mono|$id}}. | |Returns the specified {{Code|value}} of the attribute with the specified {{Code|$name}} from the WebSocket with the specified {{Mono|$id}}. | ||
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists. | |{{Error|not-found|#Errors}} No WebSocket with the specified id exists. | ||
Line 161: | Line 161: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|ws:delete|$id as xs:string, $name as xs:string|empty-sequence()}} | |{{Func|ws:delete|$id as xs:string, $name as xs:string|empty-sequence()}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Deletes an attribute with the specified {{Code|$name}} from the WebSocket with the specified {{Mono|$id}}. | |Deletes an attribute with the specified {{Code|$name}} from the WebSocket with the specified {{Mono|$id}}. | ||
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists. | |{{Error|not-found|#Errors}} No WebSocket with the specified id exists. | ||
Line 223: | Line 223: | ||
! width="110"|Code | ! width="110"|Code | ||
|Description | |Description | ||
− | |- | + | |- valign="top" |
|{{Code|not-found}} | |{{Code|not-found}} | ||
|No WebSocket with the specified id exists. | |No WebSocket with the specified id exists. |
Revision as of 14:20, 20 July 2022
This XQuery Module contains functions for accessing specific WebSocket functions. This module is mainly useful in the context of WebSockets.
Contents
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 thews
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 WebSockets. |
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:
|
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
Signatures | ws:eval($query as xs:anyAtomicType) as xs:string ws:eval($query as xs:anyAtomicType, $bindings as map(*)?) as xs:string ws:eval($query as xs:anyAtomicType, $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:
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 |
<syntaxhighlight lang="xquery"> declare %ws:message('/tasks', '{$message}') function local:message($message) { ws:eval('prof:sleep(10000), "Your message has been processed."') }; </syntaxhighlight> |
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.
|
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
<syntaxhighlight lang="xquery"> 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)
}; </syntaxhighlight>
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
<syntaxhighlight lang="xquery"> 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)
}; </syntaxhighlight>
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 |
---|---|
not-found
|
No WebSocket with the specified id exists. |
Changelog
- Version 9.2
- Added:
ws:eval
This module was introduced with Version 9.1.