Class: BusyContext

Oracle® JavaScript Extension Toolkit (JET)
15.1.0
F83698-01

Since:
  • 2.1.0
Module:
  • ojcontext

QuickNav

Methods

Description

Framework service for querying the busy state of components on the page.


Usage

Typescript Import Format
//This class is not exported from module and can not be accessed in runtime.
//However to enable typechecking and ducktyping, you can access it as an interface.
import Context= require("ojs/ojcontext");

//To access this type in your code,
class MyClass implements Context.BusyContext{
//or,
let myVariable: Context.BusyContext;

For additional information visit:


The purpose of the BusyContext API is to accommodate sequential dependencies of asynchronous operations. A common use cases defining the API is for automation testing (qunit and webdriver). Automation test developers can use this API to wait until components finish animation effects or data fetch before trying to interact with components. The BusyContext is not limited to test automation developers usages. It is also needed by page developers for waiting on run-time operation readiness.

The Busy Context API will wait until busy states have resolved or a timeout period has elapsed. There are several primary wait scenarios:
  1. Component creation and page bindings applied.
  2. Components that implement animation effects.
  3. Components that must fetch data from a REST endpoint.
  4. General wait conditions that are not specific to the Jet framework. The customer might choose to register some busy condition associated with application domain logic such as REST endpoints.
  5. Wait until the bootstrap of the page has completed - jet libraries loaded via requireJS.

The first step for waiting on a busy context is to determine what conditions are of interest to wait on. The granularity of a busy context can be scoped for the entirety of the page or for a specific DOM element. Busy contexts have hierarchical dependencies mirroring the document's DOM structure with the root being the page context. Depending on the particular scenario, developers might need to target one of the following busy context scopes:

  • Scoped for the Page - Automation test developers will more commonly choose the page busy context. This context represents the page as a whole. Automation developers commonly need to wait until the page is fully loaded before starting automation. More commonly, automation developers are interesting in testing the functionality of an application having multiple JET components versus just a single component. 
        
    var busyContext = oj.Context.getPageContext().getBusyContext();
  • Scoped for the nearest DOM Element - Application developers sometime need a mechanism to wait until a specific component operation has complete. For example, it might be desirable to wait until a component has been created and bindings applied before setting a property or calling a method on the component. Another scenario, waiting for a popup to finish open or close animation before initiating the next action in their application flow. For this problem space developers would need to obtain a busy context scoped for a DOM node. The "data-oj-context" marker attribute is used to define a busy context for a dom subtree. 
        
    
    <div id="mycontext" data-oj-context>
       ...
       <!-- JET content -->
       ...
    </div>

    var node = document.querySelector("#mycontext");
    var busyContext = oj.Context.getContext(node).getBusyContext();
    busyContext.whenReady().then(function ()
    {
      var component = document.querySelector("#myInput");
      component.value = "foo";
      component.validate().then(function (isValid)
      {
        if (!isValid)
          component.value = "foobar";
      });
    });
The BusyContext API utilizes oj.Logger.LEVEL_LOG to log detail busy state activity. 

