administrator, editor
23
edits
Changes
Jump to navigation
Jump to search
A first WebSocket <pre class="brush:xquery">module namespace page = 'http://basex.org/modules/web-page';declare %ws:message("/","{$message}") function is shown belowchat:message( $message as xs:string ){ (: Do something if a message arrives at the server :) };</pre>
no edit summary
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.
After an initial HTTP-request it communicates over a single TCP connection. The WebSocket protocol was standardized in RFC 6455 by the IETF. It creates the possibility to transponse real-time data from the server to the client and the client to the server.
In contrast to the HTTP protocol it enables the server to send unsolicited data to the client. For establishing a WebSocket connection there is a WebSocket handshake request, send by the client. The server returns a WebSocket handshake response. This will be handled by jetty. After a successful handshake, the annotation <code>ws:connect</code> will be called. The persistent connection is now open until an the client or the server closes it, an error occures or a timeout happens. How long this timeout goes can be set in the web.xml. It is possible to transmit all kind of data, binary or text.
For further information about the WebSocket protocol check out the RFC6455 spec.
=Introduction=
==Preliminaries==
There are a bunch of annotations depending to WebSockets for annotating XQuery functions. When a WebSocket message comes inarrives 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 path '/', message to the Path path '/path', ...), 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}} the file will be skipped.
To speed up processing, the functions of the existing XQuery modules are automatically cached in main memory:
==Examples==
<pre class="brush:xquery">
module namespace page = 'http://basex.org/modules/web-page';
declare
%ws:connect("/")
function wsdba:connect(
) {
(: Do something after a client connects to the path "/" :)
};
</pre>
<pre class="brush:xquery">
module namespace page = 'http://basex.org/modules/web-page';
(: Import the websocket module :)
import module namespace websocket = "http://basex.org/modules/Websocket";
declare %ws:connectclose("/") function pagechat:connectclose( ) { (: Build a close message with the id of the client who closes the connection :) let $client-id := websocket:broadcastid() let $msg := json:serialize( <json type="object"> <type>ConnectWebsocketClosed</type> <idThatClosed>{$client-id}</idThatClosed> </json> ) (: Broadcast the message to all connected users except the client who closes the connection :) return websocket:broadcast($msg)
};
</pre>
==websocket:path(name,variable[,default]==
The value of the first parameter will be assigned to the variable specified as the second parameter. The third parameter can be a default value.
==websocket:header-param(name,variable[,default]==
For accessing specific parameters like the Http-Version or the Sec-WebSocket-Version.
=Parameters=
* offset -> just for binary-Messages
* len -> just for binary-Messages
=Tipps=
* For interacting with other clients or manage specific clients you should checkout the [[WebSocket Module]] and the [[WebSockets Module]] as well.
