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.

==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.In contrast to REST the WebSockets use a single URL for the whole communication.

The WebSocket protocol was standardized in 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://toolsen.ietfwikipedia.org/htmlwiki/rfc6455 RFC 6455Polling_(computer_science)] by the IETF. After an initial HTTP-requestIn contrast to REST, all communication takes place over WebSockets use a single TCP connection. Unlike URL for the HTTP protocol, a connection will be kept alive, and a server can send unsolicited data to the clientwhole communication.

For establishing a The WebSocket connection, a handshake request is sent protocol was standardized in [https://tools.ietf.org/html/rfc6455 RFC 6455] by the clientIETF. The web server returns After an initial HTTP request, all communication takes place over a handshake responsesingle TCP connection. If Unlike the handshake is successfulHTTP protocol, the persistent a connection will be open until the client or the server closes itkept alive, an error occurs or and a timeout happens. It is possible to transmit all kind of server can send unsolicited data, binary or text. '''The BaseX-WebServer handles the handshake completely.''' You just have to define some limits of the connection in the <code>web.xml</code> and specify functions for WebSocket events like ''onConnect'' and ''onMessage''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 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 BaseX WebServer handles the handshake completely.''' You just have to define some limits of the connection in the <code>web.xml</code> and specify functions for WebSocket events like ''onConnect'' and ''onMessage''. Notice that there is no specification of a message-protocol. The WebSocket protocol just specifies the message-architecture but not how the payload of the messages is formatted. To agree on a format between the server and the client one can use subprotocolssub-protocols. 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 library takes care of how to establish the real-time connection. If the WebSocket protocol isn’t supported, it uses polling. You have to provide server functions for the fallback 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 write tag functions that act 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 its , 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.