Difference between revisions of "WebSockets"

From BaseX Documentation
Jump to navigation Jump to search
(Created page with "This page presents one of the Web Application services. It describes how to use the WebSockets API of BaseX.")
 
Line 1: Line 1:
 
This page presents one of the [[Web Application]] services. It describes how to use the WebSockets API of BaseX.
 
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

Revision as of 12:33, 31 July 2018

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 files will be parsed for functions with Websocket annotations. Sub-directories that include an .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:

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>
      )
    )
  };

Usage

  • Enable the Websocket Servlet in the web.xml. You can set here the maxIdleTime, maxTextMessageSize and maxBinaryMessageSize too.
<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>
  • Annotate your specific XQuery-Functions with WebsocketAnnotations.
  • For using Websocket-Functions like broadcast or emit import the websocket-module:

import module namespace websocket = "http://basex.org/modules/Websocket";

Annotations

websocket:connect(path)

Called when a Client-WebSocket-Connection successfully connected to the server. The path specifies the Path the Client connected to.

websocket:message(path,message)

Called when a Message arrives at the Server. The path specifies the Path the Client is connected to. The message 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 path 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 path specifies the Path the Client is connected to. The message 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

Signatures websocket:emit($message as xs:string/xs:base64Binary) as empty-sequence()
Summary Emits a message to all connected Members.

websocket:broadcast

Signatures websocket:broadcast($message as xs:string/xs:base64Binary) as empty-sequence()
Summary Broadcasts message to all connected Members exept to the caller.

websocket:send

Signatures websocket:send($message as xs:string/xs:base64Binary, $id as xs:string ) as empty-sequence()
Summary Sends a message to the user with the ID $id

websocket:id

Signatures websocket:id() as xs:string
Summary Returns the ID of the current Websocket Connetion.

websocket:ids

Signatures websocket:ids() as xs:string*
Summary Returns the IDs of all current Websocket Connections.

websocket:get

Signatures websocket:get($key as xs:string) as xs:string
websocket:get($id as xs:string, $key as xs:string) as xs:string
Summary Returns the Websocket Attribute with the key $key. If the $id Parameter is set, it returns the Attribute of a Specific User with the ID $id

websocket:set

Signatures websocket:set($key as xs:string, $value as xs:string) as empty-sequence()
websocket:set($id as xs:string, $key as xs:string, $value as xs:string) as empty-sequence()
Summary Sets a Websocket Attribute with the key $key and the value $value. If the $id Parameter is set, the Attribute of a specific User with the ID $id is set.

websocket:delete

Signatures websocket:delete($key as xs:string) as empty-sequence()
websocket:delete($id as xs:string, $key as xs:string) as empty-sequence()
Summary Removes a Session Attribute from the current WebsocketClient. If the $id Parameter is set, the Attribute of a specific User with the ID $id will be deleted.

websocket:path

Signatures websocket:path() as xs:string
websocket:path($id as xs:string) as xs:string
Summary Returns the Path of the current WebsocketClient. If the $id Parameter is set, the Path of a specific User with the ID $id 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