Boardwalk Client Virtual Machine - JavaScript

Introduction

The Boardwalk Client Virtual Machine - JavaScript (henceforth referred to as the BCVMJS) is a client library that simplifies interaction with the Boardwalk Application Engine. The BCVMJS is designed with following goals in mind:

• Simplify working with Boardwalk data
• Simplify access and invocation of the REST APIs in the Boardwalk Application Engine
• Enable access to multiple 'grids' in multiple application engines
• Load and maintain specific Boardwalk data items on the client-side, acting like a cache
• Provide a simplified mechanism for manipulating Boardwalk data
• Accumulate a series of changes on Boardwalk data, without having to submit to the server for each change.
• Submit such a series of changes in a single transaction to the Boardwalk Application Engine
• Provide access to the history of information stored in the Boardwalk Application Engine

To summarize, BCVMJS is a stateful client-side SDK that simplifies manipulation of data residing in an Boardwalk Application Engine.

About this document

This document will outline concepts and samples of BCVMJS to help a developer use the library in building an application.

How to use the BCVMJS

Download and Reference

Connect with BoardwalkTech Customer Support for downloading the BCVMJS library. Documentation is available at http://bcvmjs-doc.boardwalktech.com .

Initializing an Environment & Key Interfaces

Firstly, import the BCVMJS into your web page.

<script src="js/bcvm-v2.1.0.js"></script>

Importing the library also initializes it. It creates a local variable bcvm through which the library can be accessed.

To use the library, one must instanciate the Environment object. This object can load multiple grids into the client, provide editors for to manpipulate data, and enable communication with BAE. To initialize an Environment, you need the Credentials for accessing the BAE:

let env = bcvm.Srv().CreateEnvironment({
    usr: "username",
    membershipId: 1234,
    nhPath: "NH_Path",
    pwd: "password",
    urlPrefix: "http://server.boardwalktech.com/BAE_4_5/rest/v1",
});

Multiple instances of Environment object can be created such that

• each pointing to same server with same credentials
• each pointing to same server with different credentials
• each pointing to multiple servers with respective credentials

Viewing a Grid v/s Editing a Grid

The library comes with 2 sets of interfaces: one for viewing and one for editing grids. A typical Boardwalk Grid can contain data in the order of millions of cells. Hence the objects for viewing data are optimized for lower memory consumption, and do not support editing of the grid by default. The editor objects must be explicitly created for data manipulation. The key interfaces in this library are:

• IGridTxDelta
• IGridEditor

Creating a Grid

The following sample creates a Grid with 2 Columns and 5 Rows, and uses loops to initialize the cells to a value:

let ge = env.createGridEditor({
    collabId: 1234,
    wbId: 4321,
    name: "G" + new Date().toISOString(), // to ensure uniqueness in grid name
    description: "Test Sample Grid"
});

// insert 2 columns
let ce = null;
ce = ge.insertColumnAtStart("1");
ge.insertColumn("2", ce);

// insert 5 rows
let re = null;
re = ge.insertRowAtStart("1");
re = ge.insertRow("2", re);
re = ge.insertRow("3", re);
re = ge.insertRow("4", re);
ge.insertRow("5", re);

// use loops to initialize values
ge.getRows().forEach((rv, ri) => {
    ge.getColumns().forEach((cv, ci) => {
        ge.getCellEditorRC(rv.getRowKey(), cv.getColumnKey()).stringValue = ri + " : " + ci;
    });
});

// submit to grid
env.submitGrid(ge, { critical: true, criticalLevel: 16 }).then(function (ss) {
    console.log("Grid Creation Successful", ss.GridId);
}).catch(function (err) {
    console.log("Grid Creation Failed", err);
});

Loading an existing Grid

Mostly, the data manipulation may happen on an existing grid. Such a grid must first be loaded into the VM Environment, and then an editor can be used to manipulate that data. The 'Load' process in the VM takes a snapshot of the grid and makes it available in the VM, like caching.

let gridId = 1234567;
env.loadGridById(gridId).then(function () {
    console.log("Grid Load Successful", gridId);

    // ... manipulate the grid here
});

Editing an existing Grid

Below sample creates an editor on an existing grid, already loaded in the Environment.

// create an editor on a grid loaded in the environment
let ge2 = env.getGridEditor(gridId);

// add a row at the end, and update its cells values
let re2 = ge2.insertRowAtEnd("Last Row");
let cells = ge2.cells.getCellsByRowKey(re2.getRowKey());
cells.forEach((lv, li) => {
    lv.stringValue = "Last Row " + li;
});

// submit grid
env.submitGrid(ge2, { critical: true, criticalLevel: 16 }).then(function (ss) {
    console.log("Grid Updation Successful", ss);
}).catch(function (err) {
    console.log("Grid Updation Failure", err);
});

Library Documentation

Refer to the documentation of specific modules and classes for more information about methods and behaviors supported in the library. This documentation specifically includes only such elements which are consumed by a third-party user. There are several elements in the library which are for its internal working; the library documentation doesn't cover such elements.