Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
==ws:message(pathYou can specify here how to handle your users,message)==e. g. save a name as a WebSocket attribute. Furthermore, you can check header parameters for validity.
Called when a <code>==%ws:message</code> arrives at the server. The <code>(path</code> specifies the path which a client is connected to. The <code>message</code> is the <code>message</code> 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. )==
Called when an error has occurred. Usually, this happens errors happen because of bad/malformed incoming packets. The <code>path</code> specifies the path which a client is connected to. The <code>message</code> is the error message. The WebSocket connection gets closed after the error handling.
The following chapter explains how to create a simple basic webapplication with websockets.
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>.
()
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>.:
In the function above the WebSocketModule function <code>emit</code> is used for forwarding the message to all connected clients. Notice that you have to import the [[WebSocket Module]] before using it.
With In the code function above it , the [[WebSocket Module]] is possible to implement client-side functionality to connect to a WebSocket imported, and sendthe function <code>ws:emit</receive messages via code> is used for forwarding the WebSocketmessage to all connected clients.Following The following client-side code shows demonstrates a basic usage application of the WebSocket connection:
no edit summary
=Annotations=
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. 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.
Called when a <code>message</code> arrives at the server. The <code>path</code> specifies the path which a client is connected to. The <code>message</code> is the <code>message</code> sent by the client. It will be of type <code>xs:string</code> or <code>xs:base64Binary</code>. The client needs to take care of the message syntax, and it must not exceed the configured maximum size. ==%ws:close(path)==
Called when the WebSocket closes. The <code>path</code> specifies the path which a client is connected to.
The WebSocket is already closed when this annotation is called so there can be no return.
==%ws:error(path, message)== Called when an error occurs. The <code>path</code> specifies the path which a client is connected to.
==%ws:header-param(name,variable[,default])==
For accessing connection-specific parameters properties like the Http-Version or HTTP version. The value will be bound to the Sec-WebSocket-Versionspecified <code>variable</code>. If no value is available, an optional <code>default</code> value will be bound instead.
The following parameters are available: {| class="wikitable" |- valign="top"! Name! Description|- valign=Parameters==="top"| <code>http-version</code>| The following list shows HTTP version used for the parameters of a WebSocketrequest. You can access the parameters via the annotation |- valign="top"| <code>%ws:header-param(name,variable[,default])origin</code>* Http| The WebSocket origin.|-Version valign="top"| <code>protocol-version</code> f| The version of the used protocol (max.e1.: 3).|- valign="top"| <code>query-string</code>%ws:param("Http| The query string of the request URI.|-Versionvalign=", top"{$version}")| <code>is-secure</code>* Origin| Indicates if the connection is secure.|- valign="top"* Protocol| <code>is-Versionsecure</code>* QueryString| The Request URI to use for this request.* IsSecure|- valign="top"* RequestURI| <code>host</code>* Host| The host of the request URI.* Sec|-WebSocket-Versionvalign="top"* offset -| <code> just for binarysec-Messages* len websocket-version</code> just for binary-Messages| The websocket version.|}
=Tipps=
* For The [[WebSocket Module]] contains functions for interacting with other clients or manage specific clients you should check out the [[WebSocket Module]] as well.* The results of functions annotated with <code>%ws:close</code> or <code>%ws:error</code> will not be transmitted to the client.* For keeping the connection alive it is possible recommendable to implement use heart-beats , and send regular pings to the server.* Use <code>wss</code> instead of <code>ws</code> for a secure WebSocket connection.* If you use a proxy server, check its in the configuration if WebSocket support is WebSockets are enabled.
=Example=
The following chapter explains how to create a simple basic web application with WebSockets. You can find another example in the BaseX source 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.
<pre class="brush:xquery">
%ws:connect('/')
function example:connect() as empty-sequence() {
};
</pre>
<pre class="brush:xquery">
import module namespace ws = 'http://basex.org/modules/ws'
%ws:message('/', '{$message}')
function example:message(
$message as xs:string
) as empty-sequence() {
ws:emit($message)
};
</pre>
<pre>
var ws = new WebSocket("wssws://localhost:8984/ws");
ws.onmessage = function(event) {
alert(event.data);
</pre>
The <code>send</code> function can be called to pass on a string (e. g. a chat message) to the server. There are no heartbeats 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 of 3kb defined in the <code>web.xml</code> the connection gets closed toostandard text size.
