Addons/net/websocket

Overview

The net/websocket addon provides a websocket server, which allows a web browser to make calls to J.

The server runs in one of two modes: base and JFE. The base mode is a standard websocket server and can handle any number of clients. The JFE mode allows the browser to function as an interactive J front end; this mode is for a single client only.

Note that the Jqt IDE (full build) supports websockets, see Guides/Window Driver/Websocket. This addon adds wrapper functions for a complete server application, and also runs in jconsole, so is more appropriate for a remote server.

Basic Usage

The addon is read into locale jws, which is also used as a class for client instances.

Message encoding can be either text or binary, and any message format such as JSON can be used. How the encoding or format of messages is handled depends on the application. There is no difference for the server itself.

Application-specific code can be added as required, for example, Jd for database access. To initialise the server, in jconsole:

load 'net/websocket'      NB. load the websocket server
load myapplication        NB. load application code as required
init_jws_ port [,mode]    NB. server listening port, mode is 0=base (default), 1=JFE

Customization

ws_onmessage

In the base mode, client messages are handled by ws_onmessage_jws_. An application can replace this as appropriate. The default behaviour is:

for text messages, execute the message as a J sentence and return the result. This is the most likely use for a J server.
for binary messages, return the reverse of the message. This helps for testing that the connection supports an arbitrary binary string, e.g. by sending a. (the alphabet).

Logging

By default, server activity is logged to directory ~temp/logs, and 3 days logs are kept. In the jws locale:

LogDir=: jpath '~temp/logs'
LogLen=: 3

Change these as required. To disable logging, set LogDir to empty.

Interrupt and Shutdown

interrupt_jws_ '' will interrupt the server. Enter restart'' in the server to restart it.

shutdown_jws_ '' will shutdown the server.

Demos

The addon includes four demos. For example, in a browser, open ~addons/net/websocket/demo1.html.

The demos are:

demo1 allows sentences to be sent to J for execution

demo2 calls J to access a database. For this the data/sqlite addon should be installed, and tested to ensure the sqlite binary has been downloaded.

demo3 is a simple interactive front end to J, using the JFE server

demo4 displays multi-dimensional data from J (not Firefox, see below)

Note that since these demos use web pages, they are subject to the vagaries of browsers and OS. They have been tested with recent versions of Chrome and Firefox on Windows, macOS and Linux, Internet Explorer on Windows and Safari on macOS.

The only problem found was that demo4 does not work properly on Firefox. This demo has buttons that can be dragged to rearrange the axes - but Firefox does not support draggable buttons. In practice this can be worked around, and is not a limitation of the websocket interface.

Jqt client

Jqt can function as a websocket client to test the websocket server, see examples in script ~addons/net/websocket/client.ijs. This requires the Jqt full build, see Guides/Qt_IDE/Install#Slim_vs_Full_Builds.

Source Code

The code for this addon is here: https://github.com/jsoftware/net_websocket