Difference between revisions of "WebSockets"
Line 8: | Line 8: | ||
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. | 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 | + | 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: | To speed up processing, the functions of the existing XQuery modules are automatically cached in main memory: | ||
Line 15: | Line 15: | ||
==Examples== | ==Examples== | ||
− | A first | + | A first WebSocket function is shown below: |
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
Line 35: | Line 35: | ||
=Usage= | =Usage= | ||
− | * Enable the | + | * Enable the WebSocket Servlet in the web.xml. You can set here the maxIdleTime, maxTextMessageSize and maxBinaryMessageSize too. |
<pre class="brush:xml"> | <pre class="brush:xml"> | ||
<servlet> | <servlet> | ||
Line 54: | Line 54: | ||
</servlet-mapping> | </servlet-mapping> | ||
</pre> | </pre> | ||
− | * Annotate your specific XQuery-Functions with | + | * Annotate your specific XQuery-Functions with WebSocketAnnotations. |
− | |||
− | |||
=Annotations= | =Annotations= | ||
==websocket:connect(path)== | ==websocket:connect(path)== | ||
− | Called when a Client-WebSocket-Connection successfully connected to the server. The <code>path</code> specifies the | + | 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)== | ==websocket:message(path,message)== | ||
− | Called when a | + | Called when a <code>message</code> arrives at the Server. The <code>path</code> specifies the <code>path</code> the 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. |
==websocket:close(path)== | ==websocket:close(path)== | ||
− | Called when the WebSocket closes. The <code>path</code> specifies the | + | Called when the WebSocket closes. The <code>path</code> specifies the <code>path</code> the Client is connected to. |
The WebSocket is already closed when this Annotation is called so there can be no return. | The WebSocket is already closed when this Annotation is called so there can be no return. | ||
==websocket:error(path,message)== | ==websocket:error(path,message)== | ||
− | Called when an Error occurred. Usually, this happens because of bad/malformed incoming packets. The <code>path</code> specifies the | + | Called when an Error occurred. Usually, this happens because of bad/malformed incoming packets. The <code>path</code> specifies the <code>path</code> the Client is connected to. The <code>message</code> is the Error-Message. |
The WebSocket gets closed after an error occurred. | The WebSocket gets closed after an error occurred. | ||
==websocket:path(name,variable[,default]== | ==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. | 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. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
=Parameters= | =Parameters= |
Revision as of 19:33, 1 August 2018
This page presents one of the Web Application services. It describes how to use the WebSockets API of BaseX.
Contents
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.
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.
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