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. Please note that the current WebSocket implementation relies on Jetty’s WebSocket servlet API. Other web servers may be supported in future versions.

==WebSocket 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[polling https://en.wikipedia.org/wiki/Polling_(computer_science)].In contrast to REST the , 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.

The For establishing a WebSocket protocol was standardized in [https://tools.ietf.org/html/rfc6455 RFC 6455] connection, a handshake request is sent by the IETFclient. After an initial HTTP-request, all communication takes place over The web server returns a single TCP connectionhandshake response. Unlike If the HTTP protocolhandshake is successful, a the persistent connection will be kept aliveopen until the client or the server closes it, and an error occurs or a server can send unsolicited timeout happens. It is possible to transmit all kind of data , binary or text. '''The BaseX WebServer handles the handshake completely.''' You just have to define some limits of the connection in the client<code>web.xml</code> and specify functions for WebSocket events like ''onConnect'' and ''onMessage''.

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

Notice that there is no specification of a message-Some older browsers don’t support the WebSocket protocol. Therefore you can use fallback options like Ajax. JavaScript client libraries like SockJS can be used for building client applications. The WebSocket protocol just specifies library takes care of how to establish the messagereal-architecture but not how time connection. If the payload of the messages is formattedWebSocket protocol isn’t supported, it uses polling. To agree on a format between the You have to provide server and functions for the client one can use subprotocolsfallback solutions if you have to support fallbacks.

=Usage=Configuration==

* The WebSocket servlet has to can be enabled and disabled in the <code>web.xml</code> (which is the default case)configuration file. You can specify the further configuration options, such as <code>maxIdleTime</code>, <code>maxTextMessageSize </code>, and maxBinaryMessageSize here too. Check the standard <code>web.xmlmaxBinaryMessageSize</code> for further informations. * The default limit for messges is 64 KB. If you get a message that exceeds the maxTextMessageSize/maxBinaryMessageSize default orthe specified limit, if not set, the default messageSize of Jetty of 65 536 bytes (64 kB) then an error will be raised and the connection will be closed. In this case, the <code>ws:error</code> annotation will be called. * Annotate your specific XQuery-Functions with WebSocketAnnotations. You have to specify at least one WebSocket function.

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)== Called directly after a successful WebSocket handshake. The <code>path</code> specifies the path which a client is connected to: <pre class="brush:xquery">declare %ws:connect('/') function local:connect() { };</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.  ==%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: <pre class="brush:xquery">declare %ws:message('/', '{$info}') function local:message($info) { };</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.

Called directly after a successful WebSocket handshake. The <code>==%ws:error(path</code> specifies the path which a client is connected to. You can specify here how to handle your users, f.e. save a name as a WebSocket attribute. Furthermore, you can check here some of the header-params for validity. message)==

==ws:Called when an error occurs. The <code>path</code> specifies the path which a client is connected to. The <code>message(path,</code> string contains the name of the variable to which the message)==will be bound:

Called when a <codepre class="brush:xquery">message</code> arrives at the server. The <code>path</code> specifies the path which a client is connected to. The <code>message<declare %ws:error('/code> is the <code>message', '{$error}') function local:error($error) { };</codepre> sent by the client. Could be a text-message or a binary-message. It should be ensured that the format of the message is correct.

Usually, errors happen because of bad/malformed incoming packets. The WebSocket connection gets closed after the error handling. ==%ws:close(path)== Called when the WebSocket closes. The <code>path</code> specifies the path which a client is connected to: <pre class="brush:xquery">declare %ws:close('/') function local:connect() { };</pre>

==%ws:errorheader-param(pathname, messagevariable[, 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: <pre class="brush:xquery">declare %ws:close('host', '{$host}') %ws:header-param('host', '{$host}')function local:close($host) { admin:write-log('Connection was closed: ' || $host)};</pre> The following parameters are available: {| class="wikitable" |- valign="top"! Name! Description|- valign="top"| <code>host</code>| The host of the request URI.|- valign="top"| <code>http-version</code>| The HTTP version used for the request.|- valign="top"| <code>is-secure</code>| Indicates if the connection is secure.|- valign="top"| <code>origin</code>| The WebSocket origin.|- valign="top"| <code>protocol-version</code>| The version of the used protocol.|- valign="top"| <code>query-string</code>| The query string of the request URI.|- valign="top"| <code>request-uri</code>| The Request URI to use for this request.|- valign="top"| <code>sub-protocols</code>| List of configured sub-protocols.|} General information on the request can be retrieved via the [[Request Module]]. =Writing Applications= The [[WebSocket Module]] contains functions for interacting with other clients or manage specific clients. For example, you can store and access client-specific properties for a WebSocket connection or close the connection of clients. Note that one WebSocket connection can be opened per browser tab. In contrast, only one HTTP session exists for multiple tabs in in a browser. If you want to keep client-specific data on the web server, you can either store them in HTTP sessions or in the WebSocket connection.

Called when an error has occurred. Usually, this happens because Note further that the results of bad/malformed incoming packets. The functions annotated with <code>path%ws:close</code> specifies the path which a client is connected to. The or <code>message%ws:error</code> is will not be transmitted to the error messageclient. The WebSocket connection gets closed after the error handlingBoth annotations have rather been designed to gracefully close connections, write log data, remove clients from session data, etc.

==ws:headerFor keeping the connection alive it is recommendable to use heart-param(namebeats,variable[and send regular pings to the server. There is no ideal timespan for sending pings: It should not be sent too often,default])==but you should also consider possible network latencies.

For accessing specific parameters like If your HTTP connection is secure, you should use the Http-Version or <code>wss</code> instead of the Sec-WebSocket-Version<code>ws</code> scheme.

===Parameters===The following list shows If you get the parameters of a WebSocket. You can access the parameters via the annotation <code>%[basex:ws:header-param(name,variable[,default])WebSocket connection required</code>* Httperror, you may be attempting to call WebSocket functions from a non-Version -> fWebSocket context.eIf you use a proxy server, check in the configuration if WebSockets are enabled.: <code>%ws:param("Http-Version", "{$version}")</code>* Origin* Protocol-Version* QueryString* IsSecure* RequestURI* Host* Sec-WebSocket-Version* offset -> just for binary-Messages* len -> just for binary-Messages

=TippsExamples=

=Example=The following chapter explains how to create a simple basic webapplication web application with websocketsWebSockets. You can find another example in the BaseX source code. First of all you have to ensure that the WsServlet is enabled in your <code>web.xml</code>. It will be enabled if you use the standard <code>web.xml</code>.

First of all, you have to ensure that the <code>WsServlet</code> is enabled in your <code>web.xml</code> file. 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. Lets Let’s start by using the annotation <code>%ws:connect('/')</code>.In the connect function, specific WebSocket a bidirectional communication with the client can be initialized: attributes like such as the id and nameof a client can be set, emit or a welcome message can be emitted to other connected users, write database entries, do nothing, ... can be setand so on.

With The connect function is sufficient for creating the state until now you can create a connection between persistent client and /serverconnection. For doing sth. senseful In order to something sensible with the WebSocket connection , you should implement a function annotated with <code>%ws:message("/")</code>.: 

It is possible now to write client functions which connect to a WebSocketIn the function above, send messages to the [[WebSocket Module]] is imported, and receive messages from the WebSocketfunction <code>ws:emit</code> is used for forwarding the message to all connected clients.  The following client example provides -side code demonstrates a basic code for handling application of the WebSocket connection.: <pre class="brush:java">var ws = new WebSocket("ws://localhost:8984/ws");

The <code>send</code> function can be called to pass on a string to the server. There are no heart-beats in this example. This means that the connection is terminated if nothing happens for 5 minutes (standard timeout).If It will also be closed if you send a message which that exceeds the textsize standard text size. ==Chat Application== In the full distributions of 3kb defined BaseX, you will find a little self-contained chat application that demonstrates how WebSockets can be used in the <code>webpractice. =Changelog= WebSockets werre introduced with Version 9.xml</code> the connection gets closed too1.