 Logger.option("level", Logger.LEVEL_LOG);
This constructor should never be invoked by the application code directly.

Methods

(static) setDefaultTimeout(timeout) : {undefined}

Sets a default for the optional timeout argument of the oj.BusyContext#whenReady for all BusyContext instances. The default value will be implicitly used if a timeout argument is not provided.
Parameters:
Name Type Description
timeout number in milliseconds
Deprecated:
Since Description
6.0.0 Use oj.Context.setBusyContextDefaultTimeout instead.
Since:
  • 6.0.0
See:
Returns:
Type
undefined

addBusyState(options) : {function():void}

Called by components or services performing a task that should be considered in the overall busy state of the page. An example would be animation or fetching data.

Caveats:
  • Busy context dependency relationships are determined at the point the first busy state is added. If the DOM node is re-parented after a busy context was added, the context will maintain dependencies with any parent DOM contexts.
  • The application logic creating busy states is responsible for ensuring these busy states are resolved. Busy states added internally by JET are automatically accounted for. The busy states added by the application logic must manage a reference to the resolve function associated with a busy state and it must be called to release the busy state.
// apply the marker attribute to the element
<div id="context1" data-oj-context ... ></>
...
...
var context1 = document.querySelector("#context1");

// obtain a busy context scoped for the target node
var busyContext1 = oj.Context.getContext(context1).getBusyContext();
// add a busy state to the target context
var options = {"description": "#context1 fetching data"};
var resolve = busyContext1.addBusyState(options);
...
...  // perform asynchronous operation that needs guarded by a busy state
...
// resolve the busy state after the operation completes
resolve();
Parameters:
Name Type Description
options Object object that describes the busy state being registered.
Properties
Name Type Description
description { toString: ()=>string; [propName: string]: any; } | (() => string) | string description: Option additional information of what is registering a busy state. Added to logging and handling rejected status. Can be supplied as a Object or a function. If the type is an object the toString function needs to be implemented.
Since:
  • 2.1.0
Returns:

resolve function called by the registrant when the busy state completes. The resultant function will throw an error if the busy state is no longer registered.

Type
function():void

applicationBootstrapComplete : {undefined}

This function should be invoke by application domain logic to indicate all application libraries are loaded and bootstrap processes complete. The assumed strategy is that the application will set a single global variable "oj_whenReady" from its "main.js" script, indicating that the oj.BusyContext#whenReady should oj.BusyContext#addBusyState until the application determines its bootstrap sequence has completed.

main.js Script Example: 
main.js:

    // The "oj_whenReady" global variable enables a strategy that the busy context whenReady,
    // will implicitly add a busy state, until the application calls applicationBootstrapComplete
    // on the busy state context.
    window["oj_whenReady"] = true;
...
...
Requirejs callback Example: 

require(['knockout', 'jquery', 'app', 'ojs/ojknockout', 'ojs/ojselectcombobox' ...],
  function(ko, $, app)
  {
    // release the application bootstrap busy state
    oj.Context.getPageContext().getBusyContext().applicationBootstrapComplete();
    ...
    ...
  });
Since:
  • 3.2.0
Returns:
Type
undefined

clear : {undefined}

Forces all busy states per context instance to release. Use with discretion - last course of action.
Since:
  • 3.1.0
Returns:
Type
undefined

dump(message) : {undefined}

Logs all active busy states to the oj.Logger at {Logger.LEVEL_INFO}. 

 Logger.option("level", Logger.LEVEL_INFO);
 oj.Context.getPageContext().getBusyContext().dump("before popup open");
Parameters:
Name Type Argument Description
message string <optional>
 optional text used to further denote a debugging point
Since:
  • 3.1.0
Returns:
Type
undefined

getBusyStates : {Array.<{id:string, description:string}>}

Returns an array of states representing the active busy states managed by the instance.
Since:
  • 3.1.0
Returns:

active busy states managed by the context instance

Type
Array.<{id:string, description:string}>

isReady : {boolean}

Describes the busyness of the context. The busyness is evaluated in the "next-tick" of a busy state being resolved, meaning the number of busy states doesn't necessarily equate to readiness. The readiness is in sync with the oj.BusyContext#whenReady resultant promise resolution.

Since:
  • 2.1.0
See:
Returns:

true if the context is not busy

Type
boolean

toString : {string}

Since:
  • 3.1.0
Returns:

returns the value of the object as a string

Type
string

whenReady(timeout) : {Promise.<(boolean|Error)>}

Returns a Promise that will resolve when all registered busy states have completed or a maximum timeout period has elapsed. The promise will be rejected if all the busy states are not resolved within the timeout period. The busyness of the whenReady promsie is evaluated in the next-tick of resolving a busy state.

"next-tick" is at the macrotask level. "whenReady" is waiting for the microtask queue to be exhausted, yielding control flow to the user agent, before resolving busyness.
Parameters:
Name Type Argument Description
timeout number <optional>
 "optional" maximum period in milliseconds the resultant promise will wait. Also see oj.BusyContext.setDefaultTimeout.
Since:
  • 2.1.0
See:
Returns:
Type
Promise.<(boolean|Error)>