Startlevel execution support for jsr223 scripts (#1511)

* Startlevel execution support for jsr223 scripts JSR223 scripts can now be run at specific start levels as of openhab/openhab-core#2222 This PR adds the docs to describe how it can be used. Signed-off-by: Jonathan Gilbert <[email protected]> * Add linebreaks. Signed-off-by: Jerome Luckenbach <[email protected]> Co-authored-by: Jerome Luckenbach <[email protected]>
openhab · Mar 15, 2021 · 11d7632 · 11d7632
1 parent b5ebf3e
commit 11d7632
Showing 1 changed file with 13 additions and 9 deletions.
diff --git a/configuration/jsr223.md b/configuration/jsr223.md
@@ -118,23 +118,27 @@ Scripts should be placed in the `${OPENHAB_CONF}/automation/jsr223/` directory.
 This directory will vary, [based on the type of openHAB installation used](https://www.openhab.org/docs/installation/linux.html#installation).
 For example, Linux installations created with a package installer will use `/etc/openhab/automation/jsr223/`, and manual installations will use `/opt/openhab/conf/automation/jsr223/`.
 
-When openHAB starts, scripts will be loaded in an order based on their file name.
-If the scripts have the same name, which should rarely happen, the parent directories will be considered in the sort.
+When openHAB starts, scripts are loaded at start level 40 by default (in no particular order).
+The start level for each script can be overriden by specifying a start level either in the filename (`./my_script.sl50.py`) or containing directory (`./sl50/my_script.py`).
+The runtime provides no explicit dependency mechanism or ordering, yet scripts are loaded one at a time so can be ordered via start level if desired.
 For example, with the following scripts and directory structure...
 
 ```text
 ├── automation/jsr223
 │   ├── dir1
-│   │   ├── 001_script.py
-│   │   └── script.py
-│   ├── 001_script.py
-│   ├── dir2
-│   │   ├── 002_script.py
-│   │   └── script.py
+│   │   ├── script_a.py
+│   │   └── script_b.py
+│   ├── script.sl38.py
+│   ├── sl30
+│   │   ├── script_x.py
+│   │   └── script_y.py
 │   └── script.py
 ```
 
-... the load order will be: `/001_script.py`, `/dir1/001_script.py`, `/dir2/002_script.py`, `/script.py`, `/dir1/script.py`, `/dir2/script.py`.
+... the load order will be: (`sl30/script_x.py` & `sl30/script_y.py`) at start level 30, `script.sl38.py` at start level 38, then (`/dir1/script_a.py`, `/dir1/script_b.py`, `script.py`) at start level 40.
+The script file watching mechanism itself is activated at start level 20, so scripts cannot be executed earlier than this.
+
+Note that prior to openHAB 3, script ordering was performed alphanumerically based on file path. This is no longer supported as of openHAB 3.
 
 ### `ScriptExtension` Objects (all JSR223 languages)