Class: BusyContext

Oracle® JavaScript Extension Toolkit (JET)
3.2.0

E87541-01

QuickNav

Fields

oj. BusyContext

Version:
  • 3.2.0
Since:
  • 2.1.0
Framework service for querying the busy state of components on the page.

Constructor

new BusyContext(hostNode)

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 Busy Context API will block until all the busy states have resolved or a timeout period has elapsed. There are four primary wait scenarios:
  1. Components that implement new animation effects.
  2. Components that must fetch data from a REST endpoint.
  3. General wait conditions that are not specific to the Jet framework. The customer might choose to register some blocking condition associated with application domain logic such as REST endpoints.
  4. 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 block until a popup has finished open or close animation before initiating the next task 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 = $("#mycontext");
        var busyContext = oj.Context.getContext(node[0]).getBusyContext();
        
The BusyContext API utilizes oj.Logger.LEVEL_LOG to log detail busy state activity.

 oj.Logger.option("level", oj.Logger.LEVEL_LOG);
This constructor should never be invoked by the application code directly.
Parameters:
Name Type Argument Description
hostNode Element <optional>
DOM element associated with this busy context
Source:

Fields

applicationBoostrapComplete

Since:
  • 2.1.0
Deprecated:
Source:

Methods

<static> setDefaultTimeout(timeout)

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
Since:
  • 3.1.0
Source:
See:

addBusyState(options) → {Function}

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 {description: ?} object that describes the busy state being registered.
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
Source:
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

applicationBootstrapComplete() → {void}

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 a inline script from the document header section indicating the oj.BusyContext#whenReady should oj.BusyContext#addBusyState until the application determines its bootstrap sequence has completed.

Inline Script Example:

<head>
  <script type="text/javascript">
    // 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;
  </script>
...
...
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
Source:
Returns:
Type
void

clear()

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

dump(message)

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

 oj.Logger.option("level", oj.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
Source:

getBusyStates() → {Array.<{id:String, description:String}>}

Returns an array of states representing the active busy states managed by the instance.
Since:
  • 3.1.0
Source:
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.

"next-tick" is not waiting for the microtask queue to be exhausted. However, this may change in future releases.
Since:
  • 2.1.0
Source:
See:
Returns:
true if the context is not busy
Type
boolean

toString() → {string}

Since:
  • 3.1.0
Source:
Returns:
returns the value of the object as a string
Type
string

whenReady(timeout) → {Promise}

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 not waiting for the microtask queue to be exhausted. However, this may change in future releases.
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
Source:
See:
Returns:
Type
Promise

Non-public Methods

<protected> Init(hostNode)

Parameters:
Name Type Argument Description
hostNode Element <optional>
DOM element associated with this busy context
Source: