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.
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 [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 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 subprotocols .
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]].
* The WebSocket servlet
has to be enabled in the <code>web.xml</code> (which is the default case). You can specify the maxIdleTime, maxTextMessageSize and maxBinaryMessageSize here too. Check the standard <code> web.xml</code> for further informations. * 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 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.
write 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 path <code> '/ '< /code>. By using annotations its 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.