RFR: 8238080: FXMLLoader: if script engines implement javax.script.Compilable compile scripts

[Rony G.Flatscher]

On Tue, 12 May 2020 16:51:08 GMT, Rony G. Flatscher <github.com+60214806+ronyfla at openjdk.org> wrote:

>> I think the approach proposed in this PR is the best solution for this enhancement. Go ahead and remove the `WIP` from
>> the title, and we can proceed with the review.
>> The interface and behavior change will need to be specified in the API docs. This can be done by modifying the
>> [Introduction to
>> FXML](https://github.com/openjdk/jfx/blob/master/modules/javafx.fxml/src/main/docs/javafx/fxml/doc-files/introduction_to_fxml.html)
>> document. I recommend documenting the new behavior and `<?compile>` attribute somewhere in the
>> [Scripting](https://github.com/openjdk/jfx/blob/master/modules/javafx.fxml/src/main/docs/javafx/fxml/doc-files/introduction_to_fxml.html#L769)
>> section.  As discussed on the mailing list, this will need a CSR, which should include the changes to the docs.
>
> Suggested CSR:
> 
> Summary
> =======
> Have javafx.fxml.FXMLLoader compile FXML scripts before evaluating them, if the script engine
> implements the javax.script.Compilable interface to speed up execution. In case compilation
> throws a javax.script.ScriptException fall back to evaluating the uncompiled script. Allow
> control of script compilation with a "compile" PI for FXML files.
> 
> Problem
> =======
> javafx.fxml.FXMLLoader is able to execute scripts in Java script languages
> (javax.script.ScriptEngine implementations) referred to or embedded in a FXML file.
> 
> If a script engine implements the javax.script.Compilable interface, then such scripts could be
> compiled and the resulting javax.script.CompiledScript could be executed instead using its
> eval() methods.
> 
> Evaluating the javax.script.CompiledScript objects may help speed up the execution of script
> invocations, especially for scripts defined for event attributes in FXML elements (e.g. like
> onMouseMove) which may be repetitively invoked and evaluated.
> 
> Solution
> ========
> Before evaluating the script code test whether the javax.script.ScriptEngine implements
> javax.script.Compilable. If so, compile the script to a javax.script.CompiledScript object first
> and then use its eval() method to evaluate the script, otherwise continue to use the
> javax.script.ScriptEngine's eval() method instead. Should compilation of a script yield
> (unexpectedly) a javax.script.ScriptException then fall back to using the
> javax.script.ScriptEngine's eval() method. A new process instruction "compile" allows control of
> the compilation of scripts ("true" sets compilation on, "false" to set compilation off) in FXML
> files.
> 
> Specification
> =============
> If a javax.script.ScriptEngine implements the javax.script.Compilable interface, then use its
> compile() method to compile the script to a javax.script.CompiledScript object and use its
> eval() method to run the script. In the case that the compilation throws (unexpectedly) a
> javax.script.ScriptException log a warning and fall back to using the
> javax.script.ScriptEngine's eval() method instead.
> To allow setting this feature off and on while processing the FXML file a "compile" process
> instruction ("<?compile false?>" or "<?compile true?>") gets defined that allows to turn
> compilation off and on throughout a FXML file.

Doc addition for the CSR:
=================
The following text was added to the [Introduction to
FXML](https://github.com/openjdk/jfx/blob/master/modules/javafx.fxml/src/main/docs/javafx/fxml/doc-files/introduction_to_fxml.html)
at two locations, the "Script Event Handlers" ("#script_event_handlers") and the "Scripting" (#scripting") sections:

> <p>Hint: to turn off automatic compilation of script code place the processing instruction <span
> class="code"><?compile false?></span> before the script. To turn on compilation of script code again use the
> processing instruction <span class="code"><?compile true?></span> (or short: <span
> class="code"><?compile?></span>). The compile processing instruction can be used repeatedly to turn compilation
> of script code off and on.</p>

This documents the compile processing instruction, that it compilation is on by default and that it can be turned off
and on repeatedly. It is hoped that this formulation plays well with the context where this paragraph got introduced.

-------------

PR: https://git.openjdk.java.net/jfx/pull/192