Introducing the API

The JavaScript RBroker Framework is the simplest way to integrate DeployR-enabled analytics Web services into your JavaScript applications. It supports both the browser and Node.js environments.

The RBroker Framework defines three simple building blocks:

• RBroker: an RTask execution engine
• RTask: an executable representing any analytics Web service
• RTaskResult: a collection of result data for an instance of RTask

These building blocks are described in further detail in the RBroker Framework Tutorial.

Download and Install

1. Download the DeployR JavaScript RBroker library and begin using it in your application to communicate with DeployR.

2. Unzip the compressed folder. You will see the following structure:

rbroker/
├── examples/
├── gulp/
├── lib/  
├── browser/
│     ├── rbroker.js
│     └── rbroker.min.js
├── rbroker.js
├── gulpfile.js
├── package.json
├── LICENSE.md
└── README.md

The base rbroker.js file contains the source code for the DeployR JavaScript RBroker library. The browser/ folder includes the precompiled browser only version of the JavaScript RBroker. The examples/ folder includes both browser and Node.js samples. Beyond that, any other included file provides support for packages, license information, and development.

3. Install the JavaScript RBroker library using the instructions for your particular environment:

   • Browser
   • Node.js

   <!-- Latest compiled raw JavaScript variation -->
   <script src="./browser/rbroker.js"></script>
   
   Or
   
   <!-- Latest compiled minified JavaScript variation -->
   <script src="./browser/rbroker.min.js"></script>

   Download and install Node.js, which includes npm. npm, which stands for node packaged modules, is a way to manage development dependencies through Node.js.

   From the command line:

   1. Navigate to the root /rbroker/ directory.

   2. Run npm install --production. npm will look at the package.json file and automatically install the necessary local runtime dependencies listed there.

   3. Include the JavaScript Client Library for DeployR deployr dependency by first installing it using the directions outlined here.

   4. Once installed copy the entire /deployr directory into ./rbroker/node_modules. This step is needed because the JavaScript Client Library for DeployR is not yet registered as a public npm package. This is comming soon.

   5. Similar to the JavaScript Client Library for DeployR, the JavaScript RBroker library is not yet registered as a published npm package either. After running npm install --production in step 2, you will need to manually copy the entire /rbroker/ directory into the node_modules directory of the Node.js project that will be using it.

   6. require the directory in your code:

      var rbroker = require('rbroker');

Global Object rbroker

<script src="./browser/rbroker.js"></script>

// -- or --

<script src="./browser/rbroker.min.js"></script>

<script>window.rbroker</script>

#!/bin/env node
var rbroker = require('rbroker');

discreteTaskBroker (config) static

Create an instance of an DiscreteTaskBroker to manage the execution of a DiscreteTask.

Parameters:

• [config] Object Configuration options for a Discrete Task RBroker

  • deployrEndpoint Object Specifies the HTTP URL endpoint for a DeployR Server instance. For example: http://dserver:dport

  • maxConcurrentTaskLimit Number Specifies the task execution concurrency levels requested for an instance of an RBroker.

    Specifying a value of 1 will result in serial execution for all tasks submitted to the RBroker. Specifying a value greater than 1 will result in concurrent execution for tasks submitted to the RBroker. In all cases, up to maxConcurrentTaskLimit RTask will execute concurrently. Regardless of what task execution concurrency level you use the execution of tasks will always proceed in a FIFO order.

    Regardless of the concurrency levels requested when creating an instance of RBroker, a combination of DeployR Server Policies and available DeployR Grid resources determine the actual task throughput that will be achieved on the DeployR server.

    Where an instance of an RBroker has been configured for concurrency levels in excess of those supported by your DeployR Server Policies or DeployR Grid resources, some tasks when executed will likely result in RGridException. Such tasks can be resubmitted to the RBroker for execution at a later date. If RGridException are seen frequently we recommend adjusting the appropriate DeployR Server Policies and/or increasing the resources allocated to the DeployR Grid.

  • credentials Object
    • username - username
    • password - plain-text password

Returns: DiscreteTaskBroker

A new instance of an DiscreteTaskBroker.

pooledTaskBroker (config) static

Create an instance of an PooledTaskBroker to manage the execution of a PooledTask.

Parameters:

