Changes

Jump to navigation Jump to search
6,312 bytes added ,  12:33, 31 July 2018
no edit summary
This page presents one of the [[Web Application]] services. It describes how to use the WebSockets API of BaseX.
 
 
=Introduction=
 
==Preliminaries==
 
There are a bunch of Annotations depending to WebSockets for annotating XQuery functions. When a WebSocket-Message comes in, 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 '/', message to the 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:
* Functions will be invalidated and parsed again if the timestamp of their module changes.
 
==Examples==
 
A first Websocket function is shown below:
 
<pre class="brush:xquery">
module namespace page = 'http://basex.org/modules/web-page';
import module namespace websocket = "http://basex.org/modules/Websocket";
declare
%ws:connect("/")
function page:connect(
) {
websocket:broadcast(
json:serialize(
<json type="object">
<type>Connect</type>
</json>
)
)
};
</pre>
 
=Usage=
* Enable the Websocket Servlet in the web.xml. You can set here the maxIdleTime, maxTextMessageSize and maxBinaryMessageSize too.
<pre class="brush:xml">
<servlet>
<servlet-name>wsservlet</servlet-name>
<servlet-class>org.basex.http.ws.WsServlet</servlet-class>
<init-param>
<param-name>maxIdleTime</param-name>
<param-value>100000</param-value>
</init-param>
<init-param>
<param-name>maxTextMessageSize</param-name>
<param-value>3000</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>wsservlet</servlet-name>
<url-pattern>/ws/*</url-pattern>
</servlet-mapping>
</pre>
* Annotate your specific XQuery-Functions with WebsocketAnnotations.
* For using Websocket-Functions like broadcast or emit import the websocket-module:
<code>import module namespace websocket = "http://basex.org/modules/Websocket";</code>
 
=Annotations=
==websocket:connect(path)==
Called when a Client-WebSocket-Connection successfully connected to the server. The <code>path</code> specifies the Path the Client connected to.
 
==websocket:message(path,message)==
Called when a Message arrives at the Server. The <code>path</code> specifies the Path the Client is connected to. The <code>message</code> is the Message sent by the Client. Could be a Text-Message or a binary Message.
 
==websocket:close(path)==
Called when the WebSocket closes. The <code>path</code> specifies the Path the Client is connected to.
The WebSocket is already closed when this Annotation is called so there can be no return.
 
==websocket:error(path,message)==
Called when an Error occurred. Usually, this happens because of bad/malformed incoming packets. The <code>path</code> specifies the Path the Client is connected to. The <code>message</code> is the Error-Message.
The WebSocket gets closed after an error occurred.
 
==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.
 
=Functions=
 
==websocket:emit==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|websocket:emit|$message as xs:string/xs:base64Binary|empty-sequence()}}
|-
| '''Summary'''
|Emits a <code>message</code> to all connected Members.
|}
 
==websocket:broadcast==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|websocket:broadcast|$message as xs:string/xs:base64Binary|empty-sequence()}}
|-
| '''Summary'''
|Broadcasts <code>message</code> to all connected Members exept to the caller.
|}
 
==websocket:send==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|websocket:send|$message as xs:string/xs:base64Binary, $id as xs:string |empty-sequence()}}
|-
| '''Summary'''
|Sends a <code>message</code> to the user with the ID <code>$id</code>
|}
 
==websocket:id==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|websocket:id||xs:string}}
|-
| '''Summary'''
|Returns the ID of the current Websocket Connetion.
|}
 
==websocket:ids==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|websocket:ids||xs:string*}}
|-
| '''Summary'''
|Returns the IDs of all current Websocket Connections.
|}
 
==websocket:get==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|websocket:get|$key as xs:string|xs:string}}<br/>{{Func|websocket:get|$id as xs:string, $key as xs:string|xs:string}}
|-
| '''Summary'''
|Returns the Websocket Attribute with the key <code>$key</code>. If the <code>$id</code> Parameter is set, it returns the Attribute of a Specific User with the ID <code>$id</code>
|}
 
==websocket:set==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|websocket:set|$key as xs:string, $value as xs:string|empty-sequence()}}<br/>{{Func|websocket:set|$id as xs:string, $key as xs:string, $value as xs:string|empty-sequence()}}
|-
| '''Summary'''
|Sets a Websocket Attribute with the key <code>$key</code> and the value $value. If the <code>$id</code> Parameter is set, the Attribute of a specific User with the ID <code>$id</code> is set.
|}
 
==websocket:delete==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|websocket:delete|$key as xs:string|empty-sequence()}}<br/>{{Func|websocket:delete|$id as xs:string, $key as xs:string|empty-sequence()}}
|-
| '''Summary'''
|Removes a Session Attribute from the current WebsocketClient. If the <code>$id</code> Parameter is set, the Attribute of a specific User with the ID <code>$id</code> will be deleted.
|}
 
==websocket:path==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|websocket:path||xs:string}}<br/>{{Func|websocket:path|$id as xs:string|xs:string}}
|-
| '''Summary'''
|Returns the Path of the current WebsocketClient. If the <code>$id</code> Parameter is set, the Path of a specific User with the ID <code>$id</code> will be returned.
|}
 
=Parameters=
* Http-Version -> f.e.: ```%ws:param("Http-Version", "{$version}")```
* Origin
* Protocol-Version
* QueryString
* IsSecure
* RequestURI
* Host
* Sec-WebSocket-Version
* offset -> just for binary-Messages
* len -> just for binary-Messages
administrator, editor
23

edits

Navigation menu