WebSockets - Revision history

CG: Text replacement - "syntaxhighlight" to "pre"

2023-12-01T16:38:55Z

Text replacement - "syntaxhighlight" to "pre"

CG: Text replacement - "" to ""

2023-12-01T16:33:11Z

Text replacement - "</syntaxhighlight>" to "</pre>"

CG: Text replacement - "" to "

2023-12-01T16:29:51Z

Text replacement - "<syntaxhighlight lang="xquery">" to "<pre lang='xquery'>"

CG: /* Basic Example */

2023-03-09T13:00:14Z

Basic Example

CG: Text replacement - "ub-director" to "ubdirector"

2022-07-25T13:59:38Z

Text replacement - "ub-director" to "ubdirector"

CG at 07:41, 19 July 2022

2022-07-19T07:41:51Z

Joe Wicentowski: Fix markup for wikipedia link

2021-06-02T20:01:06Z

Fix markup for wikipedia link

CG: Text replacement - "==%" to "=="

2020-07-27T09:54:16Z

Text replacement - "==%" to "=="

CG at 12:18, 27 February 2020

2020-02-27T12:18:54Z

CG at 15:06, 31 October 2018

2018-10-31T15:06:53Z

@@ Line 170: / Line 170: @@
 The following client-side code demonstrates a basic application of the WebSocket connection:
-<syntaxhighlight lang="javascript">
+<pre lang="javascript">
 var ws = new WebSocket("ws://localhost:8080/ws");

@@ Line 40: / Line 40: @@
 <pre lang='xquery'>
 declare %ws:connect('/') function local:connect() { };
-</syntaxhighlight>
+</pre>
 You can specify here how to handle your users, e. g. save a name as a WebSocket attribute. Furthermore, you can check header parameters for validity.
@@ Line 50: / Line 50: @@
 <pre lang='xquery'>
 declare %ws:message('/', '{$info}') function local:message($info) { };
-</syntaxhighlight>
+</pre>
 The value will be of type <code>xs:string</code> or <code>xs:base64Binary</code>. As there is no fixed message protocol, the client needs to take care of the message syntax.
@@ Line 60: / Line 60: @@
 <pre lang='xquery'>
 declare %ws:error('/', '{$error}') function local:error($error) { };
-</syntaxhighlight>
+</pre>
 Usually, errors happen because of bad/malformed incoming packets. The WebSocket connection gets closed after the error handling.
@@ Line 70: / Line 70: @@
 <pre lang='xquery'>
 declare %ws:close('/') function local:connect() { };
-</syntaxhighlight>
+</pre>
 The WebSocket is already closed when this annotation is called so there can be no return.
@@ Line 85: / Line 85: @@
    admin:write-log('Connection was closed: ' || $host)
 };
-</syntaxhighlight>
+</pre>
 The following parameters are available:
@@ Line 150: / Line 150: @@
 function example:connect() as empty-sequence() {
 };
-</syntaxhighlight>
+</pre>
 The connect function is sufficient for creating the persistent client/server connection. In order to something sensible with the connection, you should implement a function annotated with <code>%ws:message("/")</code>:
@@ Line 164: / Line 164: @@
    ws:emit($message)
 };
-</syntaxhighlight>
+</pre>
 In the function above, the [[WebSocket Module]] is imported, and the function <code>ws:emit</code> is used for forwarding the message to all connected clients.
@@ Line 180: / Line 180: @@
    ws.send(message);
 };
-</syntaxhighlight>
+</pre>
 The <code>send</code> function can be called to pass on a string to the server.

@@ Line 38: / Line 38: @@
 Called directly after a successful WebSocket handshake. The <code>path</code> specifies the path which a client is connected to:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 declare %ws:connect('/') function local:connect() { };
 </syntaxhighlight>
@@ Line 48: / Line 48: @@
 Called when a client message arrives at the server. The <code>path</code> specifies the path which a client is connected to. The <code>message</code> string contains the name of the variable to which the message will be bound:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 declare %ws:message('/', '{$info}') function local:message($info) { };
 </syntaxhighlight>
@@ Line 58: / Line 58: @@
 Called when an error occurs. The <code>path</code> specifies the path which a client is connected to. The <code>message</code> string contains the name of the variable to which the message will be bound:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 declare %ws:error('/', '{$error}') function local:error($error) { };
 </syntaxhighlight>
@@ Line 68: / Line 68: @@
 Called when the WebSocket closes. The <code>path</code> specifies the path which a client is connected to:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 declare %ws:close('/') function local:connect() { };
 </syntaxhighlight>
@@ Line 78: / Line 78: @@
 For accessing connection-specific properties like the HTTP version. The value will be bound to the specified <code>variable</code>. If the property has no value, an optional <code>default</code> value will be assigned instead:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 declare
    %ws:close('host', '{$host}')
@@ Line 145: / Line 145: @@
 For establishing a connection to the WebSocket server, it is necessary that the server provides at least one function annotated with a WebSocket annotation. Let’s start by using the annotation <code>%ws:connect('/')</code>. In the connect function, a bidirectional communication with the client can be initialized: attributes such as the id and name of a client can be set, or a welcome message can be emitted to other connected users, and so on.
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 declare
    %ws:connect('/')