• [config] Object Configuration options for a Pooled Task RBroker

  • deployrEndpoint Object Specifies the HTTP URL endpoint for a DeployR Server instance. For example: http://dserver:dport

  • maxConcurrentTaskLimit Number Specifies the task execution concurrency levels requested for an instance of an RBroker.

    Specifying a value of 1 will result in serial execution for all tasks submitted to the RBroker. Specifying a value greater than 1 will result in concurrent execution for tasks submitted to the RBroker. In all cases, up to maxConcurrentTaskLimit RTask will execute concurrently. Regardless of what task execution concurrency level you use the execution of tasks will always proceed in a FIFO order.

    Regardless of the concurrency levels requested when creating an instance of RBroker, a combination of DeployR Server Policies and available DeployR Grid resources determine the actual task throughput that will be achieved on the DeployR server.

    Where an instance of an RBroker has been configured for concurrency levels in excess of those supported by your DeployR Server Policies or DeployR Grid resources, some tasks when executed will likely result in RGridException. Such tasks can be resubmitted to the RBroker for execution at a later date. If RGridException are seen frequently we recommend adjusting the appropriate DeployR Server Policies and/or increasing the resources allocated to the DeployR Grid.

  • credentials Object
    • username username
    • password - text password

  • pool Object

    Preload options:

    • author Comma-separated list of authors, one author per filename.
    • directory - Comma-separated list of directories, one directory per filename.
    • filename - Comma-separated list of repository filenames.
    • version - optional Comma-separated list of versions, one version per filename.

Returns: PooledTaskBroker

A new instance of an PooledTaskBroker.

backgroundTaskBroker (config) static

Create an instance of an BackgroundTaskBroker to manage the execution of a BackgroundTask.

Parameters:

• [config] Object Configuration options for a Background Task RBroker

  • deployrEndpoint Object Specifies the HTTP URL endpoint for a DeployR Server instance. For example: http://dserver:dport

  • maxConcurrentTaskLimit Number Specifies the task execution concurrency levels requested for an instance of an RBroker.

    Specifying a value of 1 will result in serial execution for all tasks submitted to the RBroker. Specifying a value greater than 1 will result in concurrent execution for tasks submitted to the RBroker. In all cases, up to maxConcurrentTaskLimit RTask will execute concurrently. Regardless of what task execution concurrency level you use the execution of tasks will always proceed in a FIFO order.

    Regardless of the concurrency levels requested when creating an instance of RBroker, a combination of DeployR Server Policies and available DeployR Grid resources determine the actual task throughput that will be achieved on the DeployR server.

    Where an instance of an RBroker has been configured for concurrency levels in excess of those supported by your DeployR Server Policies or DeployR Grid resources, some tasks when executed will likely result in RGridException. Such tasks can be resubmitted to the RBroker for execution at a later date. If RGridException are seen frequently we recommend adjusting the appropriate DeployR Server Policies and/or increasing the resources allocated to the DeployR Grid.

  • credentials Object
    • username - username
    • password - plain-text password

Returns: BackgroundTaskBroker

A new instance of a BackgroundTaskBroker.

discreteTask (params) static

Create an instance of a DiscreteTask for an analytics Web service based on either:

1. Repository-managed R script

   var rtask = rbroker.discreteTask({ 
    filename: 'regression',
    directory: 'demo',
    author: 'george',
    version: version
    // Additional Discrete Task Options...
   });

2. URL-addressable R script

   var rtask = rbroker.discreteTask( {    
    externalsource: regressionURL
    // Additional Discrete Task Options...
   });

Parameters:

• [params] Object The parameter details for either:

  1. Repository-managed R script

     • filename – repository-managed script filename
     • directory - optional repository-managed directory for scripts, defaults to root
     • author – optional the authors
     • version – optional the version
     • Additional Discrete Task Options:
       • Pre-Execution Parameters
       • On-Execution Parameters
       • Post-Execution Parameters

  2. URL-addressable R script

     • externalsource - URL or file paths to external scripts
     • Additional Discrete Task Options:
       • Pre-Execution Parameters
       • On-Execution Parameters
       • Post-Execution Parameters

Returns: DiscreteTask

A new instance of an DiscreteTask.

pooledTask (config) static

