WSLinkClient

Introduction

vtkWSLinkClient is a WSLink client for talking to a server over WebSocket

Methods

beginBusy

Virtually increase work load to maybe keep isBusy() on
while executing a synchronous task.

connect

Initiate the connection with the server

Argument Type Required Description
config Object Yes
configDecorator Function No (default: null)

disconnect

Disconnect from server

Argument Type Required Description
timeout Number Yes amount of second to wait before the server exit as well. If we want to avoid the server from quitting, -1 should be provided. (default=60)

endBusy

Virtually decreasing work load to maybe free isBusy()
after executing a synchronous task. Other async calls
could still keep the state as busy.

extend

Method use to decorate a given object (publicAPI+model) with vtkWSLinkClient characteristics.

Argument Type Required Description
publicAPI Yes object on which methods will be bounds (public)
model Yes object on which data structure will be bounds (protected)
initialValues object No (default: {})

getConfig

getConfigDecorator

Returns

Type Description
Function configDecorator function if any was provided

getConnection

getCreateImageStream

Returns

Type Description
Boolean the autoCreate state for imageStream

getImageStream

getNotBusyList

Returns

Type Description
object the current set of methods to ignore from busy state

getProtocols

Get protocols that were either provided in newInstance or via its set

getRemote

invokeBusyChange

isBusy

Return the current state of busy.
Do we still have pending calls?

isConnected

Return true if the client is currently connected to a server

newInstance

Method use to create a new instance of vtkWSLinkClient

Argument Type Required Description
initialValues object No for pre-setting some of its content

onBusyChange

Argument Type Required Description
callback Yes
priority Yes

registerProtocol

Register dynamically a protocol after being connected

Argument Type Required Description
name String Yes
protocol Function Yes

setConfigDecorator

Set a config decorator to possibly alterate the config object that get received from the launcher.

Argument Type Required Description
decorator Yes function for config object

setCreateImageStream

Should the client auto listen to image stream topic by creating its imageStream object

Argument Type Required Description
autoCreate Boolean Yes (default: true)

Returns

Type Description
Boolean true if the set method modified the object

setNotBusyList

Update the list of methods that should be ignore from the busy state monitoring

Returns

Type Description
Boolean true if the set method modified the object

setProtocols

Assign protocols to the client. Those will only be used at connect time and therefore needs to be set before being connected otherwise registerProtocol should be used instead.

Returns

Type Description
Boolean true if the set method modified the object

setSmartConnectClass

Bind optional dependency from WSLink to our current class.
This is mandatory when using that class

import SmartConnect from 'wslink/src/SmartConnect';
import vtkWSLinkClient from '@kitware/vtk.js/IO/Core/WSLinkClient';

vtkWSLinkClient.setSmartConnectClass(SmartConnect);
Argument Type Required Description
smartConnectClass Yes

unregisterProtocol

Remove a given protocol from the available list

Argument Type Required Description
name String Yes

Source

index.d.ts
import { vtkObject, vtkSubscription } from '../../../interfaces';
import vtkImageStream from '../ImageStream';

/**
* Bind optional dependency from WSLink to our current class.
* This is mandatory when using that class
*
* ```
* import SmartConnect from 'wslink/src/SmartConnect';
* import vtkWSLinkClient from '@kitware/vtk.js/IO/Core/WSLinkClient';
*
* vtkWSLinkClient.setSmartConnectClass(SmartConnect);
* ```
*
* @param smartConnectClass
*/
export function setSmartConnectClass(smartConnectClass: object): void;

