Difference between revisions of "WebSocket Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 18: Line 18:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|ws:send|$message as xs:anyAtomicType, $ids as xs:string* |empty-sequence()}}
+
|{{Func|ws:send|$message as xs:anyAtomicType, $ids as xs:string*|empty-sequence()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Sends a <code>$message</code> which may be of type xs:string, xs:base64Binary, or xs:hexBinary to the user(s) with the ID(s) <code>$ids</code>
+
|Sends a <code>$message</code>, which may be of type xs:string, xs:base64Binary or xs:hexBinary, to the users with the specified <code>$ids</code>.
 
|}
 
|}
  
Line 32: Line 32:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Broadcasts <code>$message</code> which may be of type xs:string, xs:base64Binary, or xs:hexBinary to all connected clients except to the caller.  
+
|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.
 
|}
 
|}
  
Line 43: Line 43:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Emits a <code>message</code> which may be of type xs:string, xs:base64Binary, or xs:hexBinary to all connected clients.
+
|Emits a <code>$message</code>, which may be of type xs:string, xs:base64Binary or xs:hexBinary, to all connected clients.
 
|}
 
|}
  
Line 65: Line 65:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the ids of all currently registered WebSocket client.
+
|Returns the ids of all currently registered WebSocket clients.
 
|}
 
|}
  
Line 73: Line 73:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|ws:path||xs:string}}<br>{{Func|ws:path|$id as xs:string|xs:string}}
+
|{{Func|ws:path|$id as xs:string|xs:string}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the path of the current WebSocket client, or the client with the specified {{Code|$id}}.
+
|Returns the path of the WebSocket client with the specified {{Code|$id}}.
 +
|}
 +
 
 +
==ws:close==
 +
 
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|ws:close|$id as xs:string|empty-sequence()}}
 +
|-
 +
| '''Summary'''
 +
|Closes the connection of the WebSocket client with the specified {{Code|$id}}.
 
|}
 
|}
  
Line 84: Line 95:
  
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
(: Import the WebSocket module :)
 
 
import module namespace ws = "http://basex.org/modules/Websocket";
 
import module namespace ws = "http://basex.org/modules/Websocket";
  
 
declare
 
declare
   %ws:connect("/")
+
   %ws:connect('/')
function local:connect(
+
function local:connect() as xs:string {
) as empty-sequence() {
+
   let $id := ws:id()
   let $client-id := ws:id()
+
   let $message := json:serialize(map {
   let $client-path := ws:path()
+
     'type': 'Connect',
  let $response := json:serialize(
+
    'id': $id
     <json type="object">
+
  })
      <messageType>UserConnected</messageType>
+
   return ws:broadcast($message)
      <clientId>{$client-id}</clientId>
 
      <clientPath>{$client-path}</clientPath>
 
    </json>
 
  )
 
   return ws:broadcast($response)
 
 
};
 
};
 
</pre>
 
</pre>
Line 106: Line 111:
 
'''Explanation:'''
 
'''Explanation:'''
  
* First of all: include the websocket module
+
* 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).
* The <code>$ws:connect("/")</code> annotation gets called if a client successfully creates a websocket to the path "/" (checkout [[WebSockets]] for further information).
+
* A JSON response is generated, which contains the new client id and a <code>Connect</code> string.
* Get the <code>client-id</code> and the <code>client-path</code> with <code>ws:id()</code> and <code>ws:path()</code>
+
* This response will be sent to all other connected clients.
* Create a json-result
 
* Broadcast the result to all connected clients without the calling client
 
  
 
==Example 2==
 
==Example 2==
  
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
(: Import the Websockets module :)
 
 
import module namespace ws = "http://basex.org/modules/Websocket";
 
import module namespace ws = "http://basex.org/modules/Websocket";
  
 
declare
 
declare
   %ws:message("/", "{$message}")
+
   %ws:message('/', '{$message}')
 
function local:message(
 
function local:message(
   $message as xs:string
+
   $message as xs:string
) as empty-sequence() {
+
) as xs:string {
   let $client-ids := ws:ids()
+
   let $message := json:serialize(map { 'message': $message })
  let $fist-client-id := fn:head($client-ids)
+
   return ws:emit($message)
  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>{ $path-first-client }</path>
 
    </json>
 
  )  
 
   return ws:emit($response)
 
 
};
 
};
 
</pre>
 
</pre>
Line 139: Line 132:
 
'''Explanation:'''
 
'''Explanation:'''
  
* First of all, import the websocket module
+
* The function has a <code>%ws:message</code> annotation. It gets called if a client sends a new message.
* The annotation <code>$ws:message("/",{$message}")</code> gets called if a message arrives at the server (checkout [[WebSockets]] for further information).
+
* A JSON response is generated, which contains the message string.
* With <code>ws:ids()</code> you will get the ids of all connected clients.
+
* This response will be sent to all connected clients (including the calling client).
* 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>
 

Revision as of 10:34, 27 September 2018

This XQuery Module contains functions for accessing specific WebSocket functions. This module is mainly useful in the context of WebSockets.

Conventions

  • The basex-api package must be included in the classpath. This is always the case if you use one of the complete distributions (zip, exe, war) of BaseX.
  • All functions and errors are assigned to the http://basex.org/modules/ws namespace. The module must be imported in the query prolog:
import module namespace ws = "http://basex.org/modules/ws";
...

Functions

ws:send

Signatures ws:send($message as xs:anyAtomicType, $ids as xs:string*) as empty-sequence()
Summary Sends a $message, which may be of type xs:string, xs:base64Binary or xs:hexBinary, to the users with the specified $ids.

ws:broadcast

Signatures ws:broadcast($message as xs:anyAtomicType) as empty-sequence()
Summary Broadcasts a $message, which may be of type xs:string, xs:base64Binary or xs:hexBinary, to all connected clients except to the caller.

ws:emit

Signatures ws:emit($message as xs:anyAtomicType) as empty-sequence()
Summary Emits a $message, which may be of type xs:string, xs:base64Binary or xs:hexBinary, to all connected clients.

ws:id

Signatures ws:id() as xs:string
Summary Returns the ID of the current WebSocket client.

ws:ids

Signatures ws:ids() as xs:string*
Summary Returns the ids of all currently registered WebSocket clients.

ws:path

Signatures ws:path($id as xs:string) as xs:string
Summary Returns the path of the WebSocket client with the specified $id.

ws:close

Signatures ws:close($id as xs:string) as empty-sequence()
Summary Closes the connection of the WebSocket client with the specified $id.

Examples

Example 1

import module namespace ws = "http://basex.org/modules/Websocket";

declare
  %ws:connect('/')
function local:connect() as xs:string {
  let $id := ws:id()
  let $message := json:serialize(map {
    'type': 'Connect',
    'id': $id
  })
  return ws:broadcast($message)
};

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

import module namespace ws = "http://basex.org/modules/Websocket";

declare
  %ws:message('/', '{$message}')
function local:message(
  $message as xs:string
) as xs:string {
  let $message := json:serialize(map { 'message': $message })
  return ws:emit($message)
};

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).