Create an instance of a PooledTask for an analytics Web service based on either:

1. Repository-managed R script

   var rtask = rbroker.pooledTask({ 
    filename: 'regression',
    directory: 'demo',
    author: 'george',
    version: version
    // Additional Pooled Task Options...
   });

2. Arbitrary block of R code

   var rtask = rbroker.pooledTask( {    
    code: codeBlock
    // Additional Pooled Task Options...
   });

3. URL-addressable R script

   var rtask = rbroker.pooledTask({ 
     externalsource: regressionURL
     // Additional Pooled Task Options...
   });

Parameters:

• [params] Object The parameter details for either:

  1. Repository-managed R script

     • filename – repository-managed script filename
     • directory - optional repository-managed directory for the script, defaults to root
     • author – the author
     • version – optional the filename version
     • Additional Pooled Task Options:
       • Pre-Execution Parameters
       • On-Execution Parameters
       • Post-Execution Parameters

  2. Arbitrary block of R code

     • code - indicates the code that has been executed
     • Additional PooledTask Options:
       • Pre-Execution Parameters
       • On-Execution Parameters
       • Post-Execution Parameters

  3. URL-addressable R script

     • externalsource - URL or file paths to external scripts
     • Additional Pooled Task Options:
       • Pre-Execution Parameters
       • On-Execution Parameters
       • Post-Execution Parameters

Returns: PooledTask

A new instance of a PooledTask.

backgroundTask (config) static

Create an instance of a BackgroundTask for an analytics Web service based on either:

1. Repository-managed R script

   var rTask = rbroker.backgroundTask({
     name: 'Sample Task',
     descr: 'Sample description',
     rscriptname: 'regression',
     rscriptdirectory: 'demo',
     rscriptauthor: 'george',
     rscriptversion: version
     // Additional Background Task Options...
   });

2. Arbitrary block of R code

   var rTask = rbroker.backgroundTask({
     name: 'Sample Task',
     descr: 'Sample description',
     code: codeBlock
     // Additional Background Task Options...
   });

3. URL-addressable R script

   var rTask = rbroker.backgroundTask({
     name: 'Sample Task',
     descr: 'Sample description',
     externalsource: regressionURL
     // Additional Background Task Options...
   });

Parameters:

• [params] Object The parameter details for either:

  1. Repository-managed R script
     • name – job name
     • descr – optional job description
     • rscriptname – repository-managed script filename to execute on job
     • rscriptdirectory - optional repository-managed directory for scripts, defaults to root
     • rscriptauthor – optional the author
     • rscriptversion – optional the version
     • Additional Background Task Options:
       • Pre-Execution Parameters
       • On-Execution Parameters
       • Post-Execution Parameters
  2. Arbitrary block of R code
     • name – job name
     • descr – optional job description
     • code – optional R code to execute on job
     • Additional Background Task Options:
       • Pre-Execution Parameters
       • On-Execution Parameters
       • Post-Execution Parameters
  3. URL-addressable R script
     • name – job name
     • descr – optional job description
     • externalsource – optional URL or file
     • Additional Background Task Options:
       • Pre-Execution Parameters
       • On-Execution Parameters
       • Post-Execution Parameters

Returns: BackgroundTask

A new instance of a BackgroundTask.

RBroker

complete (λ) chainable

A success listener for all tasks submitted on behalf of this RBroker.

Parameters:

• λ Function The callback function. Supplies two argument:

  • task - The RTask associated with this submission.
  • result - The RTask result associated with this submission.

Returns: RBroker

The refrence to this RBroker used for chaining.

error (λ) chainable

A failure listener for all tasks submitted on behalf of this RBroker.

Parameters:

• λ Function The callback function. Supplies two argument:

  • task - The RTask associated with this submission.
  • err - The error associated with this submission.

Returns: RBroker

The refrence to this RBroker used for chaining.

ensure (λ) chainable

A convenience for always returning a result regardless if it is an error or a success for all tasks submitted on behalf of this RBroker.

Parameters:

• λ Function The callback function.

Returns: RBroker

The refrence to this RBroker used for chaining.

progress (λ) chainable

Runtime stats.

Parameters:

• λ Function The callback function.

Returns: RBroker

The refrence to this RBroker used for chaining.

idel (λ) chainable

