Changes

Jump to navigation Jump to search
5,430 bytes added ,  14:43, 27 February 2020
no edit summary
This [[Module Library|XQuery Module]] contains functions for accessing specific WebSocket functions and setting attributes on a WebSocket connection. This module is mainly useful in the context of [[WebSockets]].
=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/websocketws</nowiki></code> namespace. The module must be imported in , which is statically bound to the query prolog:<pre class="brush:xquery">import module namespace websocket = "http://basex{{Code|ws}} prefix.org/modules/websocket";* 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= ==ws:id== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|ws:id||xs:string}}|-| '''Summary'''|Returns the ID of the current WebSocket.|-| '''Errors'''|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.|} ==ws:ids== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|ws:ids||xs:string*}}|-| '''Summary'''|Returns the ids of all currently registered WebSockets.|} ==ws:path== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|ws:path|$id as xs:string|xs:string}}|-| '''Summary'''|Returns the path of the WebSocket with the specified {{Code|$id}}.|-| '''Errors'''|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.|} ==ws:close== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|ws:close|$id as xs:string|empty-sequence()}}|-| '''Summary'''|Closes the connection of the WebSocket with the specified {{Code|$id}}.|-| '''Errors'''|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.|} =Sending Data= ==ws:send== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|ws:send|$message as item(), $ids as xs:string*|empty-sequence()}}|-| '''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:* 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.|} ==ws:broadcast==
==websocket:broadcast==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|websocketws:broadcast|$message as xs:anyAtomicType|empty-sequence()}}
|-
| '''Summary'''
|Broadcasts a <code>$message</code> which may be of type xs:string, xs:base64Binary, or xs:hexBinary to all connected members 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.
|}
==websocketws:idemit== 
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|websocketws:id|emit|$message as xs:stringanyAtomicType|empty-sequence()}}
|-
| '''Summary'''
|Returns the ID 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|ws:send]] for more details on the current WebSocket connectionmessage handling.
|}
==websocketws:geteval== 
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|websocketws:geteval|$key 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'''
|Returns Schedules the evaluation of the supplied {{Code|$query}} and returns the result to the calling WebSocket attribute 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 key standard <code>$keyjob</code>prefix, and it can only be assigned if no job with the same name exists. If 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. <codebr/>${{Error|id|#Errors}} The specified id</code> parameter is set, it returns invalid or has already been assigned.|-| '''Examples'''|* Schedule a second query that will notify the attribute of client 10 seconds later that a specific User with the ID message was processed:<codesyntaxhighlight lang="xquery">declare %ws:message('/tasks', '{$message}')function local:message($idmessage) { ws:eval('prof:sleep(10000), "Your message has been processed."')}; </codesyntaxhighlight>
|}
=WebSocket Attributes=websocket ==ws:setget== 
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|websocketws:setget|$key id as xs:string, $value name as xs:string|empty-sequenceitem()*}}<br/>{{Func|ws:get|$id as xs:string, $name as xs:string, $default as item()*|item()*}}
|-
| '''Summary'''
|Sets a WebSocket Returns the value of an attribute with the key <code>specified {{Code|$key</code> and name}} from the value <code>WebSocket with the specified {{Code|$value</code>id}}. If the <code>$id</code> parameter attribute is setunknown, an empty sequence or the attribute of a specific user optionally specified {{Code|$default}} value will be returned instead.|-| '''Errors'''|{{Error|not-found|#Errors}} No WebSocket with the ID <code>$specified id</code> is setexists.
|}
==websocketws:deleteset== 
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|websocketws:deleteset|$key id as xs:string, $name as xs:string, $value as item()*|empty-sequence()}}
|-
| '''Summary'''
|Removes a session Returns the specified {{Code|value}} of the attribute with the specified {{Code|$name}} from the current WebSocketClient. If WebSocket with the <code>specified {{Mono|$id</code> parameter is set, the attribute of a specific user }}.|-| '''Errors'''|{{Error|not-found|#Errors}} No WebSocket with the ID <code>$specified idexists.</codebr> will {{Error|set|#Errors}} The supplied value cannot be deletedmaterialized.
|}
==websocketws:pathdelete== 
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|websocketws:path|delete|$id as xs:string, $name as xs:string|empty-sequence()}}
|-
| '''Summary'''
|Returns Deletes an attribute with the specified {{Code|$name}} from the path of WebSocket with the current WebSocketClientspecified {{Mono|$id}}. If |-| '''Errors'''|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.|} =Examples= ==Example 1== <codesyntaxhighlight 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 <code>%ws:connect</code> annotation. It gets called if a client successfully creates a WebSocket connection to the path <code>/</code> parameter (check out [[WebSockets]] for further information).* A JSON response is setgenerated, which contains the path of new client id and a specific user with the ID <code>Connect</code> 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': $idmessage }) return ws:emit($message)};</syntaxhighlight> '''Explanation:''' * The function has a <code>%ws:message</code> 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 returnedsent to all connected clients (including the calling client). =Errors= {| class="wikitable" width="100%"! width="110"|Code|Description|-|{{Code|set}}|The supplied value cannot be materialized.|-|{{Code|not-found}}|No WebSocket with the specified id exists.
|}
 
=Changelog=
 
;Version 9.2
 
* Added: [[#ws:eval|ws:eval]]
 
This module was introduced with Version 9.1.
Bureaucrats, editor, reviewer, Administrators
13,550

edits

Navigation menu