export interface vtkWSLinkClient extends vtkObject {
/**
* Virtually increase work load to maybe keep isBusy() on
* while executing a synchronous task.
*/
beginBusy(): void;

/**
* Virtually decreasing work load to maybe free isBusy()
* after executing a synchronous task. Other async calls
* could still keep the state as busy.
*/
endBusy(): void;

/**
* Return the current state of busy.
* Do we still have pending calls?
*/
isBusy(): boolean;

/**
* Return true if the client is currently connected to a server
*/
isConnected(): boolean;

/**
* Initiate the connection with the server
* @param {Object} config
* @param {Function} [configDecorator] (default: null)
*/
connect(
config: object,
configDecorator?: (config: object) => object
): Promise<vtkWSLinkClient>;

/**
* Disconnect from server
* @param {Number} timeout amount of second to wait before the server exit as well. If we want to avoid the server from quitting, `-1` should be provided. (default=60)
*/
disconnect(timeout: number): void;

/**
* Register dynamically a protocol after being connected
*
* @param {String} name
* @param {Function} protocol
*/
registerProtocol(name: string, protocol: (session: object) => object): void;

/**
* Remove a given protocol from the available list
*
* @param {String} name
*/
unregisterProtocol(name: string): void;

// --- via macro --

/**
* Assign protocols to the client. Those will only be used at connect time and therefore needs to be set before being connected otherwise `registerProtocol` should be used instead.
* @returns {Boolean} true if the set method modified the object
*/
setProtocols(protocols: Record<string, any>): boolean;

/**
* Get protocols that were either provided in `newInstance` or via its set
*/
getProtocols(): Record<string, any>;

/**
* Update the list of methods that should be ignore from the busy state monitoring
* @returns {Boolean} true if the set method modified the object
*/
setNotBusyList(methodList: [string]): boolean;

/**
* @returns {object} the current set of methods to ignore from busy state
*/
getNotBusyList(): object;

/**
* Should the client auto listen to image stream topic by creating its imageStream object
* @param {Boolean} autoCreate (default: true)
* @returns {Boolean} true if the set method modified the object
*/
setCreateImageStream(autoCreate: boolean): boolean;

/**
* @returns {Boolean} the autoCreate state for imageStream
*/
getCreateImageStream(): boolean;

/**
* Set a config decorator to possibly alterate the config object that get received from the launcher.
* @param decorator function for config object
*/
setConfigDecorator(decorator: (config: object) => object): boolean;

/**
* @returns {Function} configDecorator function if any was provided
*/
getConfigDecorator(): (config: object) => object;

/**
*
*/
getConnection(): any;

/**
*
*/
getConfig(): object;

/**
*
*/
getRemote(): Record<string, any>;

/**
*
*/
getImageStream(): vtkImageStream;

/**
*
* @param callback
* @param priority
*/
onBusyChange(callback: Function, priority: number): vtkSubscription;

/**
*
*/
invokeBusyChange(): void;

onConnectionReady(callback: (httpReq: any) => void): vtkSubscription;
// invokeConnectionReady(): void

onConnectionError(callback: (httpReq: any) => void): vtkSubscription;
// invokeConnectionError(): void

onConnectionClose(callback: (httpReq: any) => void): vtkSubscription;
// invokeConnectionClose(): void
}

/**
* Method use to decorate a given object (publicAPI+model) with vtkWSLinkClient characteristics.
*
* @param publicAPI object on which methods will be bounds (public)
* @param model object on which data structure will be bounds (protected)
* @param {object} [initialValues] (default: {})
*/
export function extend(
publicAPI: object,
model: object,
initialValues?: object
): void;

// ----------------------------------------------------------------------------

/**
* Method use to create a new instance of vtkWSLinkClient
* @param {object} [initialValues] for pre-setting some of its content
*/
export function newInstance(initialValues?: object): vtkWSLinkClient;

/**
* vtkWSLinkClient is a WSLink client for talking to a server over WebSocket
*/
export declare const vtkWSLinkClient: {
newInstance: typeof newInstance;
extend: typeof extend;
// static
setSmartConnectClass: typeof setSmartConnectClass;
};

export default vtkWSLinkClient;
index.js
import macro from 'vtk.js/Sources/macros';

import vtkImageStream from 'vtk.js/Sources/IO/Core/ImageStream';

// ----------------------------------------------------------------------------
// Dependency injection
// ----------------------------------------------------------------------------

let SMART_CONNECT_CLASS = null;

// ----------------------------------------------------------------------------

function setSmartConnectClass(klass) {
SMART_CONNECT_CLASS = klass;
}

// ----------------------------------------------------------------------------
// Busy feedback handling
// ----------------------------------------------------------------------------

function busy(fn, update) {
return (...args) =>
new Promise((resolve, reject) => {
update(1);
fn(...args).then(
(response) => {
update(-1);
resolve(response);
},
(error) => {
update(-1);
reject(error);
}
);
});
}

// ----------------------------------------------------------------------------

function busyWrap(methodMap, update, skipList = []) {
const busyContainer = {};
Object.keys(methodMap).forEach((methodName) => {
if (skipList.indexOf(methodName) === -1) {
busyContainer[methodName] = busy(methodMap[methodName], update);
} else {
busyContainer[methodName] = methodMap[methodName];
}
});
return busyContainer;
}

// ----------------------------------------------------------------------------
// vtkWSLinkClient
// ----------------------------------------------------------------------------

