Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
m
Text replacement - "</syntaxhighlight>" to "</pre>"
* The module will be available if the {{Code|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 <code><nowiki>http://basex.org/modules/ws</nowiki></code> namespace, which is statically bound to the {{Code|ws}} prefix.
* As sessions are side-effecting operations, all functions are flagged as ''non-deterministicnondeterministic''. As a result, some query optimizations will be suppressed.
=General Functions=
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>ws:id||() as xs:string}}</pre>|-valign="top"
| '''Summary'''
|Returns the ID of the current WebSocket.
|-valign="top"
| '''Errors'''
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>ws:ids||() as xs:string*}}</pre>|-valign="top"
| '''Summary'''
|Returns the ids of all currently registered WebSockets.
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>ws:path|( $id as xs:string|) as xs:string}}</pre>|-valign="top"
| '''Summary'''
|Returns the path of the WebSocket with the specified {{Code|$id}}.
|-valign="top"
| '''Errors'''
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>ws:close|( $id as xs:string|) as empty-sequence()}}</pre>|-valign="top"
| '''Summary'''
|Closes the connection of the WebSocket with the specified {{Code|$id}}.
|-valign="top"
| '''Errors'''
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>ws:send|( $message as item(), $ids as xs:string*|) as empty-sequence()}}</pre>|-valign="top"
| '''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:
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>ws:broadcast|( $message as xs:anyAtomicType|) as empty-sequence()}}</pre>|-valign="top"
| '''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 [[#ws:send{{Function||ws:send]] }} for more details on the message handling.
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>ws:emit|( $message as xs:anyAtomicType|) as empty-sequence()}}</pre>|-valign="top"
| '''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 [[#ws:send{{Function||ws:send]] }} for more details on the message handling.
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|ws:eval|$query as xs:anyAtomicItem|xs:string}}<br /pre>{{Func|ws:eval|( $query as xs:anyAtomicItemanyAtomicType, $bindings as map(*)?|xs :string}}<br />{{Func|ws:eval|$query as xs:anyAtomicItem, $bindings as map= (*)?, $options as map(*)?| := map { }) as xs:string}}<br /pre>|-valign="top"
| '''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:
* {{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.
|-valign="top"
| '''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.
|-valign="top"
| '''Examples'''
|
* Schedule a second query that will notify the client 10 seconds later that a message was processed:
<syntaxhighlight pre lang="'xquery"'>
declare
%ws:message('/tasks', '{$message}')
ws:eval('prof:sleep(10000), "Your message has been processed."')
};
</syntaxhighlightpre>
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|ws:get|$id as xs:string, $name as xs:string|item()*}}<br/pre>{{Func|ws:get|( $id as xs:string, $name as xs:string, $default as item()*| := ()) as item()*}}</pre>|-valign="top"
| '''Summary'''
|Returns the value of an attribute with the specified {{Code|$name}} from for 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'''
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>ws:set|( $id as xs:string, $name as xs:string, $value as item()*|) as empty-sequence()}}</pre>|-valign="top"
| '''Summary'''
|Returns Assigns the specified {{Code|$value}} of to the attribute with the specified {{Code|$name}} from for the WebSocket with the specified {{Mono|$id}}.|-valign="top"
| '''Errors'''
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.<br>{{Error|set|#Errors}} The supplied value cannot be materialized.
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>ws:delete|( $id as xs:string, $name as xs:string|) as empty-sequence()}}</pre>|-valign="top"
| '''Summary'''
|Deletes an attribute with the specified {{Code|$name}} from the WebSocket with the specified {{Mono|$id}}.
|-valign="top"
| '''Errors'''
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.
==Example 1==
<syntaxhighlight pre lang="'xquery"'>
import module namespace ws = "http://basex.org/modules/ws";
return ws:broadcast($message)
};
</syntaxhighlightpre>
'''Explanation:'''
==Example 2==
<syntaxhighlight pre lang="'xquery"'>
import module namespace ws = "http://basex.org/modules/ws";
return ws:emit($message)
};
</syntaxhighlightpre>
'''Explanation:'''
! width="110"|Code
|Description
|-|{{Code|set}}|The supplied value cannot be materialized.|-valign="top"
|{{Code|not-found}}
|No WebSocket with the specified id exists.
;Version 9.2
* Added: [[#ws:eval{{Function||ws:eval]]}}
This module was introduced with Version 9.1.
