Changes

This page presents one of the [[Web Application]] services. It describes how to use the WebSockets API of BaseX. WebSocket is a communication protocol for providing '''full-duplex ''' communication: Data can be sent in both directions and simultaneously.

The Please note that the current WebSocket protocol was standardized in [https://tools.ietf.org/html/rfc6455 RFC 6455] by the IETFimplementation relies on Jetty’s WebSocket servlet API. After an initial HTTP-request, all communication takes place over a single TCP connection. In contrast to the HTTP protocol, a connection will Other web servers may be kept alive, and a server can send unsolicited data to the clientsupported in future versions.

=Introduction= ==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.  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. For establishing a WebSocket connection, a handshake request is sent by the client. The web server returns a handshake response. If the handshake is successful, the persistent connection will be open until an the client or the server closes it, an error occurs or a timeout happens. It is possible to transmit all kind of data, binary or text. '''The timeout can be specified BaseX WebServer handles the handshake completely.''' You just have to define some limits of the connection in the <code>web.xml</code> configuration fileand specify functions for WebSocket events like ''onConnect'' and ''onMessage''. It  Notice that there is possible to transmit all kind no specification of a message protocol. The WebSocket protocol just specifies the message architecture but not how the payload of data, binary or textthe messages is formatted. To agree on a format between the server and the client one can use sub-protocols.

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. 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]]. ==Configuration== * The WebSocket servlet can be enabled and disabled in the <code>web.xml</code> configuration file . You can specify further configuration options, such as <code>maxIdleTime</code>, <code>maxTextMessageSize</code>, and <code>maxBinaryMessageSize</code>.* The default limit for messges is 64 KB. If you a message exceeds the default or the specified limit, an error will be raised and the connection will be skippedclosed.

* 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 invalidated 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 parsed again if the timestamp of their module changesServlet will do the rest for you.

==Examples%ws:connect(path)==

Called directly after a successful WebSocket handshake. The <pre class="brush:xquery"code>path</code>module namespace page = 'httpspecifies the path which a client is connected to://basex.org/modules/web-page';

import module namespace ws <syntaxhighlight lang= "httpxquery">declare %ws:connect('/') function local:connect() { };</basex.org/modules/Websocket";syntaxhighlight>

%ws:connectclose("/"'host', '{$host}') %ws:header-param('host', '{$host}')function pagelocal:connectclose($host) { admin:write-log('Connection was closed: Do something after a client connects to the path "/" :' || $host)

declare %If you get the <code>[basex:ws:message("] WebSocket connection required</"code> error,"{$message}")function page:message( $message as xs:string) { (: Do something if you may be attempting to call WebSocket functions from a non-WebSocket context. If you use a message arrives at proxy server, check in the server :)};configuration if WebSockets are enabled.

declare %ws:close("/")function chat:close() { (: Return a close message with the id of the client who closes the connection :) let $client-id := ws:id() let $msg :Examples= json:serialize( <json type="object"> <type>WebsocketClosed</type> <idThatClosed>{$client-id}</idThatClosed> </json> ) (: Broadcast the message to all connected users except the client who closes the connection :) return ws:broadcast($msg)};</pre>

=Usage=Basic Example==

* Enable the WebSocket servlet in the The following chapter explains how to create a simple basic web.xmlapplication with WebSockets. You can set here the maxIdleTime, maxTextMessageSize and maxBinaryMessageSize too.* If you get a message that exceeds the maxTextMessageSize/maxBinaryMessageSize or, if not set, the default messageSize of Jetty of 65 536 bytes (64 kB) then the connection will close. In this case, find another example in the ws:error annotation will be calledBaseX source code.

First of all, you have to ensure that the <pre class="brush:xml"code><servlet> <servlet-name>wsservletWsServlet</servlet-namecode> is enabled in your <servlet-classcode>orgweb.basex.http.ws.WsServletxml</servlet-classcode> <init-param> <param-name>maxIdleTime</param-name> <param-value>100000</param-value> </init-param> <init-param> <param-name>maxTextMessageSize</param-name> <param-value>3000</param-value> </init-param></servlet><servlet-mapping> <servlet-name>wsservlet</servlet-name> <url-pattern>/ws/*</url-pattern></servlet-mapping></pre>* Annotate your specific XQuery-Functions with WebSocketAnnotationsfile. It will be enabled if you use the standard configuration of BaseX.

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=Annotations="xquery">declare %ws:connect('/')function example:connect() as empty-sequence() {};</syntaxhighlight>

==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:connectmessage(path"/")==</code>:

Called directly after a successful WebSocket handshake. The <codesyntaxhighlight lang="xquery">path<import module namespace ws = 'http://code> specifies the path to which a client is connected tobasex.org/modules/ws'

==declare %ws:message(path'/','{$message}')==function example:message( $message as xs:string) as empty-sequence() { ws:emit($message)};</syntaxhighlight>

Called when a <code>message</code> arrives at In the server. The <code>path</code> specifies function above, the path to which a client [[WebSocket Module]] is connected to. The imported, and the function <code>messagews:emit</code> is used for forwarding the <code>message</code> sent by the client. Could be a text-message or a binary-messageto all connected clients.

==wsThe following client-side code demonstrates a basic application of the WebSocket connection:close(path)==

Called when the WebSocket closes. The <code>path</codesyntaxhighlight lang="javascript"> specifies the path to which a client is connected to.The var ws = new WebSocket is already closed when this annotation is called so there can be no return.("ws://localhost:8984/ws");

ws.onmessage ==ws:errorfunction(event) { alert(path, messageevent.data)==;};

Called when an error has occurred. Usually, this happens because of bad/malformed incoming packets. The <code>path</code> specifies the path to which a client is connected tofunction send(message) { ws. The <code>send(message);};</codesyntaxhighlight> is the error message. The WebSocket connection gets closed after the error handling.

For accessing specific parameters like There are no heart-beats in this example. This means that the Http-Version or connection is terminated if nothing happens for 5 minutes (standard timeout). It will also be closed if you send a message that exceeds the Sec-WebSocket-Versionstandard text size.

=Parameters=Chat Application==

* HttpIn the full distributions of BaseX, you will find a little self-Version -> f.econtained chat application that demonstrates how WebSockets can be used in practice.: ```%ws:param("Http-Version", "{$version}")```* Origin* Protocol-Version* QueryString* IsSecure* RequestURI* Host* Sec-WebSocket-Version* offset -> just for binary-Messages* len -> just for binary-Messages

=TippsChangelog=

* For interacting WebSockets werre introduced with other clients or manage specific clients you should check out the [[WebSocket Module]] as wellVersion 9.1.