[jsscripting] Rename library injection parameter & Improve docs (#15547)

* [jsscripting] Rename parameter useIncludedLibrary to injectionCachingEnabled (#4)
* [jsscripting] Improve README for cached library injection
* Remove settings image

Signed-off-by: Florian Hotze <florianh_dev@icloud.com>

bundles/org.openhab.automation.jsscripting/README.md

@@ -39,13 +39,25 @@ to common openHAB functionality within rules including items, things, actions, l
 ## Configuration
 
 This add-on includes by default the [openhab-js](https://github.com/openhab/openhab-js/) NPM library and exports its namespaces onto the global namespace.
+
 This allows the use of `items`, `actions`, `cache` and other objects without the need to explicitly import them using `require()`.
 This functionality can be disabled for users who prefer to manage their own imports via the add-on configuration options.
 
-By default, the injection of the included [openhab-js](https://github.com/openhab/openhab-js/) NPM library is cached to improve performance and reduce memory usage.
+By default, the injection of the [openhab-js](https://github.com/openhab/openhab-js/) NPM library is cached (using a special mechanism instead of `require()`) to improve performance and reduce memory usage.
-If you want to use a different version of openhab-js (installed to the `node_modules` folder) than the included one, you need to disable the usage of the included library.
 
-![openHAB Rule Configuration](doc/settings.png)
+When configuring the add-on, you should ask yourself these questions:
+
+1. Do I want to have the openhab-js namespaces automatically globally available (`injectionEnabled`)?
+   - Yes: "Use Built-In Variables" (default)
+   - No: "Do Not Use Built-In Variables", which will allow you to decide what to import and really speed up script loading, but you need to manually import the library, which actually will slow down script loading again.
+2. Do I want to have a different version injected other than the included one (`injectionCachingEnabled`)?
+   - Yes: "Do Not Cache Library Injection" and install your version to the `$OPENHAB_CONF/automation/js/node_modules` folder, which will slow down script loading, because the injection is not cached.
+   - No: "Cache Library Injection" (default), which will speed up the initial loading of a script because the library's injection is cached.
+
+Note that in case you disable caching or your code uses `require()` to import the library and there is no installation of the library found in the node_modules folder, the add-on will fallback to its included version.
+
+In general, the first run of a script will take longer than the subsequent runs.
+This is because on the first run both the globals (like `console`) and (if enabled) the library are injected into the script's context.
 
 <!-- Paste the copied docs from openhab-js under this comment. Do NOT forget the table of contents. -->
 

bundles/org.openhab.automation.jsscripting/src/main/java/org/openhab/automation/jsscripting/internal/GraalJSScriptEngineFactory.java

@@ -45,7 +45,7 @@ import com.oracle.truffle.js.scriptengine.GraalJSEngineFactory;
 @NonNullByDefault
 public final class GraalJSScriptEngineFactory implements ScriptEngineFactory {
     private static final String CFG_INJECTION_ENABLED = "injectionEnabled";
-    private static final String CFG_USE_INCLUDED_LIBRARY = "useIncludedLibrary";
+    private static final String CFG_INJECTION_CACHING_ENABLED = "injectionCachingEnabled";
 
     private static final GraalJSEngineFactory factory = new GraalJSEngineFactory();
 
@@ -59,7 +59,7 @@ public final class GraalJSScriptEngineFactory implements ScriptEngineFactory {
     }
 
     private boolean injectionEnabled = true;
-    private boolean useIncludedLibrary = true;
+    private boolean injectionCachingEnabled = true;
 
     private final JSScriptServiceUtil jsScriptServiceUtil;
     private final JSDependencyTracker jsDependencyTracker;
@@ -87,8 +87,8 @@ public final class GraalJSScriptEngineFactory implements ScriptEngineFactory {
         if (!scriptTypes.contains(scriptType)) {
             return null;
         }
-        return new DebuggingGraalScriptEngine<>(new OpenhabGraalJSScriptEngine(injectionEnabled, useIncludedLibrary,
+        return new DebuggingGraalScriptEngine<>(new OpenhabGraalJSScriptEngine(injectionEnabled,
-                jsScriptServiceUtil, jsDependencyTracker));
+                injectionCachingEnabled, jsScriptServiceUtil, jsDependencyTracker));
     }
 
     @Override
@@ -99,6 +99,7 @@ public final class GraalJSScriptEngineFactory implements ScriptEngineFactory {
     @Modified
     protected void modified(Map<String, ?> config) {
         this.injectionEnabled = ConfigParser.valueAsOrElse(config.get(CFG_INJECTION_ENABLED), Boolean.class, true);
-        this.useIncludedLibrary = ConfigParser.valueAsOrElse(config.get(CFG_USE_INCLUDED_LIBRARY), Boolean.class, true);
+        this.injectionCachingEnabled = ConfigParser.valueAsOrElse(config.get(CFG_INJECTION_CACHING_ENABLED),
+                Boolean.class, true);
     }
 }

bundles/org.openhab.automation.jsscripting/src/main/java/org/openhab/automation/jsscripting/internal/OpenhabGraalJSScriptEngine.java

@@ -139,17 +139,17 @@ public class OpenhabGraalJSScriptEngine
 
     private boolean initialized = false;
     private final boolean injectionEnabled;
-    private final boolean useIncludedLibrary;
+    private final boolean injectionCachingEnabled;
 
     /**
      * Creates an implementation of ScriptEngine (& Invocable), wrapping the contained engine, that tracks the script
      * lifecycle and provides hooks for scripts to do so too.
      */
-    public OpenhabGraalJSScriptEngine(boolean injectionEnabled, boolean useIncludedLibrary,
+    public OpenhabGraalJSScriptEngine(boolean injectionEnabled, boolean injectionCachingEnabled,
             JSScriptServiceUtil jsScriptServiceUtil, JSDependencyTracker jsDependencyTracker) {
         super(null); // delegate depends on fields not yet initialised, so we cannot set it immediately
         this.injectionEnabled = injectionEnabled;
-        this.useIncludedLibrary = useIncludedLibrary;
+        this.injectionCachingEnabled = injectionCachingEnabled;
         this.jsRuntimeFeatures = jsScriptServiceUtil.getJSRuntimeFeatures(lock);
 
         LOGGER.debug("Initializing GraalJS script engine...");
@@ -279,7 +279,7 @@ public class OpenhabGraalJSScriptEngine
             LOGGER.debug("Evaluating cached global script...");
             delegate.getPolyglotContext().eval(GLOBAL_SOURCE);
             if (this.injectionEnabled) {
-                if (this.useIncludedLibrary) {
+                if (this.injectionCachingEnabled) {
                     LOGGER.debug("Evaluating cached openhab-js injection...");
                     delegate.getPolyglotContext().eval(OPENHAB_JS_SOURCE);
                 } else {

bundles/org.openhab.automation.jsscripting/src/main/resources/OH-INF/config/config.xml

@@ -17,15 +17,15 @@
 			</options>
 			<default>true</default>
 		</parameter>
-		<parameter name="useIncludedLibrary" type="boolean" required="true">
+		<parameter name="injectionCachingEnabled" type="boolean" required="true">
-			<label>Use Included openHAB JavaScript Library</label>
+			<label>Cache openHAB JavaScript Library Injection</label>
 			<description><![CDATA[
-			Use the included openHAB JavaScript library for optimal performance.<br>
+			Cache the openHAB JavaScript library injection for optimal performance.<br>
-			Disable this option to allow loading the library from the local user configuration directory "automation/js/node_modules". Using a user provided version of the library may increase script loading times, especially on less powerful systems.
+			Disable this option to allow loading the library from the local user configuration directory "automation/js/node_modules". Disabling caching may increase script loading times, especially on less powerful systems.
 			]]></description>
 			<options>
-				<option value="true">Use Included Library</option>
+				<option value="true">Cache Library Injection</option>
-				<option value="false">Do Not Use Included Library</option>
+				<option value="false">Do Not Cache Library Injection</option>
 			</options>
 			<default>true</default>
 		</parameter>

bundles/org.openhab.automation.jsscripting/src/main/resources/OH-INF/i18n/jsscripting.properties

@@ -1,12 +1,15 @@
+# add-on
+
+addon.jsscripting.name = JavaScript Scripting
+addon.jsscripting.description = This adds a JS (ECMAScript-2021) script engine.
+
+# add-on
+
+automation.config.jsscripting.injectionCachingEnabled.label = Cache openHAB JavaScript Library Injection
+automation.config.jsscripting.injectionCachingEnabled.description = Cache the openHAB JavaScript library injection for optimal performance.<br>Disable this option to allow loading the library from the local user configuration directory "automation/js/node_modules". Disabling caching may increase script loading times, especially on less powerful systems.
+automation.config.jsscripting.injectionCachingEnabled.option.true = Cache Library Injection
+automation.config.jsscripting.injectionCachingEnabled.option.false = Do Not Cache Library Injection
 automation.config.jsscripting.injectionEnabled.label = Use Built-in Global Variables
 automation.config.jsscripting.injectionEnabled.description = Import all variables from the openHAB JavaScript library into all rules for common services like items, things, actions, log, etc... <br> If disabled, the openHAB JavaScript library can be imported manually using "<i>require('openhab')</i>"
 automation.config.jsscripting.injectionEnabled.option.true = Use Built-in Variables
 automation.config.jsscripting.injectionEnabled.option.false = Do Not Use Built-in Variables
-automation.config.jsscripting.useIncludedLibrary.label = Use Included openHAB JavaScript Library
-automation.config.jsscripting.useIncludedLibrary.description = Use the included openHAB JavaScript library for optimal performance.<br> Disable this option to allow loading the library from the local user configuration directory "automation/js/node_modules". Using a user provided version of the library may increase script loading times, especially on less powerful systems.
-automation.config.jsscripting.useIncludedLibrary.option.true = Use Included Library
-automation.config.jsscripting.useIncludedLibrary.option.false = Do Not Use Included Library
-
-# service
-
-service.automation.jsscripting.label = JavaScript Scripting