diff --git a/bundles/org.openhab.automation.jsscripting/README.md b/bundles/org.openhab.automation.jsscripting/README.md index bc9655c5bc2b3..c7afa016cb130 100644 --- a/bundles/org.openhab.automation.jsscripting/README.md +++ b/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. -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. +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. + +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. -![openHAB Rule Configuration](doc/settings.png) +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. diff --git a/bundles/org.openhab.automation.jsscripting/doc/settings.png b/bundles/org.openhab.automation.jsscripting/doc/settings.png deleted file mode 100644 index a0f5dddc059a3..0000000000000 Binary files a/bundles/org.openhab.automation.jsscripting/doc/settings.png and /dev/null differ diff --git a/bundles/org.openhab.automation.jsscripting/src/main/java/org/openhab/automation/jsscripting/internal/GraalJSScriptEngineFactory.java b/bundles/org.openhab.automation.jsscripting/src/main/java/org/openhab/automation/jsscripting/internal/GraalJSScriptEngineFactory.java index 15c4a90250671..61d7f97c4308f 100644 --- a/bundles/org.openhab.automation.jsscripting/src/main/java/org/openhab/automation/jsscripting/internal/GraalJSScriptEngineFactory.java +++ b/bundles/org.openhab.automation.jsscripting/src/main/java/org/openhab/automation/jsscripting/internal/GraalJSScriptEngineFactory.java @@ -45,7 +45,7 @@ @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 @@ private static List createScriptTypes() { } 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 void scopeValues(ScriptEngine scriptEngine, Map scopeValu if (!scriptTypes.contains(scriptType)) { return null; } - return new DebuggingGraalScriptEngine<>(new OpenhabGraalJSScriptEngine(injectionEnabled, useIncludedLibrary, - jsScriptServiceUtil, jsDependencyTracker)); + return new DebuggingGraalScriptEngine<>(new OpenhabGraalJSScriptEngine(injectionEnabled, + injectionCachingEnabled, jsScriptServiceUtil, jsDependencyTracker)); } @Override @@ -99,6 +99,7 @@ public void scopeValues(ScriptEngine scriptEngine, Map scopeValu @Modified protected void modified(Map 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); } } diff --git a/bundles/org.openhab.automation.jsscripting/src/main/java/org/openhab/automation/jsscripting/internal/OpenhabGraalJSScriptEngine.java b/bundles/org.openhab.automation.jsscripting/src/main/java/org/openhab/automation/jsscripting/internal/OpenhabGraalJSScriptEngine.java index 432a3a2c28499..3233ab745c478 100644 --- a/bundles/org.openhab.automation.jsscripting/src/main/java/org/openhab/automation/jsscripting/internal/OpenhabGraalJSScriptEngine.java +++ b/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 @@ protected void beforeInvocation() { 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 { diff --git a/bundles/org.openhab.automation.jsscripting/src/main/resources/OH-INF/config/config.xml b/bundles/org.openhab.automation.jsscripting/src/main/resources/OH-INF/config/config.xml index 0d6230c76ed0c..f5b82929c6aee 100644 --- a/bundles/org.openhab.automation.jsscripting/src/main/resources/OH-INF/config/config.xml +++ b/bundles/org.openhab.automation.jsscripting/src/main/resources/OH-INF/config/config.xml @@ -17,15 +17,15 @@ true - - + + - 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. + Cache the openHAB JavaScript library injection for optimal performance.
+ 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. ]]> - - + + true diff --git a/bundles/org.openhab.automation.jsscripting/src/main/resources/OH-INF/i18n/jsscripting.properties b/bundles/org.openhab.automation.jsscripting/src/main/resources/OH-INF/i18n/jsscripting.properties index f9fb7c9d786b7..c4035c095b7f5 100644 --- a/bundles/org.openhab.automation.jsscripting/src/main/resources/OH-INF/i18n/jsscripting.properties +++ b/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.
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...
If disabled, the openHAB JavaScript library can be imported manually using "require('openhab')" 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.
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