BBjCalendarWidget

Class BBjJavaScriptExecutor

java.lang.Object

BBjCalendarWidget.BBjJavaScriptExecutor

public class BBjJavaScriptExecutor
extends Object

The BBjJavaScriptExecutor is a BBj Custom Class that manages JavaScript code execution in a BBjHtmlView control, providing the ability to queue and debounce JavaScript execution.

Definition of terms:

- Debouncing: instead of immediately firing off several events in quick succession, if you choose to debounce the scripts then they will be batched together to improve performance. The batch size depends on how many scripts are enqueued, the amount of time that passes between their enqueing, and the defined Rate. Do NOT debounce scripts from which you are expecting a return value, as the return value will be associated with the entire batch, not an individual line of JavaScript. If you do need a valid return value, use the executeImmediately() methods.

- Rate: the number of milliseconds that must expire without enqueing any more scripts before the executor flushes the enqueued scripts on the client. The default Rate is 200ms, although you can override this by using the constructor that specifies a Rate time.

- Execute Key: The script's unique id. If you attempt to queue two scripts with the same key then the second script will overwrite the first and the first script will not be executed. You do not have to specify a key value with several of the execute() methods. The main point of the key is that if you think that you may be executing the exact same script several times, then reusing the same key is a way to have only the last instance of the script be executed. For example, if you execute a redraw() JavaScript function whenever the user resizes a window, then using the script as the key ensures that it won't get called dozens of times sequentially as the user is resizing the window.

- Execute Priority: The script's priority in the queue, starting from 0 and incrementing by ones. If you specify a priority, it will be used as the script's index in the queue (a ListOrderedMap). This MUST start at 0 and increment, or you will get an indexing error on the queue. If you use an execute() method that does not specify a priority, then the scripts will be added sequentually to the queue and executed in the order in which they were added.

Although this class offers several execute() methods for the most flexibility, the most common usage will be the execute(BBjString script!, BBjNumber debounced!) signature, as it reuses the provided script for the key, you can control debouncing, and sequential execution is desired (without having to keep track of priority levels).

If scripts are queued for execution, they will eventually be executed in the BBjHtmlView control either when the widget code explicitly calls the executor's flush() method, or after the Rate timer has expired, which is 200 milliseconds by default. The executor will continue to flush the queue whenever it is needed.

Note that every time you queue a new script it will reset the Rate timer. That means that if you are queueing up scripts for execution in quick succession, then they will all be executed in a batch after the last script is queued. If you are queueing up scripts occasionally, meaning longer than the Rate timer, then each script will end up being executed before the next one has been queued.

Note: The executor handles JSNI automatically so you don't have to check for BUI and adjust the window and document JavaScript objects.

Example use cases:

rem Create a new executor object specifying the rate time of 200ms where #this! is an
rem instance of the custom class (assuming the application is object-oriented)
executor! = new BBjJavaScriptExecutor(#this!, 200)

rem Have the executor enqueue then execute the JavaScript stored in the script! variable.
rem The "1" indicates that it should be debounced, or batched.
executor!.execute(script!, 1)

rem Have the executor immediately execute the provided JavaScript and return the result
rem in a BBjString or Object
viewType! = executor!.executeImmediately("window.calendar.view.type;")

Since this class is meant to be used with a BBjWidget, then it will automatically queue up scripts if the BBjWidget's getIsReady() returns false.

Since:

BBj 21.00

Field Summary

Fields

Modifier and Type	Field and Description
BBjNumber	Debug! A boolean that determines whether the plug-in should run in debug mode - when true it will use unminified Javascript and display the debugger in GUI and log messages to the console.
BBjHtmlView	HTMLView! The BBjHtmlView control that will execute the JavaScript.
BBjNumber	Rate! The number of milliseconds before the executor tries to flush the enqueued scripts on the client.
BBjNumber	SuppressBuiDebouncing! A BBjNumber acting as a boolean that determines whether the executor should override script debouncing in BUI.
BBjNumber	SuppressGuiDebouncing! A BBjNumber acting as a boolean that determines whether the executor should override script debouncing in GUI.

Constructor Summary

Constructors

Constructor and Description
BBjJavaScriptExecutor(BBjWidget widget!) A constructor that creates a new BBjJavaScriptExecutor object to be used with a BBj plug-in that extends the BBjWidget plug-in class, specifying the BBjWidget and taking the default flush rate of 200ms.
BBjJavaScriptExecutor(BBjWidget widget!, BBjNumber rate!) A constructor that creates a new BBjJavaScriptExecutor object to be used with a BBj plug-in that extends the BBjWidget plug-in class, specifying the BBjWidget and the flush rate in milliseconds.

Method Summary

Modifier and Type	Method and Description
Object	execute(BBjString script!) Executes and debounces the provided JavaScript code on the client using the script itself as a key and without a priority.
Object	execute(BBjString script!, BBjNumber debounced!) Executes the provided JavaScript code on the client using the script itself as a key and without priority, which is the typical use case.
Object	execute(BBjString script!, BBjNumber debounced!, BBjNumber priority!) Executes the provided JavaScript code on the client and uses the script itself as a key with the specified priority.
Object	execute(BBjString key!, BBjString script!) Executes and debounces the provided JavaScript code on the client without a priority.
Object	execute(BBjString key!, BBjString script!, BBjNumber debounced!) Executes the provided JavaScript code on the client without a priority, which is a more typical use case.
Object	execute(BBjString key!, BBjString script!, BBjNumber debounced!, BBjNumber priority!) Executes the provided JavaScript code on the client, specifying all available parameters.
Object	executeImmediately(BBjString script!) Executes the provided JavaScript directly in the BBjHtmlView control without debouncing so that it can return a valid return object as a generic Object.
BBjJavaScriptExecutor	flush() Flushes the executor's queue by iterating over the enqueued scripts, combining them into a single batch, executing them on the BBjHtmlView control.
void	onFlush(BBjTimerEvent event!) An internal method serving as a BBjTimerEvent callback which will be invoked when the executor timer's count down reaches 0 to flush the enqueued scripts.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

Rate!

public BBjNumber Rate!

The number of milliseconds before the executor tries to flush the enqueued scripts on the client.

SuppressBuiDebouncing!

public BBjNumber SuppressBuiDebouncing!

A BBjNumber acting as a boolean that determines whether the executor should override script debouncing in BUI. Defaults to "0", meaning scripts will be batched instead of executed immediately. Setting this to "0" may help to increase the communication performance between BBj and the JavaScript library/object inside the BBjHtmlView control in BUI.

SuppressGuiDebouncing!

public BBjNumber SuppressGuiDebouncing!

A BBjNumber acting as a boolean that determines whether the executor should override script debouncing in GUI. Defaults to "0", meaning scripts will be batched instead of executed immediately. Setting this to "0" will help to increase the communication performance between BBj and the JavaScript library/object inside the BBjHtmlView control in GUI.

HTMLView!

public BBjHtmlView HTMLView!

The BBjHtmlView control that will execute the JavaScript.

Debug!

public BBjNumber Debug!

A boolean that determines whether the plug-in should run in debug mode - when true it will use unminified Javascript and display the debugger in GUI and log messages to the console.

Constructor Detail

BBjJavaScriptExecutor

public BBjJavaScriptExecutor(BBjWidget widget!)

A constructor that creates a new BBjJavaScriptExecutor object to be used with a BBj plug-in that extends the BBjWidget plug-in class, specifying the BBjWidget and taking the default flush rate of 200ms.

Parameters:

BBjWidget - widget! The BBjWidget instance.

BBjJavaScriptExecutor

public BBjJavaScriptExecutor(BBjWidget widget!,
BBjNumber rate!)

A constructor that creates a new BBjJavaScriptExecutor object to be used with a BBj plug-in that extends the BBjWidget plug-in class, specifying the BBjWidget and the flush rate in milliseconds.

Parameters:

BBjWidget - widget! The BBjWidget instance.

BBjNumber - rate! The number of milliseconds that should elapse before the executor flushes the JavaScript code on the client.

Method Detail

execute

public Object execute(BBjString key!,
BBjString script!,
BBjNumber debounced!,
BBjNumber priority!)

Executes the provided JavaScript code on the client, specifying all available parameters.

Parameters:

BBjString - key! The script's unique id. If you attempt to queue two scripts with the same key then the second script will overwrite the first, and the first script will not be executed.

BBjString - script! The JavaScript code to execute.

BBjNumber - debounced! A BBjNumber acting as a boolean that determines whether the executor will debounce the script (1) or execute it immediately (0).

BBjNumber - priority! The script's priority value that serves as its index in the queue. This MUST start at 0 and increment, or you'll get an indexing error on the queue.

Returns:

Object The result of the JavaScript code execution if the script returns a value.

execute

public Object execute(BBjString script!,
BBjNumber debounced!,
BBjNumber priority!)

Executes the provided JavaScript code on the client and uses the script itself as a key with the specified priority.

Parameters:

BBjString - script! The JavaScript code to execute.

BBjNumber - debounced! A BBjNumber acting as a boolean that determines whether the executor will debounce the script (1) or execute it immediately (0).

BBjNumber - priority! The script's priority value that serves as its index in the queue. This MUST start at 0 and increment, or you'll get an indexing error on the queue.

Returns:

Object The result of the JavaScript code execution if the script returns a value.

execute

public Object execute(BBjString key!,
BBjString script!,
BBjNumber debounced!)

Executes the provided JavaScript code on the client without a priority, which is a more typical use case.

Parameters:

BBjString - key! The script's unique id. If you attempt to queue two scripts with the same key then the second script will overwrite the first, and the first script will not be executed.

BBjString - script! The JavaScript code to execute.

BBjNumber - debounced! A BBjNumber acting as a boolean that determines whether the executor will debounce the script (1) or execute it immediately (0).

Returns:

Object The result of the JavaScript code execution if the script returns a value.

execute

public Object execute(BBjString script!,
BBjNumber debounced!)

Executes the provided JavaScript code on the client using the script itself as a key and without priority, which is the typical use case.

Parameters:

BBjString - script! The JavaScript code to execute.

BBjNumber - debounced! A BBjNumber acting as a boolean that determines whether the executor will debounce the script (1) or execute it immediately (0).

Returns:

Object The result of the JavaScript code execution if the script returns a value.

execute

public Object execute(BBjString key!,
BBjString script!)

Executes and debounces the provided JavaScript code on the client without a priority.

Parameters:

BBjString - key! The script's unique id. If you attempt to queue two scripts with the same key then the second script will overwrite the first, and the first script will not be executed.

BBjString - script! The JavaScript code to execute.

Returns:

Object The result of the JavaScript code execution if the script returns a value.

execute

public Object execute(BBjString script!)

Executes and debounces the provided JavaScript code on the client using the script itself as a key and without a priority.

Parameters:

BBjString - script! The JavaScript code to execute.

Returns:

Object The result of the JavaScript code execution if the script returns a value.

executeImmediately

public Object executeImmediately(BBjString script!)

Executes the provided JavaScript directly in the BBjHtmlView control without debouncing so that it can return a valid return object as a generic Object.

Parameters:

BBjString - script$ The JavaScript code to execute.

Returns:

Object The result of the JavaScript code execution if the script returns a value.

flush

public BBjJavaScriptExecutor flush()

Flushes the executor's queue by iterating over the enqueued scripts, combining them into a single batch, executing them on the BBjHtmlView control. The widget should call this method once when it is ready to begin the execution process. This is normally this done after the 'ON_PAGE_LOADED' event has fired. If this method isn't explicitly called by the widget, then it will be called automatically after the Rate timer has expired, which is 200 milliseconds by default. The executor will continue to flush the queue whenever it is needed.

Returns:

BBjJavaScriptExecutor the executor instance.

onFlush

public void onFlush(BBjTimerEvent event!)

An internal method serving as a BBjTimerEvent callback which will be invoked when the executor timer's count down reaches 0 to flush the enqueued scripts.

Parameters:

BBjTimerEvent - event!