Example Collection

# Example Collection

This repository contains a collection of KGrid Knowledge Objects that demonstrate features of the grid, good development practices, and useful tools.

# Anatomy of this Knowledge Object project.

The following structure is not an requirement or enforced, it is a recommendation based on what the JavaScript and in particular Node community at large have been following by convention.

# Prerequisites

  • There are some bundled objects that have packaging features that require npm, npm is installed with Node.js npm.
  • There are also some that require python, which will also be required to run the remote python runtime.

# Directories

  • collection/ contains one to many directories representing knowledge objects

    • object-name a directory for each knowledge object (e.g. js-simple-v1.0)

  • docs/ is a sub-directory for this information about these KOs

  • performanceTest/ contains performance tests that will send a number of requests to an activator endpoint. You must have K6 installed. Tests can be run from the performanceTest directory with: k6 run -e URL=<Endpoint URL to be tested> k6post.js -u <Amount of users> -i <Amount of iterations>

    example: k6 run -e URL=http://localhost:8080/js/simple/1.0/welcome k6post.js -u 10 -i 1000

  • test-collection/ contains a few objects that contain errors for the purpose of debugging Kgrid components.

# Example Knowledge Objects

  • JS Simple v1.0 - Simple KO designed as a starting point. Demonstrates a simple project structure that runs in the Graal environment using the javascript adapter.
  • JS Bundled v1.0 - A bundled knowledge object that uses node to take multiple code artifacts and bundle into one file that can be run in the Graal environment. Requires node.js to build the object before it will run in the Knowledge Grid activator.
  • JS Executive v1.0 - An executive knowledge object which calls another object in the Knowledge Grid in the Graal engine. Both this object and the object it calls have to be nashorn javascript objects.
  • JS Multiartifact v1.0 - Simple KO designed as a starting point. Demonstrates a simple project structure that runs in the Graal environment using the javascript adapter, but with multiple artifacts.
  • JS Multimime v1.0 - Simple KO designed as a starting point. Demonstrates a simple project structure that runs in the Graal environment using the javascript adapter, but with multiple endpoints exhibiting different mime types.
  • Node Simple v1.0 - A javascript object that is run remotely in the node runtime. Requires a node runtime that is connected to the activator to run.
  • Node Executive v1.0 - A javascript object that calls other objects and is run remotely in the node runtime. Requires a node runtime that is connected to the activator to run.
  • Node Multiartifact v1.0 - A javascript object that has multiple code artifacts and is run remotely in the node runtime. Requires a node runtime that is connected to the activator to run.
  • Python Simple v1.0 - A python object that is run remotely in the python runtime. Requires a node runtime that is connected to the activator to run.
  • Python Executive v1.0 - A python object that calls other objects and is run remotely in the python runtime. Requires a node runtime that is connected to the activator to run.
  • Python Multiartifact v1.0 - A python object that has multiple code artifacts and is run remotely in the python runtime. Requires a node runtime that is connected to the activator to run.
  • Python Multimime v1.0 - A python object that has multiple endpoints of differing mime types and is run remotely in the python runtime. Requires a node runtime that is connected to the activator to run.
  • Resource Simple v1.0 - A static resource object with a GET http endpoint that works with the resource adapter, and returns artifact binaries.

# Adapters and running Knowledge Objects

Currently, the KGrid Activator has several adapters that can be used to run knowledge objects:

  • The graal javascript engine adapter for execution of JavaScript Objects. Graal implements ECMAScript 2020 specification
  • The proxy adapter can use our node.js runtime which will run javascript in a node.js environment and can load external dependencies.
  • The proxy adapter can also use our python runtime, which can run python and load python dependencies just like any other python engine
  • The Activator also makes use of our resource adapter in order to expose resource-based endpoints defined in resource Knowledge Objects.

These are all included in the KGrid Activator project however the runtimes must be run separately to activate objects that require them.

# Running Example KOs in an Activator

To try these objects you can either clone this project or download a released version of the objects directly or using a manifest. This is done most easily via the kgrid cli.

Download the cli using

npm install -g @kgrid/cli

and run

kgrid setup

to download the required kgrid components and then in the /collection directory run

kgrid start:activator

to start an activator that loads the example collection. You can then browse the collection by going to http://localhost:8080

If you already have an activator you can either run this collection from the source or import the manifest.

To run from source clone this project and set the activator's kgrid.shelf.cdostore.url property to point to the collection directory. Note that the js-bundled object requires node and you must run npm run build inside the object's directory to build the source code into a bundled artifact that can be activated.

To use the manifest setting the kgrid.shelf.manifest property in the activator to point to a released manifest.

# Package

You can use the kgrid cli to package the collection of knowledge objects by going into the /collection directory and running

kgrid package-all

This will add a checksum to the deployment spec of each object, which the remote runtimes will optionally use to help with caching in remote environments.

Last Updated: 4/6/2021, 4:01:29 PM