function vtkWSLinkClient(publicAPI, model) {
// Set our className
model.classHierarchy.push('vtkWSLinkClient');

// --------------------------------------------------------------------------
// Internal methods
// --------------------------------------------------------------------------

function notifyBusy() {
publicAPI.invokeBusyChange(model.busyCount);
}

// --------------------------------------------------------------------------

function updateBusy(delta = 0) {
model.busyCount += delta;

// Clear any pending timeout
if (model.timeoutId) {
clearTimeout(model.timeoutId);
model.timeoutId = 0;
}

// Delay notification when idle
if (model.busyCount) {
notifyBusy();
} else {
model.timeoutId = setTimeout(notifyBusy, model.notificationTimeout);
}
}

// --------------------------------------------------------------------------
// Public methods
// --------------------------------------------------------------------------

publicAPI.beginBusy = () => updateBusy(+1);
publicAPI.endBusy = () => updateBusy(-1);
publicAPI.isBusy = () => !!model.busyCount;
publicAPI.isConnected = () => !!model.connection;

// --------------------------------------------------------------------------

publicAPI.connect = (config = {}, configDecorator = null) => {
if (!SMART_CONNECT_CLASS) {
return Promise.reject(new Error('Need to provide SmartConnect'));
}
if (model.connection) {
return Promise.reject(new Error('Need to disconnect first'));
}

model.config = config;
model.configDecorator = configDecorator || model.configDecorator;
return new Promise((resolve, reject) => {
model.smartConnect = SMART_CONNECT_CLASS.newInstance({
config,
configDecorator: model.configDecorator,
});

// ready
model.smartConnect.onConnectionReady((connection) => {
model.connection = connection;
model.remote = {};
model.config = model.smartConnect.getConfig();
const session = connection.getSession();

// Link remote API
model.protocols = model.protocols || {};
Object.keys(model.protocols).forEach((name) => {
model.remote[name] = busyWrap(
model.protocols[name](session),
updateBusy,
model.notBusyList
);
});

// Handle image stream if needed
if (model.createImageStream) {
model.imageStream = vtkImageStream.newInstance();
model.imageStream.connect(session);
}

// Forward ready info as well
publicAPI.invokeConnectionReady(publicAPI);

resolve(publicAPI);
});

// error
model.smartConnect.onConnectionError((error) => {
publicAPI.invokeConnectionError(error);
reject(error);
});

// close
model.smartConnect.onConnectionClose((close) => {
publicAPI.invokeConnectionClose(close);
reject(close);
});

// Start connection
model.smartConnect.connect();
});
};

// --------------------------------------------------------------------------

publicAPI.disconnect = (timeout = 60) => {
if (model.connection) {
model.connection.destroy(timeout);
model.connection = null;
}
};

// --------------------------------------------------------------------------

publicAPI.registerProtocol = (name, protocol) => {
model.remote[name] = busyWrap(
protocol(model.connection.getSession()),
updateBusy,
model.notBusyList
);
};

// --------------------------------------------------------------------------

publicAPI.unregisterProtocol = (name) => {
delete model.remote[name];
};
}

// ----------------------------------------------------------------------------
// Object factory
// ----------------------------------------------------------------------------

const DEFAULT_VALUES = {
// protocols: null,
// connection: null,
// config: null,
// imageStream
notBusyList: [],
busyCount: 0,
timeoutId: 0,
notificationTimeout: 50,
createImageStream: true,
// configDecorator: null,
};

// ----------------------------------------------------------------------------

export function extend(publicAPI, model, initialValues = {}) {
Object.assign(model, DEFAULT_VALUES, initialValues);

// Object methods
macro.obj(publicAPI, model);
macro.setGet(publicAPI, model, [
'protocols',
'notBusyList',
'createImageStream',
'configDecorator',
]);
macro.get(publicAPI, model, [
'connection',
'config',
'remote',
'imageStream',
]);
macro.event(publicAPI, model, 'BusyChange');
macro.event(publicAPI, model, 'ConnectionReady');
macro.event(publicAPI, model, 'ConnectionError');
macro.event(publicAPI, model, 'ConnectionClose');

// Object specific methods
vtkWSLinkClient(publicAPI, model);
}

// ----------------------------------------------------------------------------

export const newInstance = macro.newInstance(extend, 'vtkWSLinkClient');

// ----------------------------------------------------------------------------

export default { newInstance, extend, setSmartConnectClass };