Changes

Jump to navigation Jump to search
2,700 bytes added ,  15:43, 27 February 2020
no edit summary
=Conventions=
* The module will be available if the {{Code|basex-api}} package must be included library is found in the classpath. This is always the case if you use one of the complete distributions of BaseX (zip, exe, war) of BaseX.* All functions and errors are assigned to the <code><nowiki>http://basex.org/modules/ws</nowiki></code> namespace. The module must be imported in , which is statically bound to the query prolog: <pre class="brush:xquery">import module namespace {{Code|ws = "http://basex}} prefix.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..</pre>
=General Functions=
| '''Summary'''
|Returns the ID of the current WebSocket.
|-
| '''Errors'''
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.
|}
|-
| '''Summary'''
|Returns the ids of all currently registered WebSocketWebSockets.
|}
| '''Summary'''
|Returns the path of the WebSocket with the specified {{Code|$id}}.
|-
| '''Errors'''
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.
|}
| '''Summary'''
|Closes the connection of the WebSocket with the specified {{Code|$id}}.
|-
| '''Errors'''
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.
|}
|-
| width='120' | '''Signatures'''
|{{Func|ws:send|$message as xs:anyAtomicTypeitem(), $ids as xs:string*|empty-sequence()}}
|-
| '''Summary'''
|Sends a <code>$message</code>, which may be of type xs:string, xs:base64Binary or xs:hexBinary, 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:* Items of type {{Code|xs:base64Binary}} and {{Code|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.
|}
|-
| '''Summary'''
|Broadcasts a <code>$message</code>, which may be of type xs:string, xs:base64Binary or xs:hexBinary, 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|ws:send]] for more details on the message handling.
|}
|-
| '''Summary'''
|Emits a <code>$message</code>, which may be of type xs:string, xs:base64Binary or xs:hexBinary, to all connected clients. Invocations of this function are equivalent to <code>ws:send($message, ws:ids())</code>.See [[#ws:send|ws:send]] for more details on the message handling.|} ==ws:eval== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|ws:eval|$query as xs:anyAtomicItem|xs:string}}<br />{{Func|ws:eval|$query as xs:anyAtomicItem, $bindings as map(*)?|xs:string}}<br />{{Func|ws:eval|$query as xs:anyAtomicItem, $bindings as map(*)?, $options as map(*)?|xs:string}}<br />|-| '''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|base-uri}}: sets the [https://www.w3.org/TR/xquery-31/#dt-static-base-uri base-uri property] for the query. This URI will be used when resolving relative URIs, such as with {{Code|fn:doc}}.* {{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.|-| '''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.|-| '''Examples'''|* Schedule a second query that will notify the client 10 seconds later that a message was processed:<syntaxhighlight lang="xquery">declare %ws:message('/tasks', '{$message}')function local:message($message) { ws:eval('prof:sleep(10000), "Your message has been processed."')}; </syntaxhighlight>
|}
| '''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.
|-
| '''Errors'''
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.
|}
|-
| '''Errors'''
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.<br>{{Error|set|#Errors}} The supplied value cannot be materialized.
|}
| '''Summary'''
|Deletes an attribute with the specified {{Code|$name}} from the WebSocket with the specified {{Mono|$id}}.
|-
| '''Errors'''
|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.
|}
==Example 1==
<pre classsyntaxhighlight lang="brush:xquery">import module namespace ws = "http://basex.org/modules/Websocketws";
declare
%ws:connect('/')
function local:connect() as xs:string empty-sequence() {
let $id := ws:id()
let $message := json:serialize(map {
return ws:broadcast($message)
};
</presyntaxhighlight>
'''Explanation:'''
==Example 2==
<pre classsyntaxhighlight lang="brush:xquery">import module namespace ws = "http://basex.org/modules/Websocketws";
declare
function local:message(
$message as xs:string
) as xs:string empty-sequence() {
let $message := json:serialize(map { 'message': $message })
return ws:emit($message)
};
</presyntaxhighlight>
'''Explanation:'''
|-
|{{Code|not-found}}
|The No WebSocket with the specified WebSocket was not foundid exists.
|}
=Changelog=
 
;Version 9.2
 
* Added: [[#ws:eval|ws:eval]]
This module was introduced with Version 9.1.
Bureaucrats, editor, reviewer, Administrators
12,227

edits

Navigation menu