A notification listener indicating that this Rbroker is still active and there are currently no RTasks running or in the wait queue.

Parameters:

• λ Function The callback function.

Returns: RBroker

The refrence to this RBroker used for chaining.

submit (rtask, priority) undefined

Submit an RTask for execution under the control of RBroker. If priority is indicated, priority tasks are automatically moved to the front of the queue, ahead of all standard tasks that are already pending execution by the broker.

Parameters:

• task RTask The RTask associated with this submission.
• priority Boolean optional Mark this task as having priority.

Returns: RTaskToken

The handle to an RTask live on an RBroker.

shutdown () promise

Release all client-side and server-side resources maintained by or on behalf of an instance of RBroker.

aBroker.shutdown()
   .then(function() {
      // success
   }, function(err) {
      // error
   });

Returns: Promise

A promise wrapping the resolution of either "resolve" or "reject" callback.

status () undefined

Returns status indicating current RTask activity on RBroker.

This call can be used to determine if an RBroker instance is idle which can be particularly useful ahead of calls to shutdown().

Returns: Object

Response objec properties:

• pending - Queued tasks waiting to run.
• executing - Currently running tasks.
• idle - Convenience for an application if individual pending and executing task counts are not relevant in shutdown() decisions.

Object literal containing RBroker status indicating the number of currently queued and executing RTask.

flush () undefined

Flushes all pending RTask from queues maintained by RBroker. Flushing RTask queues ensures that queued tasks will not be executed by RBroker.

Returns: Object

Response objec properties:

• pending - Queued tasks waiting to run.
• executing - Currently running tasks.
• idle - Convenience for an application if individual pending and executing task counts are not relevant in shutdown() decisions.

Object literal containing RBroker status indicating the number of currently queued and executing RTask.

refresh (config) undefined

Refresh the configuration for RBroker.

Note, support for refresh is only available on the PooledTaskBroker runtime. In addition, only pool creation options are processed on this call. All other RBroker_ configuration options are ignored.

A refresh causes all workspace objects and directory files in the underlying R sessions within the pool to be cleared before new workspace objects and/or directory files are loaded per the new config options.

Only an idle RBroker instance can be refreshed.

Parameters:

• [config] Object Startup options for a Pooled Task RBroker.

maxConcurrency () undefined

Returns the task execution concurrency levels enforced for this instance of RBroker.

Returns: Boolean

The task execution concurrency levels enforced for this instance of RBroker.

DiscreteTaskBroker

Extends RBroker

complete (λ) chainable

A success listener for all tasks submitted on behalf of this RBroker.

Parameters:

• λ Function The callback function. Supplies two argument:

  • task - The RTask associated with this submission.
  • result - The RTask result associated with this submission.

Returns: RBroker

The refrence to this RBroker used for chaining.

error (λ) chainable

A failure listener for all tasks submitted on behalf of this RBroker.

Parameters:

• λ Function The callback function. Supplies two argument:

  • task - The RTask associated with this submission.
  • err - The error associated with this submission.

Returns: RBroker

The refrence to this RBroker used for chaining.

ensure (λ) chainable

A convenience for always returning a result regardless if it is an error or a success for all tasks submitted on behalf of this RBroker.

Parameters:

• λ Function The callback function.

Returns: RBroker

The refrence to this RBroker used for chaining.

idel (λ) chainable

A notification listener indicating that this Rbroker is still active and there are currently no RTasks running or in the wait queue.

Parameters:

• λ Function The callback function.

Returns: RBroker

The refrence to this RBroker used for chaining.

submit (rtask, priority) undefined

Submit an RTask for execution under the control of RBroker. If priority is indicated, priority tasks are automatically moved to the front of the queue, ahead of all standard tasks that are already pending execution by the broker.

Parameters:

• task RTask The RTask associated with this submission.
• priority Boolean optional Mark this task as having priority.

Returns: RTaskToken

The handle to an RTask live on an RBroker.

shutdown () promise

Release all client-side and server-side resources maintained by or on behalf of an instance of RBroker.

aBroker.shutdown()
   .then(function() {
      // success
   }, function(err) {
      // error
   });

Returns: Promise

A promise wrapping the resolution of either "resolve" or "reject" callback.

status () undefined

