Skip to content

Commit d68ff70

Browse files
dilyanpalauzovdilyanpalauzov
committed
JSR223 mention lifecycle, media and provider presets, scriptLoaded and scriptUnloaded functions
1 parent 5666e10 commit d68ff70

File tree

1 file changed

+172
-3
lines changed

1 file changed

+172
-3
lines changed

‎configuration/jsr223.md‎

Lines changed: 172 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -236,23 +236,27 @@ Note that prior to openHAB 3, script ordering was performed alphanumerically bas
236236

237237
To facilitate JSR223 scripting, several openHAB-related variables are automatically predefined within `ScriptExtension` presets.
238238
They can be loaded into the script context using `scriptExtension.importPreset(String preset)`, e.g. `scriptExtension.importPreset("RuleSimple")`.
239-
The `default` preset is preloaded, so it does not require importing.
239+
The `default`, `lifecycle` and `media` presets are preloaded, so they do not require importing.
240240
With `scriptExtension.get("automationManager")` the `automationManager` can be made available without loading a preset.
241241

242242
- [Overview](#overview)
243243
- [Example rules for a first impression](#example-rules-for-a-first-impression)
244244
- [Script Locations](#script-locations)
245245
- [`ScriptExtension` Objects (all JSR223 languages)](#scriptextension-objects-all-jsr223-languages)
246-
- [Default Preset (`importPreset` not required)](#default-preset-importpreset-not-required)
246+
- [`default` Preset (`importPreset` not required)](#default-preset-importpreset-not-required)
247247
- [`events` operations](#events-operations)
248+
- [`lifecycle` Preset (`importPreset` not required)](#lifecycle-preset-importpreset-not-required)
249+
- [`media` Preset (`importPreset` not required)](#media-preset-importpreset-not-required)
248250
- [`RuleSimple` Preset](#rulesimple-preset)
249251
- [`RuleSupport` Preset](#rulesupport-preset)
250252
- [`RuleFactories` Preset](#rulefactories-preset)
251253
- [`ScriptAction` Preset](#scriptaction-preset)
252254
- [`cache` Preset](#cache-preset)
255+
- [`provider` Preset](#provider-preset)
253256
- [`TriggerType` Objects (all JSR223 languages)](#triggertype-objects-all-jsr223-languages)
257+
- [The `scriptLoaded` and `scriptUnloaded` functions](#the-scriptloaded-and-scriptunloaded-functions)
254258

255-
#### Default Preset (`importPreset` not required)
259+
#### `default` Preset (`importPreset` not required)
256260

257261
| Variable | Description |
258262
|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -335,6 +339,24 @@ With `scriptExtension.get("automationManager")` the `automationManager` can be m
335339
- `events.storeStates(Item...)`
336340
- `events.restoreStates(Map<Item, State>)`
337341

342+
#### `lifecycle` Preset (`importPreset` not required)
343+
344+
It provides a mechanism to execute code, when the script is deleted.
345+
Modifying a script deletes it and creates it again.
346+
347+
| Variable | Description |
348+
|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
349+
| `lifecycleTracker` | [`org.openhab.core.automation.module.script.LifecycleScriptExtensionProvider.LifecycleTracker`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/module/script/lifecyclescriptextensionprovider.lifecycletracker) |
350+
351+
This is demonstrated in [The `scriptLoaded` and `scriptUnloaded` functions](#the-scriptloaded-and-scriptunloaded-functions) section.
352+
353+
#### `media` Preset (`importPreset` not required)
354+
355+
| Variable | Description |
356+
|----------|---------------------------------------------------------------------------------------------------------------------|
357+
| `audio` | [`org.openhab.core.audio.AudioManager`](https://www.openhab.org/javadoc/latest/org/openhab/core/audio/audiomanager) |
358+
| `voice` | [`org.openhab.core.voice.VoiceManager`](https://www.openhab.org/javadoc/latest/org/openhab/core/voice/voicemanager) |
359+
338360
#### `RuleSimple` Preset
339361

340362
These variables and classes are loaded using:
@@ -532,6 +554,25 @@ Both caches implement the `org.openhab.core.automation.module.script.rulesupport
532554
- `Object get(String key)`: Get the value for the given key from the cache. Non-existent keys return `null`.
533555
- `Object get(String key, Supplier<Object> supplier`: Get the value for the given key. If no value is present, add the value that is return from the `supplier`.
534556

557+
#### `provider` Preset
558+
559+
The preset is available since openHAB 5.0.
560+
561+
| Variable | Description |
562+
|---------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
563+
| `itemRegistry` | [`org.openhab.core.automation.module.script.providersupport.shared.ProviderItemRegistryDelegate`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/module/script/providersupport/shared/provideritemregistrydelegate) |
564+
| `metadataRegistry` | [`org.openhab.core.automation.module.script.providersupport.shared.ProviderMetadataRegistryDelegate`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/module/script/providersupport/shared/providermetadataregistrydelegate) |
565+
| `thingRegistry` | [`org.openhab.core.automation.module.script.providersupport.shared.ProviderThingRegistryDelegate`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/module/script/providersupport/shared/providerthingregistrydelegate) |
566+
| `itemChannelLinkRegistry` | [`org.openhab.core.automation.module.script.providersupport.shared.ProviderItemChannelLinkRegistry`](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/module/script/providersupport/shared/provideritemchannellinkregistry) |
567+
568+
The above instances provide implementations of the interfaces [`org.openhab.core.items.ItemRegistry`](https://www.openhab.org/javadoc/latest/org/openhab/core/items/itemregistry), [`org.openhab.core.items.MetadataRegistry`](https://www.openhab.org/javadoc/latest/org/openhab/core/items/metadataregistry) and [`org.openhab.core.thing.ThingRegistry`](https://www.openhab.org/javadoc/latest/org/openhab/core/thing/thingregistry) respectively.
569+
The `itemChannelLinkRegistry` does not provide the same methods as the [`org.openhab.core.thing.link.ItemChannelLinkRegistry`](https://www.openhab.org/javadoc/latest/org/openhab/core/thing/link/itemchannellinkregistry) interface.
570+
571+
All instances from this preset have an `addPermanent(…)` method, in addition to `add(…)`.
572+
With the `add(…)` method, elements added over the above instances are removed, when the script, which inserted the elements, is deleted or changed.
573+
When `addPermanent(…)` is used, the inserted elements are … not removed.
574+
`itemRegistry.addPermanent(…)`/`thingRegistry.addPermanent(…)` from this preset offer the same functionality as `itemRegistry.add(…)`/`things.add(…)` from the `default` preset.
575+
535576
### `TriggerType` Objects (all JSR223 languages)
536577

537578
The following trigger types are defined by openHAB (custom triggers can also be defined) and take the specified configuration parameters.
@@ -666,3 +707,131 @@ Read the JSR223 language specific documentation for examples of using these `Tri
666707
| `startlevel` | The system `StartLevel` |
667708

668709
:::
710+
711+
### The `scriptLoaded` and `scriptUnloaded` functions
712+
713+
When a JSR223 script is created or changed and it contains the `scriptLoaded(String)` function, OpenHAB executes it, and passes as parameter the path of the loaded script.
714+
Similarly, when a script is changed or deleted, and the script contained the `scriptUnloaded()` function, it is invoked.
715+
`scriptLoaded(String)` is only executed when a script from the automation add-on directory, like `${OPENHAB_CONF}/automation/jsr223/`, is loaded.
716+
It is not executed in transformations, UI rules with Inline Script action, UI scripts.
717+
The [`lifecycleTracker`](#lifecycle-preset-importpreset-not-required) object and the `scriptUnloaded()` function serve similar purposes.
718+
When a script is executed several times, on each execution it adds a Disposable, and then the script is changed, its `scriptUnloaded()` is executed once and each added Disposable is also `dispose()`d.
719+
720+
:::: tabs
721+
722+
::: tab Groovy
723+
724+
```groovy
725+
static @groovy.transform.Field logger = org.slf4j.LoggerFactory.getLogger("org.openhab.automation.example")
726+
727+
lifecycleTracker.addDisposeHook(new org.openhab.core.automation.module.script.LifecycleScriptExtensionProvider.Disposable() {
728+
public void dispose() {
729+
logger.error("I am logged fourth.")
730+
}
731+
})
732+
733+
lifecycleTracker.addDisposeHook{ logger.error("I am logged fifth. Bye!") }
734+
735+
void scriptLoaded(String filename) { // can be static
736+
logger.error("I am logged second and I am from ${filename}.")
737+
}
738+
739+
static void scriptUnloaded() { // can be non-static
740+
logger.error("I am logged third.")
741+
}
742+
logger.error("I am logged first.")
743+
```
744+
745+
:::
746+
747+
::: tab JS&nbsp;Nashorn
748+
749+
```js
750+
var logger = Java.type('org.slf4j.LoggerFactory').getLogger("org.openhab.core.automation.examples")
751+
lifecycleTracker.addDisposeHook(function() {
752+
logger.error("I am logged fourth. Bye!")
753+
})
754+
function scriptLoaded(filename) {
755+
logger.error("I am logged second and I am from " + filename + ".")
756+
}
757+
function scriptUnloaded() {
758+
logger.error("I am logged third.")
759+
}
760+
logger.error("I am logged first.")
761+
```
762+
763+
:::
764+
765+
::: tab JS&nbsp;Scripting
766+
767+
```js
768+
require('@runtime').lifecycleTracker.addDisposeHook( () => console.log("I am logged fourth. Bye!") )
769+
770+
const scriptUnloaded = () => console.log("I am logged third.")
771+
772+
function scriptLoaded(filename) {
773+
console.log(`I am logged second and I am from ${filename}.`)
774+
}
775+
776+
console.log("I am logged first.")
777+
```
778+
779+
:::
780+
781+
::: tab Jython
782+
783+
```python
784+
from org.slf4j import LoggerFactory
785+
786+
logger = LoggerFactory.getLogger("org.openhab.core.automation.examples")
787+
788+
def scriptUnloaded():
789+
logger.error("I am logged third.")
790+
791+
def scriptLoaded(filename):
792+
logger.error("I am logged second and I am from " + filename + ".")
793+
794+
lifecycleTracker.addDisposeHook(lambda : logger.error("I am logged fourth. Bye!"))
795+
logger.error("I am logged first.")
796+
```
797+
798+
:::
799+
800+
::: tab Python
801+
802+
When the setting “Use scope and import wrapper” is on, the `scope` module is enabled:
803+
804+
```python
805+
import sys
806+
import scope
807+
808+
def scriptUnloaded():
809+
print("I am logged third.")
810+
811+
def scriptLoaded(filename):
812+
print("I am logged second and I am from " + filename + ".")
813+
814+
scope.lifecycleTracker.addDisposeHook(lambda : print("I am logged fourth. Bye!"))
815+
816+
print("I am logged first.")
817+
```
818+
819+
When the `scope` module is disabled:
820+
821+
```python
822+
import sys
823+
824+
def scriptUnloaded():
825+
print("I am logged third.")
826+
827+
def scriptLoaded(filename):
828+
print("I am logged second and I am from " + filename + ".")
829+
830+
lifecycleTracker.addDisposeHook(lambda : print("I am logged fourth. Bye!"))
831+
832+
print("I am logged first.")
833+
```
834+
835+
:::
836+
837+
::::

0 commit comments

Comments
 (0)