From 8fb03da0954c6e97ffd9d655a36716d0aab14004 Mon Sep 17 00:00:00 2001 From: Florian Hotze Date: Mon, 16 Sep 2024 12:28:46 +0200 Subject: [PATCH] [jsscripting] Upgrade to openhab-js 5.6.0 (#17424) Also sync webpack dependency with openhab-js package.json. * [jsscripting] README changes from ohjs upgrade Signed-off-by: Florian Hotze --- .../README.md | 83 +++++-------------- .../pom.xml | 4 +- 2 files changed, 22 insertions(+), 65 deletions(-) diff --git a/bundles/org.openhab.automation.jsscripting/README.md b/bundles/org.openhab.automation.jsscripting/README.md index fa2b5f1418b..4af31d367b6 100644 --- a/bundles/org.openhab.automation.jsscripting/README.md +++ b/bundles/org.openhab.automation.jsscripting/README.md @@ -472,6 +472,9 @@ Calling `Item.persistence` returns an `ItemPersistence` object with the followin - .minimumSince(timestamp, serviceId) ⇒ `PersistedItem | null` - .minimumUntil(timestamp, serviceId) ⇒ `PersistedItem | null` - .minimumBetween(begin, end, serviceId) ⇒ `PersistedItem | null` + - .medianSince(timestamp, serviceId) ⇒ `PersistedState | null` + - .medianUntil(timestamp, serviceId) ⇒ `PersistedState | null` + - .medianBetween(begin, end, serviceId) ⇒ `PersistedState | null` - .persist(serviceId): Tells the persistence service to store the current Item state, which is then done asynchronously. **Warning:** This has the side effect, that if the Item state changes shortly after `.persist` has been called, the new Item state will be persisted. See [JSDoc](https://openhab.github.io/openhab-js/items.ItemPersistence.html#persist) for a possible work-around. - .persist(timestamp, state, serviceId): Tells the persistence service to store the given state at the given timestamp, which is then done asynchronously. @@ -749,11 +752,13 @@ There are three different types of notifications: In addition to that, notifications can be updated later be re-using the same `referenceId` and hidden/removed either by `referenceId` or `tag`. To send these three types of notifications, use the `notificationBuilder(message)` method of the `actions` namespace. +`message` is optional and may be omitted. It returns a new `NotificationBuilder` object, which by default sends a broadcast notification and provides the following methods: - `.logOnly()`: Send a log notification only. -- `.hide()`: Hides notifications with the specified `referenceId` or `tag`. +- `.hide()`: Hides notification(s) with the specified `referenceId` or `tag` (`referenceId` has precedence over `tag`). - `.addUserId(emailAddress)`: By adding the email address(es) of specific openHAB Cloud user(s), the notification is only sent to this (these) user(s). + To add multiple users, either call `addUserId` multiple times or pass mutiple emails as multiple params, e.g. `addUserId(emailAddress1, emailAddress2)`. - `.withIcon(icon)`: Sets the icon of the notification. - `.withTag(tag)`: Sets the tag of the notification. Used for grouping notifications and to hide/remove groups of notifications. - `.withTitle(title)`: Sets the title of the notification. @@ -1224,7 +1229,7 @@ Operations and conditions can also optionally take functions: ```javascript rules.when().item("F1_light").changed().then(event => { - console.log(event); + console.log(event); }).build("Test Rule", "My Test Rule"); ``` @@ -1288,6 +1293,8 @@ Additionally, all the above triggers have the following functions: - `if(optionalFunction)` - `.stateOfItem(itemName)` - `is(state)` + - `isOn()` + - `isOff()` - `in(state...)` #### Rule Builder Operations @@ -1368,6 +1375,8 @@ This table gives an overview over the `event` object: | `thingUID` | `Thing****Trigger` | UID of Thing that triggered event | N/A | | `cronExpression` | `GenericCronTrigger` | Cron expression of the trigger | N/A | | `time` | `TimeOfDayTrigger` | Time of day value of the trigger | N/A | +| `timeOnly` | `DateTimeTrigger` | Whether the trigger only considers the time part of the DateTime Item | N/A | +| `offset` | `DateTimeTrigger` | Offset in seconds added to the time of the DateTime Item | N/A | | `eventType` | all except `PWMTrigger`, `PIDTrigger` | Type of event that triggered event (change, command, triggered, update, time) | N/A | | `triggerType` | all except `PWMTrigger`, `PIDTrigger` | Type of trigger that triggered event | N/A | | `eventClass` | all | Java class name of the triggering event | N/A | @@ -1438,76 +1447,24 @@ If you want to get some advanced information, you can read [this blog post](http ### @runtime -One can access many useful utilities and types using `require("@runtime")`, e.g. +In most cases, the [Standard Library](#standard-library) provides pure-JS APIs to interact with the openHAB runtime. +Generally speaking, you should therefore prefer to use [Standard Library](#standard-library) provided by this library instead. + +However, in some cases, e.g. when needing a [`HSBType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/hsbtype), one needs to access raw Java utilities and types. +This can be achieved by using `require('@runtime')`, e.g. ```javascript -var { ON, OFF, QuantityType } = require("@runtime"); +var { ON, OFF, QuantityType } = require('@runtime'); // Alternative, more verbose way to achieve the same: // -// var runtime = require("@runtime"); +// var runtime = require('@runtime'); // // var ON = runtime.ON; // var OFF = runtime.OFF; // var QuantityType = runtime.QuantityType; ``` -| Variable | Description | -|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| -| `State` | [`org.openhab.core.types.State`](https://www.openhab.org/javadoc/latest/org/openhab/core/types/state) | -| `Command` | [`org.openhab.core.types.Command`](https://www.openhab.org/javadoc/latest/org/openhab/core/types/command) | -| `URLEncoder` | [`java.net.URLEncoder`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/net/URLEncoder.html) | -| `File` | [`java.io.File`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/io/File.html) | -| `Files` | [`java.nio.file.Files`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/nio/file/Files.html) | -| `Path` | [`java.nio.file.Path`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/nio/file/Path.html) | -| `Paths` | [`java.nio.file.Paths`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/nio/file/Paths.html) | -| `IncreaseDecreaseType` | [`org.openhab.core.library.types.IncreaseDecreaseType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/increasedecreasetype) | -| `DECREASE` | `IncreaseDecreaseType` enum item | -| `INCREASE` | `IncreaseDecreaseType` enum item | -| `OnOffType` | [`org.openhab.core.library.types.OnOffType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/onofftype) | -| `ON` | `OnOffType` enum item | -| `OFF` | `OnOffType` enum item | -| `OpenClosedType` | [`org.openhab.core.library.types.OpenClosedType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/openclosedtype) | -| `OPEN` | `OpenClosedType` enum item | -| `CLOSED` | `OpenClosedType` enum item | -| `StopMoveType` | [`org.openhab.core.library.types.StopMoveType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/stopmovetype) | -| `STOP` | `StopMoveType` enum item | -| `MOVE` | `StopMoveType` enum item | -| `UpDownType` | [`org.openhab.core.library.types.UpDownType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/updowntype) | -| `UP` | `UpDownType` enum item | -| `DOWN` | `UpDownType` enum item | -| `UnDefType` | [`org.openhab.core.library.types.UnDefType`](https://www.openhab.org/javadoc/latest/org/openhab/core/types/undeftype) | -| `NULL` | `UnDefType` enum item | -| `UNDEF` | `UnDefType` enum item | -| `RefreshType` | [`org.openhab.core.library.types.RefreshType`](https://www.openhab.org/javadoc/latest/org/openhab/core/types/refreshtype) | -| `REFRESH` | `RefreshType` enum item | -| `NextPreviousType` | [`org.openhab.core.library.types.NextPreviusType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/nextprevioustype) | -| `NEXT` | `NextPreviousType` enum item | -| `PREVIOUS` | `NextPreviousType` enum item | -| `PlayPauseType` | [`org.openhab.core.library.types.PlayPauseType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/playpausetype) | -| `PLAY` | `PlayPauseType` enum item | -| `PAUSE` | `PlayPauseType` enum item | -| `RewindFastforwardType` | [`org.openhab.core.library.types.RewindFastforwardType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/rewindfastforwardtype) | -| `REWIND` | `RewindFastforwardType` enum item | -| `FASTFORWARD` | `RewindFastforwardType` enum item | -| `QuantityType` | [`org.openhab.core.library.types.QuantityType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/quantitytype) | -| `StringListType` | [`org.openhab.core.library.types.StringListType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/stringlisttype) | -| `RawType` | [`org.openhab.core.library.types.RawType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/rawtype) | -| `DateTimeType` | [`org.openhab.core.library.types.DateTimeType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/datetimetype) | -| `DecimalType` | [`org.openhab.core.library.types.DecimalType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/decimaltype) | -| `HSBType` | [`org.openhab.core.library.types.HSBType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/hsbtype) | -| `PercentType` | [`org.openhab.core.library.types.PercentType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/percenttype) | -| `PointType` | [`org.openhab.core.library.types.PointType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/pointtype) | -| `StringType` | [`org.openhab.core.library.types.StringType`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/types/stringtype) | -| `SIUnits` | [`org.openhab.core.library.unit.SIUnits`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/unit/siunits) | -| `ImperialUnits` | [`org.openhab.core.library.unit.ImperialUnits`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/unit/imperialunits) | -| `MetricPrefix` | [`org.openhab.core.library.unit.MetricPrefix`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/unit/metricprefix) | -| `Units` | [`org.openhab.core.library.unit.Units`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/unit/units) | -| `BinaryPrefix` | [`org.openhab.core.library.unit.BinaryPrefix`](https://www.openhab.org/javadoc/latest/org/openhab/core/library/unit/binaryprefix) | -| `ChronoUnit` | [`java.time.temporal.ChronoUnit`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/temporal/ChronoUnit.html) | -| `Duration` | [`java.time.Duration`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html) | -| `ZoneId` | [`java.time.ZoneId`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/ZoneId.html) | -| `ZonedDateTime` | [`java.time.ZonedDateTime`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/ZonedDateTime.html) | +A list of available utilities and types can be found in the [JSR223 Default Preset documentation](https://www.openhab.org/docs/configuration/jsr223.html#default-preset-importpreset-not-required). -`require("@runtime")` also defines "services" such as `items`, `things`, `rules`, `events`, `actions`, `ir`, `itemRegistry`. +`require('@runtime')` also defines "services" such as `items`, `things`, `rules`, `events`, `actions`, `ir`, `itemRegistry`. You can use these services for backwards compatibility purposes or ease migration from JSR223 scripts. -Generally speaking, you should prefer to use [Standard Library](#standard-library) provided by this library instead. diff --git a/bundles/org.openhab.automation.jsscripting/pom.xml b/bundles/org.openhab.automation.jsscripting/pom.xml index e172d4fa634..a571b84c0e2 100644 --- a/bundles/org.openhab.automation.jsscripting/pom.xml +++ b/bundles/org.openhab.automation.jsscripting/pom.xml @@ -24,7 +24,7 @@ 22.0.0.2 ${project.version} - openhab@5.5.0 + openhab@5.6.0 @@ -69,7 +69,7 @@ - install ${ohjs.version} webpack@^5.87.0 webpack-cli@^5.1.4 + install ${ohjs.version} webpack@^5.94.0 webpack-cli@^5.1.4