Returns status indicating current RTask activity on RBroker.

This call can be used to determine if an RBroker instance is idle which can be particularly useful ahead of calls to shutdown().

Returns: Object

Response objec properties:

• pending - Queued tasks waiting to run.
• executing - Currently running tasks.
• idle - Convenience for an application if individual pending and executing task counts are not relevant in shutdown() decisions.

Object literal containing RBroker status indicating the number of currently queued and executing RTask.

flush () undefined

Flushes all pending RTask from queues maintained by RBroker. Flushing RTask queues ensures that queued tasks will not be executed by RBroker.

Returns: Object

Response objec properties:

• pending - Queued tasks waiting to run.
• executing - Currently running tasks.
• idle - Convenience for an application if individual pending and executing task counts are not relevant in shutdown() decisions.

Object literal containing RBroker status indicating the number of currently queued and executing RTask.

maxConcurrency () undefined

Returns the task execution concurrency levels enforced for this instance of RBroker.

Returns: Boolean

The task execution concurrency levels enforced for this instance of RBroker.

PooledTaskBroker

Extends RBroker

complete (λ) chainable

A success listener for all tasks submitted on behalf of this RBroker.

Parameters:

• λ Function The callback function. Supplies two argument:

  • task - The RTask associated with this submission.
  • result - The RTask result associated with this submission.

Returns: RBroker

The refrence to this RBroker used for chaining.

error (λ) chainable

A failure listener for all tasks submitted on behalf of this RBroker.

Parameters:

• λ Function The callback function. Supplies two argument:

  • task - The RTask associated with this submission.
  • err - The error associated with this submission.

Returns: RBroker

The refrence to this RBroker used for chaining.

ensure (λ) chainable

A convenience for always returning a result regardless if it is an error or a success for all tasks submitted on behalf of this RBroker.

Parameters:

• λ Function The callback function.

Returns: RBroker

The refrence to this RBroker used for chaining.

idel (λ) chainable

A notification listener indicating that this Rbroker is still active and there are currently no RTasks running or in the wait queue.

Parameters:

• λ Function The callback function.

Returns: RBroker

The refrence to this RBroker used for chaining.

submit (rtask, priority) undefined

Submit an RTask for execution under the control of RBroker. If priority is indicated, priority tasks are automatically moved to the front of the queue, ahead of all standard tasks that are already pending execution by the broker.

Parameters:

• task RTask The RTask associated with this submission.
• priority Boolean optional Mark this task as having priority.

Returns: RTaskToken

The handle to an RTask live on an RBroker.

shutdown () promise

Release all client-side and server-side resources maintained by or on behalf of an instance of RBroker.

aBroker.shutdown()
   .then(function() {
      // success
   }, function(err) {
      // error
   });

Returns: Promise

A promise wrapping the resolution of either "resolve" or "reject" callback.

status () undefined

Returns status indicating current RTask activity on RBroker.

This call can be used to determine if an RBroker instance is idle which can be particularly useful ahead of calls to shutdown().

Returns: Object

Response objec properties:

• pending - Queued tasks waiting to run.
• executing - Currently running tasks.
• idle - Convenience for an application if individual pending and executing task counts are not relevant in shutdown() decisions.

Object literal containing RBroker status indicating the number of currently queued and executing RTask.

flush () undefined

Flushes all pending RTask from queues maintained by RBroker. Flushing RTask queues ensures that queued tasks will not be executed by RBroker.

Returns: Object

Response objec properties:

• pending - Queued tasks waiting to run.
• executing - Currently running tasks.
• idle - Convenience for an application if individual pending and executing task counts are not relevant in shutdown() decisions.

Object literal containing RBroker status indicating the number of currently queued and executing RTask.

maxConcurrency () undefined

Returns the task execution concurrency levels enforced for this instance of RBroker.

Returns: Boolean

The task execution concurrency levels enforced for this instance of RBroker.

BackgroundTaskBroker

Extends RBroker

complete (λ) chainable

A success listener for all tasks submitted on behalf of this RBroker.

Parameters:

• λ Function The callback function. Supplies two argument:

  • task - The RTask associated with this submission.
  • result - The RTask result associated with this submission.

Returns: RBroker

The refrence to this RBroker used for chaining.

error (λ) chainable

