Skip to content

Commit

Permalink
Added warning and small updates
Browse files Browse the repository at this point in the history 
I did some tidying up, corrected some of the classes that changed due to the ESH reintegration, and added a warning about using anything other than the official APIs (requested here... openhab/openhab-core#663 (comment)).

Signed-off-by: Scott Rushworth <openhab@5iver.com>
  • Loading branch information
Scott Rushworth committed Apr 7, 2019
1 parent 010c8b6 commit 8181b72
Showing 1 changed file with 138 additions and 101 deletions.
239 changes: 138 additions & 101 deletions configuration/jsr223.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,103 +13,63 @@ title: JSR223 Scripting
## Overview

[JSR223](https://docs.oracle.com/javase/6/docs/technotes/guides/scripting/) ([spec](https://jcp.org/aboutJava/communityprocess/pr/jsr223/index.html))
is a standard scripting API for Java Virtual Machine (JVM)
[languages](https://en.wikipedia.org/wiki/List_of_JVM_languages).
[JSR223](https://docs.oracle.com/javase/6/docs/technotes/guides/scripting/) ([spec](https://jcp.org/aboutJava/communityprocess/pr/jsr223/index.html)) is a standard scripting API for Java Virtual Machine (JVM) [languages](https://en.wikipedia.org/wiki/List_of_JVM_languages).
The JVM languages provide varying levels of support for the JSR223 API and interoperability with the Java runtime.
Currently the following languages are known to work well for openHAB scripting:
[**Oracle Nashorn**](http://www.oracle.com/technetwork/articles/java/jf14-nashorn-2126515.html) (Javascript bundled with Java),
[**Jython**](http://www.jython.org/) (Python on the JVM) and
[**Jython**](https://jython.github.io/) (Python on the JVM),
[**Nashorn Javascript**](http://www.oracle.com/technetwork/articles/java/jf14-nashorn-2126515.html) (ECMAScript implementation included in JDK8 through 10, [deprecated in 11](https://openjdk.java.net/jeps/335)), and
[**Apache Groovy**](http://www.groovy-lang.org/) (JVM scripting language).

Although JSR223 scripts can be used as a general-purpose extension language for openHAB,
the most common usage will be for defining openHAB rules.
Although JSR223 scripts can be used as a general-purpose extension language for openHAB, it is most commonly used for the creation of rules, and within scripted Actions or Conditions.
Currently, openHAB allows JSR223 scripting to access all packages, which may not be included in the official APIs.
This provides great flexibility for the users of JSR223, but is also *use at your own risk*, since changes outside of the offical APIs occur frequently, and are not considered to be *breaking changes*.
New APIs are planned to be implemented in the future, which will provide standardized interfaces for interacting with openHAB through scripted automation.

### Language-Specific Documentation

- [Javascript](jsr223-js.html)
- [Jython](jsr223-jython.html)
- [Javascript](jsr223-js.html)
- Groovy (TODO)

### Script Locations

Scripts should be placed in the 'USERDATA/automation/jsr223' directory. For example,
in Linux installations created with a package installer,
the directory would be `/etc/openhab2/automation/jsr223`.
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/openhab2/automation/jsr223/`, and manual installations will use `/opt/openhab2/conf/automation/jsr223/`.

At system start time the scripts will be loaded in an order based on their name
and then top-down through the directory hierarchy.
Note that while scripts may be placed in subdirectories of `jsr223`,
they should not have the same names as scripts in other directories (this may be changed in the future).
For example, with the following directory structure...
When openHAB starts, scripts will be loaded in an order based on their file name and path.
For example, with the following scripts and directory structure...

```text
automation/jsr223
01/
script1.py
scriptx.py
00script.py
script2.py
├── automation/jsr223
│   ├── 00
│   │   ├── 00_00.py
│   │   └── 01_00.py
│   ├── 00.py
│   ├── 01
│   │   ├── 00_01.py
│   │   └── 01_01.py
│   └── 01.py
```

the load order will be: `00script.py`, `01/script1.py`, `script2.py`, `01/scriptx.py`.

<a name="trigger_types"></a>

### Trigger Types (all JSR223 languages)

The following trigger types are defined by openHAB (custom triggers can also be defined)
and take the specified configuration parameters.

| Trigger: `core.ItemCommandTrigger` |
|-----------------------------|
| `itemName` | The item name | TEXT |
| `command` | The command | TEXT |

| Trigger: `core.ItemStateUpdateTrigger` |
|-----------------------------|
| `itemName` | The item name | TEXT |
| `state` | The state | TEXT |

| Trigger: `core.ItemStateChangeTrigger` |
|-----------------------------|
| `itemName` | The item name | TEXT |
| `previousState` | The previous state | TEXT |
| `state` | The state | TEXT |

| Trigger: `timer.GenericCronTrigger` |
|-----------------------------|
| `cronExpression` | The cron expression | TEXT |

| Trigger: `timer.TimeOfDayTrigger` |
|-----------------------------|
| `time` | The time in "hh:mm" format | TEXT |

| Trigger: `core.GenericEventTrigger` |
|-----------------------------|
| `eventTopic` | default: "smarthome/*" (for channel events: "smarthome/channels/*/triggered") | TEXT |
| `eventSource` | item name, channel UID | TEXT |
| `eventTypes` | ItemCommandEvent, ItemStateEvent | TEXT |

### Additional Information

- [Scripted Rule Support](https://github.com/eclipse/smarthome/wiki/Scripted-Rule-Support) -
Early documentation on JSR223 usage in openHAB 2. Includes IDE setup instructions.
... the load order will be: `00.py`, `00/00_00.py`, `00/01_00.py`, `01.py`, `01/00_01.py`, `01/01_01.py`.

<a name="presets"></a>

### Predefined Script Variables (all JSR223 languages)
### `ScriptExtension` Objects (all JSR223 languages)

To faciliate JSR223 scripting, several openHAB-related variables are automatically predefined. These presets include:
To faciliate JSR223 scripting, several openHAB-related variables are automatically predefined within `ScriptExtension` presets.
They can be loaded into the script context using `scriptExtension.importPreset(String preset)`, e.g. `scriptExtension.importPreset("RuleSimple")`.
The Default preset is preloaded, so it does not require importing.

- [Default](#default_presets)
- [`Default`](#default_presets)
- [`RuleSimple`](#rulesimple_presets)
- [`RuleSupport`](#rulesupport_presets)
- [`RuleFactories`](#rulefactories_presets)

<a name="default_presets"></a>

#### Default Variables (no preset loading required)
#### Default Preset (`importPreset` not required)

| Variable | Description |
|---------|-------------|
Expand Down Expand Up @@ -161,29 +121,29 @@ To faciliate JSR223 scripting, several openHAB-related variables are automatical
| `itemRegistry` | Instance of `org.eclipse.smarthome.core.items.ItemRegistry` |
| `ir` | Alias for `itemRegistry` |
| `things` | Instance of `org.eclipse.smarthome.core.thing.ThingRegistry` |
| `events` | (internal) Used to send events, post commands, etc. [Details](#event_operations) below] |
| `rules` | Instance of `org.eclipse.smarthome.automation.RuleRegistry` |
| `scriptExtension` | (internal) For loading script presets. |
| `se` | Alias for `scriptExtension` |
| `events` | (internal) Used to send events, post commands, etc. [Details](#event_operations) below] |

<a name="#event_operations"></a>

##### `events` operations

- `postUpdate(String, String)`
- `postUpdate(Item, Number)`
- `postUpdate(Item, String)`
- `postUpdate(Item, State)`
- `sendCommand(String, String)`
- `sendCommand(Item, Number)`
- `sendCommand(Item, String)`
- `sendCommand(Item, Command)`
- `storeStates(Item...)`
- `restoreStates(Map<Item, State>)`
- `events.postUpdate(String, String)`
- `events.postUpdate(Item, Number)`
- `events.postUpdate(Item, String)`
- `events.postUpdate(Item, State)`
- `events.sendCommand(String, String)`
- `events.sendCommand(Item, Number)`
- `events.sendCommand(Item, String)`
- `events.sendCommand(Item, Command)`
- `events.storeStates(Item...)`
- `events.restoreStates(Map<Item, State>)`

<a name="rulesimple_presets"></a>

#### RuleSimple Extension/Preset
#### RuleSimple Preset

These variables are loaded using:

Expand All @@ -197,18 +157,18 @@ See language-specific documentation for examples.
| Variable | Description |
|----------|------|-------|
| SimpleRule | Base class for Jython Rules |
| SimpleActionHandler | `org.eclipse.smarthome.automation.module.script.rulesupport.shared.simple.SimpleActionHandler` |
| SimpleConditionHandler | `org.eclipse.smarthome.automation.module.script.rulesupport.shared.simple.SimpleConditionHandler` |
| SimpleTriggerHandler | `org.eclipse.smarthome.automation.module.script.rulesupport.shared.simple.SimpleTriggerHandler` |
| TriggerType | `org.eclipse.smarthome.automation.type.TriggerType` |
| SimpleActionHandler | `org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleActionHandler` |
| SimpleConditionHandler | `org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleConditionHandler` |
| SimpleTriggerHandler | `org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleTriggerHandler` |
| TriggerType | `org.openhab.core.automation.type.TriggerType` |
| ConfigDescriptionParameter | `org.eclipse.smarthome.config.core.ConfigDescriptionParameter` |
| ModuleType | `org.eclipse.smarthome.automation.type.ModuleType` |
| ActionType | `org.eclipse.smarthome.automation.type.ActionType` |
| Visibility | `org.eclipse.smarthome.automation.Visibility` enum |
| ModuleType | `org.openhab.core.automation.type.ModuleType` |
| ActionType | `org.openhab.core.automation.type.ActionType` |
| Visibility | `org.openhab.core.automation.Visibility` enum |

<a name="rulesupport_presets"></a>

#### RuleSupport Extension/Preset
#### `RuleSupport` Preset

These variables are loaded using:

Expand All @@ -220,14 +180,14 @@ scriptExtension.importPreset("RuleSupport")
|----------|-------------|
| automationManager | Instance for managing rules and other openHAB module instances. (e.g., `addRule`) |
| Configuration | `org.eclipse.smarthome.config.core.Configuration` |
| Action | `org.eclipse.smarthome.config.core.Action` |
| Condition | `org.eclipse.smarthome.config.core.Condition` |
| Trigger | `org.eclipse.smarthome.config.core.Trigger` |
| Rule | `org.eclipse.smarthome.config.core.Action.Rule` (use `SimpleRule` for defining rules) |
| Action | `org.openhab.core.automation.Action` |
| Condition | `org.openhab.core.automation.Condition` |
| Trigger | `org.openhab.core.automation.Trigger` |
| Rule | `org.openhab.core.automation.Rule` (use `SimpleRule` for defining rules) |

<a name="rulefactories_presets"></a>

#### RuleFactories Extension
#### `RuleFactories` Preset

> NOTE: Advanced usage
Expand All @@ -237,11 +197,88 @@ scriptExtension.importPreset("RuleFactories")

| Variable | Description |
|----------|-------------|
| `ActionHandlerFactory` | `org.eclipse.smarthome.automation.module.script.rulesupport.shared.factories.ActionHandlerFactory` |
| `ConditionHandlerFactory` | `org.eclipse.smarthome.automation.module.script.rulesupport.shared.factories.ConditionHandlerFactory` |
| `TriggerHandlerFactory` | `org.eclipse.smarthome.automation.module.script.rulesupport.shared.factories.TriggerHandlerFactory` |
| `TriggerType` | `org.eclipse.smarthome.automation.type.TriggerType` |
| `ActionHandlerFactory` | `org.openhab.core.automation.module.script.rulesupport.shared.factories.ActionHandlerFactory` |
| `ConditionHandlerFactory` | `org.openhab.core.automation.module.script.rulesupport.shared.factories.ConditionHandlerFactory` |
| `TriggerHandlerFactory` | `org.openhab.core.automation.module.script.rulesupport.shared.factories.TriggerHandlerFactory` |
| `TriggerType` | `org.openhab.core.automation.type.TriggerType` |
| `ConfigDescriptionParameter` | `org.eclipse.smarthome.config.core.ConfigDescriptionParameter` |
| `ModuleType` | `org.eclipse.smarthome.automation.type.ModuleType` |
| `ActionType` | `org.eclipse.smarthome.automation.type.ActionType` |
| `Visibility` | `org.eclipse.smarthome.automation.Visibility` enum |
| `ModuleType` | `org.openhab.core.automation.type.ModuleType` |
| `ActionType` | `org.openhab.core.automation.type.ActionType` |
| `Visibility` | `org.openhab.core.automation.Visibility` enum |


<a name="trigger_types"></a>

### `TriggerType` Objects (all JSR223 languages)

The following trigger types are defined by openHAB (custom triggers can also be defined) and take the specified configuration parameters.
All parameters are Strings.
Read the JSR223 language specific documentation for examples of using these `TriggerType` objects.

<details>
<summary>timer.GenericCronTrigger</summary>

| Parameter | Description |
|-----------|-------------|
| `cronExpression` | The cron expression |
</details>

<details>
<summary>timer.TimeOfDayTrigger</summary>

| Parameter | Description |
|-----------|-------------|
| `time` | The time in "hh:mm" format |
</details>

<details>
<summary>core.ItemCommandTrigger</summary>

| Parameter | Description |
|-----------|-------------|
| `itemName` | The name of the `Item` |
| `command` | The `Command` (optional) |
</details>

<details>
<summary>core.ItemStateUpdateTrigger</summary>

| Parameter | Description |
|-----------|-------------|
| `itemName` | The name of the `Item` |
| `state` | The `State` (optional) |
</details>

<details>
<summary>core.ItemStateChangeTrigger</summary>

| Parameter | Description |
|-----------|-------------|
| `itemName` | The name of the `Item` |
| `previousState` | The previous `State` (optional) |
| `state` | The `State` (optional) |
</details>

<details>
<summary>core.ChannelEventTrigger</summary>

| Parameter | Description |
|-----------|-------------|
| `channelUID` | The `ChannelUID` of the `Channel` |
| `event` | The `Channel` trigger `Event` (optional) |
</details>

<details>
<summary>core.GenericEventTrigger</summary>

| Parameter | Description |
|-----------|-------------|
| `eventTopic` | Default: "smarthome/\*"<br><br>Events can also be filtered, e.g.<br>Item events: "smarthome/items/\*/"<br>Channel events: "smarthome/channels/\*/triggered"<br>Thing events: "smarthome/things/\*/" |
| `eventSource` | `Item` name, `ChannelUID`, `ThingUID`, etc. |
| `eventTypes` | `ItemCommandEvent`, `ItemStateEvent`, `ItemStateChangedEvent`, `GroupItemStateChangedEvent`, `ItemAddedEvent`, `ItemRemovedEvent`, `ThingAddedEvent`, `ThingRemovedEvent`, `ThingStatusInfoChangedEvent`, `ThingStatusInfoEvent`, `ThingUpdatedEvent`, etc. |
</details>

### Additional Information

- [Scripted Rule Support](https://github.com/eclipse/smarthome/wiki/Scripted-Rule-Support) -
Early documentation on JSR223 usage in openHAB 2, including IDE setup instructions

0 comments on commit 8181b72

Please sign in to comment.