/**
 * BBjJavaScriptExecutor.bbj
 * @author ndecker
 *
 * The <code>BBjJavaScriptExecutor</code> is a BBj Custom Class that manages JavaScript code execution in a BBjHtmlView
 * control, providing the ability to queue and debounce JavaScript execution. It is meant to be used with a BBj plug-in
 * that extends the BBjWidget plug-in class. It is based off of the BBjGridExWidget's GxExecutor class by Hyyan Abo Fakher.
 *
 * For the full copyright and license information, please view the LICENSE file distributed with this source code.
 *
 * @since BBj 21.00
*/
package BBjCalendarWidget;
import org.apache.commons.collections4.map.ListOrderedMap;
/**
 * The <code>BBjJavaScriptExecutor</code> is a BBj Custom Class that manages JavaScript code execution in a BBjHtmlView control, providing the ability to queue and debounce JavaScript execution.
 * <p>
 * <h3>Definition of terms:</h3>
 * <p>
 * - <b>Debouncing</b>: 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 <code>executeImmediately()</code> methods.
 * <p>
 * - <b>Rate</b>: 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.
 * <p>
 * - <b>Execute Key</b>: 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.
 * <p>
 * - <b>Execute Priority</b>: 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.
 * <p>
 * Although this class offers several execute() methods for the most flexibility, the most common usage will be the <code>execute(BBjString script!, BBjNumber debounced!)</code> 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).
 * <p>
 * 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.
 * <p>
 * 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.
 * <p>
 * <b>Note</b>: The executor handles JSNI automatically so you don't have to check for BUI and adjust the window and document JavaScript objects.
 * <p>
 * <b>Example use cases:</b>
 * <blockquote><pre><code><div style = 'background:#E1E6EA; border:1px solid #000; border-radius:1em; padding:0 1em;'>
 *
 * <i><span style = 'color:#080;'>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)</span></i>
 * executor! = new BBjJavaScriptExecutor(#this!, 200)
 * <span></span>
 * <i><span style = 'color:#080;'>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.</span></i>
 * executor!.execute(script!, 1)
 * <span></span>
 * <i><span style = 'color:#080;'>rem Have the executor immediately execute the provided JavaScript and return the result
 * rem in a BBjString or Object</span></i>
 * viewType! = executor!.executeImmediately("window.calendar.view.type;")
 * </div></code></pre></blockquote>
 * 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
*/
public class BBjJavaScriptExecutor {
/** The number of milliseconds before the executor tries to flush the enqueued scripts on the client. */

public BBjNumber Rate!;
/**
 * 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.
*/
public BBjNumber SuppressBuiDebouncing!;
/**
 * 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.
*/
public BBjNumber SuppressGuiDebouncing!;
/** The widget instance. */

protected BBjWidget Widget!;
/** The BBjHtmlView control that will execute the JavaScript. */

public BBjHtmlView HTMLView!;
/** 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. */

public BBjNumber Debug!;
/** A BBjNumber acting as a boolean that indicates whether the executor is currently flushing or not. */

protected BBjNumber IsFlushing!;
/** A BBjString that contains the Widget's ID which is only used for debugging. If it's advanced BBjWidget built from JavaScript, it will be a UUID. */

protected BBjString Id!;
/** A map of enqueued scripts to be executed. */

protected ListOrderedMap Queue!;
/**
 * 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.
 *
 * @param BBjWidget widget! The BBjWidget instance.
*/
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 the flush rate in milliseconds.
 *
 * @param BBjWidget widget! The BBjWidget instance.
 * @param BBjNumber rate! The number of milliseconds that should elapse before the executor flushes the JavaScript code on the client.
*/
public BBjJavaScriptExecutor(BBjWidget widget!, BBjNumber rate!) { }
/**
 * Executes the provided JavaScript code on the client, specifying all available parameters.
 *
 * @param 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.
 * @param BBjString script! The JavaScript code to execute.
 * @param BBjNumber debounced! A BBjNumber acting as a boolean that determines whether the executor will debounce the script (1) or execute it immediately (0).
 * @param 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.
 *
 * @return Object The result of the JavaScript code execution if the script returns a value.
*/
public Object execute(BBjString key!, BBjString script!, BBjNumber debounced!, BBjNumber priority!) { }
/**
 * If the script should not be debounced, then this means that the execution might return a value.
 * In this case we check if the widget is ready and if so, then we execute the script directly on
 * the BBjHtmlView control and return the result. Otherwise, we continue to the next step.
 *
 * An example of calls which not be debounced would be something like:
 * grid!.getSelectedRow() -> we expect a value, so it should not be debounced.
 * grid!.clearData() -> it should be executed immediately because other calls might depend on it.
*/
/**
 * This point is reached in two scenarios:
 *
 * 1. The script SHOULD be debounced
 * 2. The script SHOULD NOT be debounced but the widget is not ready yet so debouncing is enforced until the widget is ready
 *
 * We check if debouncing is enabled for the current platform (BUI, GUI) then
 *
 * Debouncing is ENABLED :
 * 1. If the widget is READY we execute the script directly
 * 2. If the widget is NOT READY we add the script to the queue for later execution
 *
 * Debouncing is NOT ENABLED:
 * 1. add the script to the queue for later execution
 * 2. Iin case the grid is ready start a count down before executing the code
 * in the BBjHtmlView control. the countdown will be restated if the developer tries
 * to execute anything new before the counted down reaches 0.
 *
*/
/**
 * Executes the provided JavaScript code on the client and uses the script itself as a key with the specified priority.
 *
 * @param BBjString script! The JavaScript code to execute.
 * @param BBjNumber debounced! A BBjNumber acting as a boolean that determines whether the executor will debounce the script (1) or execute it immediately (0).
 * @param 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.
 *
 * @return Object The result of the JavaScript code execution if the script returns a value.
*/
public Object execute(BBjString script!, BBjNumber debounced!, BBjNumber priority!) { }
/**
 * Executes the provided JavaScript code on the client without a priority, which is a more typical use case.
 *
 * @param 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.
 * @param BBjString script! The JavaScript code to execute.
 * @param BBjNumber debounced! A BBjNumber acting as a boolean that determines whether the executor will debounce the script (1) or execute it immediately (0).
 *
 * @return Object The result of the JavaScript code execution if the script returns a value.
*/
public Object execute(BBjString key!, 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.
 *
 * @param BBjString script! The JavaScript code to execute.
 * @param BBjNumber debounced! A BBjNumber acting as a boolean that determines whether the executor will debounce the script (1) or execute it immediately (0).
 *
 * @return Object The result of the JavaScript code execution if the script returns a value.
*/
public Object execute(BBjString script!, BBjNumber debounced!) { }
/**
 * Executes <i>and debounces</i> the provided JavaScript code on the client without a priority.
 *
 * @param 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.
 * @param BBjString script! The JavaScript code to execute.
 *
 * @return Object The result of the JavaScript code execution if the script returns a value.
*/
public Object execute(BBjString key!, BBjString script!) { }
/**
 * Executes <i>and debounces</i> the provided JavaScript code on the client using the script itself as a key and without a priority.
 *
 * @param BBjString script! The JavaScript code to execute.
 *
 * @return Object The result of the JavaScript code execution if the script returns a value.
*/
public Object execute(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 <code>Object</code>.
 *
 * @param BBjString script$ The JavaScript code to execute.
 *
 * @return Object The result of the JavaScript code execution if the script returns a value.
*/
public Object executeImmediately(BBjString script!) { }
/**
 * 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.
 *
 * @return BBjJavaScriptExecutor the executor instance.
*/
public BBjJavaScriptExecutor flush() { }
/**
 * 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.
 *
 * @param BBjTimerEvent event!
*/
public void onFlush(BBjTimerEvent event!) { }
/**
 * Returns a boolean that indicates whether the widget is running in BUI or not.
 *
 * @return BBjNumber Returns true when the platform is BUI and false if it's GUI.
*/
protected boolean isBui() { }
/**
 * Enqueues a script for execution at a later time.
 *
 * @param 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.
 * @param BBjString script! The JavaScript code to execute.
 * @param BBjNumber priority! The script's priority value that serves as its index in the queue.
 *
 * @return BBjJavaScriptExecutor The executor instance.
*/
protected BBjJavaScriptExecutor enqueue(BBjString key!, BBjString script!, BBjNumber priority!) { }
/**
 * Executes the provided JavaScript directly in the BBjHtmlView control without enqueuing, called by the flush method with a flag that indicates if it's executing a queue of scripts or not.
 *
 * @param BBjString script! The JavaScript code to execute.
 * @param BBjString isDebounced! A BBjNumber acting as a boolean that indicates whether the script is coming from the queue or not.
 *
 * @return Object The result of the JavaScript code execution if the script returns a value.
*/
protected Object executeInHtmlView(BBjString script!, BBjNumber isDebounced!) { }
/**
 * Starts the count down timer. When the timer reaches 0 then the queue will be flushed.
 *
 * @return BBjJavaScriptExecutor The executor instance so that the method may be chained.
*/
protected BBjJavaScriptExecutor startTimer() { }
/**
 * Stops the last created timer if it exists, preventing the executor from reaching the point where it needs to flush its content.
 *
 * @return BBjJavaScriptExecutor The executor instance so that the method may be chained.
*/
protected BBjJavaScriptExecutor endTimer() { }
/**
 * Returns a boolean that indicates whether the widget is ready to be interacted with or not (usually after the ON_PAGE_LOADED event).
 *
 * @return BBjNumber Returns True when the platform is BUI and false if it's GUI.
*/
protected boolean IsReady() { }
/**
 * Sets the BBjWidget with which this executor will be used.
 *
 * @param BBjJavaScriptExecutor The executor instance.
*/
protected void setWidget(BBjWidget widget!) { }
/**
 * Returns the widget instance as a BBjWidget.
 *
 * @return BBjWidget The widget instance.
*/
protected BBjWidget getWidget() { }
}