Changes

Jump to navigation Jump to search
3,361 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/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 {{Code|ws = "http://basex}} 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='120' | '''Signatures'''
|{{Func|ws:send|$message as xs:anyAtomicTypeitem(), $ids as xs:string* |empty-sequence()}}
|-
| '''Summary'''
|Sends a <code>$message</code> which may 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 xs:string, {{Code|xs:base64Binary, or }} and {{Code|xs:hexBinary to the user}} will be transmitted as binary messages.* Function items (smaps, arrays) will be serialized as JSON and transmitted as string messages.* All other items will be serialized with the ID(s) <code>$ids</code>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 to all connected clients. Invocations of type xsthis function are equivalent to <code>ws:stringsend($message, xsws:ids())</code>. See [[#ws:base64Binary, or xssend|ws:hexBinary to all connected clientssend]] for more details on the message handling.
|}
==ws:ideval==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|ws:ideval|$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 ID evaluation of the current 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 WebSocket connection10 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>
|}
=WebSocket Attributes= ==ws:idsget==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|ws:idsget|$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()*}}
|-
| '''Summary'''
|Returns the IDs value of all current an attribute with the specified {{Code|$name}} from the WebSocket connectionswith 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.
|}
==ws:pathset==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|ws:path|set|$id as xs:string, $name as xs:string, $value as item()*|empty-sequence()}}
|-
| '''Summary'''
|Returns the path specified {{Code|value}} of the current WebSocketClientattribute 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.<br>{{Error|set|#Errors}} The supplied value cannot be materialized.
|}
==ws:pathdelete==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|ws:pathdelete|$id as xs:string|, $name as xs:string|empty-sequence()}}
|-
| '''Summary'''
|Returns Deletes an attribute with the specified {{Code|$name}} from the path of specific user WebSocket with the ID <code>specified {{Mono|$id</code>}}.|-| '''Errors'''|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.
|}
=Example 1Examples=
==CodeExample 1==
<pre classsyntaxhighlight lang="brush:xquery">module namespace websocketexample = 'http://basex.org/modules/web-page';(: Import the WebSocket module :)import module namespace ws = "http://basex.org/modules/Websocketws";
declare
%ws:connect("'/"') function websocketexamplelocal:connect() as empty-sequence() { let $client-id := ws:id() let $client-path := ws:path() let $response message := json:serialize(map { <json 'type="object">': 'Connect', <messageType>UserConnected</messageType> <clientId>{ 'id': $client-id}</clientId> <clientPath>{$client-path }</clientPath> </json> ) return ws:broadcast($responsemessage)
};
</presyntaxhighlight==Explanation==
* First of all'''Explanation: include the websocket module* The <code>$ws:connect("/")</code> annotation gets called if a client successfully creates a websocket to the path "/" (checkout [[WebSockets]] for further information).* Get the <code>client-id</code> and the <code>client-path</code> with <code>ws:id()</code> and <code>ws:path()</code>* Create a json-result * Broadcast the result to all connected clients without the calling client'''
=Example 2=* 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> (check out [[WebSockets]] for further information).* A JSON response is generated, which contains the new client id and a <code>Connect</code> string.* This response will be sent to all other connected clients.
==CodeExample 2==
<pre classsyntaxhighlight lang="brush:xquery">(: Import the Websockets module :)import module namespace ws = "http://basex.org/modules/Websocketws";
declare
%ws:message("'/"',"'{$message}"')
function local:message(
$message as xs:string) as xs:string { let $clientempty-ids := ws:idssequence(){ let $fist-client-id := fn:head($client-ids) let $send-to-id := ws:send($message, $first-client-id) let $path-first-client := ws:path($first-client-id) let $response := json:serialize( <json type="object"> <messageType>PathFirstClient</messageType> <path>map { 'message': $path-first-client message }</path> </json> ) return ws:emit($responsemessage)
};
</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 sent 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=
</pre>;Version 9.2
==Explanatation==* Added: [[#ws:eval|ws:eval]]
* First of all, import the websocket This module* The annotation <code>$ws:message("/",{$message}")</code> gets called if a message arrives at the server (checkout [[WebSockets]] for further information)was introduced with Version 9.* With <code>ws:ids()</code> you will get the ids of all connected clients1.* The function <code>ws:send($message,$first-client-id)</code> sends the <code>$message</code> to the client with the id <code>$first-client-id</code>* <code>ws:path($first-client-id)</code> returns the path of the client with the id <code>$first-client-id</code>* To emit a message to all connected clients you call <code>ws:emit($response)</code>
Bureaucrats, editor, reviewer, Administrators
13,550

edits

Navigation menu