A failure listener for all tasks submitted on behalf of this RBroker.

Parameters:

• λ Function The callback function. Supplies two argument:

  • task - The RTask associated with this submission.
  • err - The error associated with this submission.

Returns: RBroker

The refrence to this RBroker used for chaining.

ensure (λ) chainable

A convenience for always returning a result regardless if it is an error or a success for all tasks submitted on behalf of this RBroker.

Parameters:

• λ Function The callback function.

Returns: RBroker

The refrence to this RBroker used for chaining.

idel (λ) chainable

A notification listener indicating that this Rbroker is still active and there are currently no RTasks running or in the wait queue.

Parameters:

• λ Function The callback function.

Returns: RBroker

The refrence to this RBroker used for chaining.

submit (rtask, priority) undefined

Submit an RTask for execution under the control of RBroker. If priority is indicated, priority tasks are automatically moved to the front of the queue, ahead of all standard tasks that are already pending execution by the broker.

Parameters:

• task RTask The RTask associated with this submission.
• priority Boolean optional Mark this task as having priority.

Returns: RTaskToken

The handle to an RTask live on an RBroker.

shutdown () promise

Release all client-side and server-side resources maintained by or on behalf of an instance of RBroker.

aBroker.shutdown()
   .then(function() {
      // success
   }, function(err) {
      // error
   });

Returns: Promise

A promise wrapping the resolution of either "resolve" or "reject" callback.

status () undefined

Returns status indicating current RTask activity on RBroker.

This call can be used to determine if an RBroker instance is idle which can be particularly useful ahead of calls to shutdown().

Returns: Object

Response objec properties:

• pending - Queued tasks waiting to run.
• executing - Currently running tasks.
• idle - Convenience for an application if individual pending and executing task counts are not relevant in shutdown() decisions.

Object literal containing RBroker status indicating the number of currently queued and executing RTask.

flush () undefined

Flushes all pending RTask from queues maintained by RBroker. Flushing RTask queues ensures that queued tasks will not be executed by RBroker.

Returns: Object

Response objec properties:

• pending - Queued tasks waiting to run.
• executing - Currently running tasks.
• idle - Convenience for an application if individual pending and executing task counts are not relevant in shutdown() decisions.

Object literal containing RBroker status indicating the number of currently queued and executing RTask.

maxConcurrency () undefined

Returns the task execution concurrency levels enforced for this instance of RBroker.

Returns: Boolean

The task execution concurrency levels enforced for this instance of RBroker.

DiscreteTask

No public methods supported.

PooledTask

No public methods supported.

BackgroundTask

No public methods supported.

RTaskToken

complete (λ) chainable

A success listener for a single task submission.

Parameters:

• λ Function The callback function. Supplies one argument:

  • result - The RTask result associated with this submission.

Returns: RTaskToken

The refrence to this token on a task submission for chaining.

error (λ) chainable

A failure listener for a single task submission.

Parameters:

• λ Function The callback function. Supplies one argument:

  • err - The error associated with this submission.

Returns: RTaskToken

The refrence to this token on a task submission for chaining.

ensure (λ) chainable

A convenience for always returning a result regardless if it is an error or a success for a single task submission.

Parameters:

• λ Function The callback function.

Returns: RTaskToken

The refrence to this token on a task submission for chaining.

cancel (interrupt) undefined

Terminates this the running task.

Parameters:

• interrupt Boolean Permission to interrupt task if it is running.

isCancelled () undefined

Defines if this task is currently cancelled.

Returns: Boolean

If this task is currently cancelled.

RTaskResult

Properties:

idString

Task DeployR identifier. Maps to a project execution or job identifier.

typeRTaskType

Task type

successBoolean

Task success indicator.

timeOnCodeNumber

Task time spent executing R code on server.

timeOnServerNumber

Task time spent being processed on server.

timeOnCallNumber

Task time spent on call to server.

failureString

Task failure indicator.

interruptedBoolean

Task interrupted indicator.

generatedConsoleString

Task R session generated console output.

generatedPlotsArray

Task R session graphics device generated plots.

generatedFilesArray

Task R session working directory generated files.

generatedObjectsArray

Task R session workspace generated objects.

storedFilesArray

Task generated files stored to DeployR repository.