@@ Line 154: / Line 154: @@
 The connect function is sufficient for creating the persistent client/server connection. In order to something sensible with the connection, you should implement a function annotated with <code>%ws:message("/")</code>:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 import module namespace ws = 'http://basex.org/modules/ws';

@@ Line 155: / Line 155: @@
 <syntaxhighlight lang="xquery">
-import module namespace ws = 'http://basex.org/modules/ws'
+import module namespace ws = 'http://basex.org/modules/ws';
 declare

@@ Line 21: / Line 21: @@
 There are a bunch of annotations depending to WebSockets for annotating XQuery functions. When a WebSocket message arrives at the server, an XQuery function will be invoked that matches the constraints indicated by its annotations.
-If a WebSocket function is requested (like connecting to the path <code>/</code>, sending a message to the path <code>/path</code>, …), the module directory and its sub-directories will be traversed, and all [[XQuery Extensions#Suffixes|XQuery files]] will be parsed for functions with WebSocket annotations. Sub-directories that include an {{Code|.ignore}} file will be skipped.
+If a WebSocket function is requested (like connecting to the path <code>/</code>, sending a message to the path <code>/path</code>, …), the module directory and its subdirectories will be traversed, and all [[XQuery Extensions#Suffixes|XQuery files]] will be parsed for functions with WebSocket annotations. Subdirectories that include an {{Code|.ignore}} file will be skipped.
 To speed up processing, the functions of the existing XQuery modules are automatically cached in main memory. For further information on cache handling, check out the [[RESTXQ#Introduction|RESTXQ introduction]].

@@ Line 171: / Line 171: @@
 <syntaxhighlight lang="javascript">
-var ws = new WebSocket("ws://localhost:8984/ws");
+var ws = new WebSocket("ws://localhost:8080/ws");
 ws.onmessage = function(event) {

@@ Line 7: / Line 7: @@
 ==Protocol==
-Use WebSockets if you have to exchange data with a high frequency or if you have to send messages from the server to the client without techniques like [polling https://en.wikipedia.org/wiki/Polling_(computer_science)]. In contrast to REST, WebSockets use a single URL for the whole communication.
+Use WebSockets if you have to exchange data with a high frequency or if you have to send messages from the server to the client without techniques like [https://en.wikipedia.org/wiki/Polling_(computer_science) polling]. In contrast to REST, WebSockets use a single URL for the whole communication.
 The WebSocket protocol was standardized in [https://tools.ietf.org/html/rfc6455 RFC 6455] by the IETF. After an initial HTTP request, all communication takes place over a single TCP connection. Unlike the HTTP protocol, a connection will be kept alive, and a server can send unsolicited data to the client.

@@ Line 34: / Line 34: @@
 To tag functions as WebSocket functions you have to use [[XQuery 3.0#Annotations|annotations]]. The annotation is written after the keyword ''declare'' and before the keyword ''function''. For the context of WebSockets there are some annotations listed below. Functions which are annotated with a WebSocket annotation will be called if the appropriate event occurs. For example, the function annotated with <code>ws:connect('/')</code> will be executed if a client establishes a connection with the WebSocket root path (which is, by default, <code>ws/</code>). By using annotations, it’s easy to provide an API for your WebSocket connection. You just have to specify what to do when a WebSocket Event occurs, annotate it with the corresponding annotation and the Servlet will do the rest for you.
-==%ws:connect(path)==
+==ws:connect(path)==
 Called directly after a successful WebSocket handshake. The <code>path</code> specifies the path which a client is connected to:
@@ Line 44: / Line 44: @@
 You can specify here how to handle your users, e. g. save a name as a WebSocket attribute. Furthermore, you can check header parameters for validity.
-==%ws:message(path, message)==
+==ws:message(path, message)==
 Called when a client message arrives at the server. The <code>path</code> specifies the path which a client is connected to. The <code>message</code> string contains the name of the variable to which the message will be bound:
@@ Line 54: / Line 54: @@
 The value will be of type <code>xs:string</code> or <code>xs:base64Binary</code>. As there is no fixed message protocol, the client needs to take care of the message syntax.
-==%ws:error(path, message)==
+==ws:error(path, message)==
 Called when an error occurs. The <code>path</code> specifies the path which a client is connected to. The <code>message</code> string contains the name of the variable to which the message will be bound:
@@ Line 64: / Line 64: @@
 Usually, errors happen because of bad/malformed incoming packets. The WebSocket connection gets closed after the error handling.
-==%ws:close(path)==
+==ws:close(path)==
 Called when the WebSocket closes. The <code>path</code> specifies the path which a client is connected to:
@@ Line 74: / Line 74: @@
 The WebSocket is already closed when this annotation is called so there can be no return.
-==%ws:header-param(name, variable[, default])==
+==ws:header-param(name, variable[, default])==
 For accessing connection-specific properties like the HTTP version. The value will be bound to the specified <code>variable</code>. If the property has no value, an optional <code>default</code> value will be assigned instead:

← Older revision		Revision as of 15:06, 31 October 2018
Line 189:		Line 189:

	In the full distributions of BaseX, you will find a little self-contained chat application that demonstrates how WebSockets can be used in practice.		In the full distributions of BaseX, you will find a little self-contained chat application that demonstrates how WebSockets can be used in practice.
		+
		+	=Changelog=
		+
		+	WebSockets werre introduced with Version 9.1.