Remove deprecated methods & properties (#332)

- [rules] Remove deprecated `state` and `receivedTrigger` event object properties.
- [cache] Remove deprecated default cache (users should either use private or shared cache).
- [actions] Remove `createTimerWithArgument` (users should use `createTimer` or `setTimeout` instead,
  `createTimerWithArgument` is not even thread-safe).

All these have been marked as deprecated at least since openHAB 3.4,
which was released end of 2022, which means users have had enough time
to adjust their code.

---------

Signed-off-by: Florian Hotze <[email protected]>

README.md

@@ -63,7 +63,7 @@ openHAB also provides the [JavaScript Scripting (Nashorn) add-on](https://next.o
 ### Custom Installation
 
 <!-- TODO: Update link to stable when openHAB 4.0 is released -->
-If you want to install the openHAB JavaScript library manually, you need to disable the caching of the internal library in the [add-on's settings](https://next.openhab.org/addons/automation/jsscripting/#configuration).
+If you want to install the openHAB JavaScript library manually, you need to disable the caching of the internal library in the [add-on settings](https://next.openhab.org/addons/automation/jsscripting/#configuration).
 
 On openHABian:
 
@@ -622,7 +622,8 @@ These include several methods to convert between color types like HSB, RGB, sRGB
 
 See [openhab-js : actions.Ephemeris](https://openhab.github.io/openhab-js/actions.html#.Ephemeris) for complete documentation.
 
-Ephemeris is a way to determine what type of day today or a number of days before or after today is. For example, a way to determine if today is a weekend, a bank holiday, someone’s birthday, trash day, etc.
+Ephemeris is a way to determine what type of day today or a number of days before or after today is.
+For example, a way to determine if today is a weekend, a public holiday, someone’s birthday, trash day, etc.
 
 Additional information can be found on the  [Ephemeris Actions Docs](https://www.openhab.org/docs/configuration/actions.html#ephemeris) as well as the [Ephemeris JavaDoc](https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/ephemeris).
 
@@ -771,7 +772,7 @@ When a script is unloaded and its cache is cleared, all timers (see [`createTime
 
 The shared cache is shared across all rules and scripts, it can therefore be accessed from any automation language.
 The access to every key is tracked and the key is removed when all scripts that ever accessed that key are unloaded.
-If that key stored a timer, the timer is cancelled.
+If that key stored a timer, the timer will be cancelled.
 
 See [openhab-js : cache](https://openhab.github.io/openhab-js/cache.html) for full API documentation.
 
@@ -835,10 +836,10 @@ See [JS-Joda](https://js-joda.github.io/js-joda/) for more examples and complete
 Occasionally, one will need to parse a non-supported date time string or generate one from a ZonedDateTime.
 To do this you will use [JS-Joda DateTimeFormatter and potentially your Locale](https://js-joda.github.io/js-joda/manual/formatting.html).
 However, shipping all the locales with the openhab-js library would lead to an unacceptable large size.
-Therefore if you attempt to use the `DateTimeFormatter` and receive an error saying it cannot find your locale, you will need to manually install your locale and import it into your rule.
+Therefore, if you attempt to use the `DateTimeFormatter` and receive an error saying it cannot find your locale, you will need to manually install your locale and import it into your rule.
 
 [JS-Joda Locales](https://github.com/js-joda/js-joda/tree/master/packages/locale#use-prebuilt-locale-packages) includes a list of all the supported locales.
-Each loacle consists of a two letter language indicator followed by a "-" and a two letter dialect indicator: e.g. "EN-US".
+Each locale consists of a two letter language indicator followed by a "-" and a two letter dialect indicator: e.g. "EN-US".
 Installing a locale can be done through the command `npm install @js-joda/locale_de-de` from the *$OPENHAB_CONF/automation/js* folder.
 
 To import and use a local into your rule you need to require it and create a `DateTimeFormatter` that uses it:
@@ -995,7 +996,7 @@ The argument `value` can be a Quantity-compatible `Item`, a string, a `Quantity`
 `value` strings have the `$amount $unit` format and must follow these rules:
 
 - `$amount` is required with a number provided as string
-- `$unit` is optional (unitless quantities are possible) and can have a prefix like `m` (milli) or `M` (mega)
+- `$unit` is optional (unit-less quantities are possible) and can have a prefix like `m` (milli) or `M` (mega)
 - `$unit` does not allow whitespaces.
 - `$unit` does allow superscript, e.g. `²` instead of `^2`.
 - `$unit` requires the `*` between two units to be present, although you usually omit it (which is mathematically seen allowed, but openHAB needs the `*`).

src/actions.js

@@ -271,26 +271,6 @@ class ScriptExecution {
       return ThreadsafeTimers.createTimer(identifier, callbackFn); // eslint-disable-line no-undef
     }
   }
-
-  /**
-   * Schedules a function (with argument) for later execution
-   *
-   * @deprecated
-   * @param {string} identifier an optional identifier, e.g. used for logging
-   * @param {time.ZonedDateTime} instant the point in time when the code should be executed
-   * @param {*} arg1 the argument to pass to the code block
-   * @param {function} closure the code block to execute
-   * @returns {*} a native openHAB Timer
-   */
-  static createTimerWithArgument (identifier, instant, arg1, closure) {
-    console.warn('"createTimerWithArgument" has been deprecated and will be removed in a future release. Use "createTimer" or "setTimeout" instead.');
-    // Support method overloading as identifier is optional
-    if (typeof identifier === 'string' && closure != null) {
-      return JavaScriptExecution.createTimerWithArgument(identifier, instant, arg1, closure);
-    } else {
-      return JavaScriptExecution.createTimerWithArgument(identifier, instant, arg1);
-    }
-  }
 }
 
 /**

src/cache.js

@@ -4,28 +4,18 @@
  * @namespace cache
  */
 
-const log = require('./log')('cache');
-const { privateCache, sharedCache } = require('@runtime/cache'); // The new cache from core
-const addonSharedCache = require('@runtime').sharedcache; // The old cache from the adddon
-
-const coreCacheAvail = Java.isJavaObject(privateCache) && Java.isJavaObject(sharedCache);
-
-function logDeprecationWarning (funcName) {
-  console.warn(`"cache.${funcName}" has been deprecated and will be removed in a future release. Use "cache.private.${funcName}" or "cache.shared.${funcName}" instead. Visit the JavaScript Scripting Automation addon docs for more information about the cache.`);
-}
+const { privateCache, sharedCache } = require('@runtime/cache');
 
 /**
  * The {@link JSCache} can be used by to share information between subsequent runs of the same script or between scripts (depending on implementation).
  */
 class JSCache {
   /**
    * @param {*} valueCacheImpl an implementation of the Java {@link https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.automation.module.script.rulesupport/src/main/java/org/openhab/core/automation/module/script/rulesupport/shared/ValueCache.java ValueCache} interface
-   * @param {boolean} [deprecated]
    * @hideconstructor
    */
-  constructor (valueCacheImpl, deprecated = false) {
+  constructor (valueCacheImpl) {
     this._valueCache = valueCacheImpl;
-    this._deprecated = deprecated;
   }
 
   /**
@@ -36,7 +26,6 @@ class JSCache {
    * @returns {*|null} the current object for the supplied key, a default value if defaultSupplier is provided, or null
    */
   get (key, defaultSupplier) {
-    if (this._deprecated === true) logDeprecationWarning('get');
     if (typeof defaultSupplier === 'function') {
       return this._valueCache.get(key, defaultSupplier);
     } else {
@@ -52,7 +41,6 @@ class JSCache {
    * @returns {*|null} the previous value associated with the key, or null if there was no mapping for key
    */
   put (key, value) {
-    if (this._deprecated === true) logDeprecationWarning('put');
     return this._valueCache.put(key, value);
   }
 
@@ -63,7 +51,6 @@ class JSCache {
    * @returns {*|null} the previous value associated with the key or null if there was no mapping for key
    */
   remove (key) {
-    if (this._deprecated === true) logDeprecationWarning('remove');
     return this._valueCache.remove(key);
   }
 
@@ -74,29 +61,11 @@ class JSCache {
    * @returns {boolean} whether the key has a mapping
    */
   exists (key) {
-    if (this._deprecated === true) logDeprecationWarning('exists');
     return this._valueCache.get(key) !== null;
   }
 }
 
-let addonSharedJSCache;
-if (coreCacheAvail === true) {
-  log.debug('Caches from core are available, enable legacy cache methods to keep the old API.');
-  addonSharedJSCache = new JSCache(sharedCache, true);
-} else {
-  log.debug('Caches from core are unavailable, using the addon-provided cache.');
-  addonSharedJSCache = new JSCache(addonSharedCache);
-}
-
 module.exports = {
-  /** @deprecated */
-  get: (key, defaultSupplier) => { return addonSharedJSCache.get(key, defaultSupplier); },
-  /** @deprecated */
-  put: (key, value) => { return addonSharedJSCache.put(key, value); },
-  /** @deprecated */
-  remove: (key) => { return addonSharedJSCache.remove(key); },
-  /** @deprecated */
-  exists: (key) => { return addonSharedJSCache.exists(key); },
   /**
    * Shared cache that is shared across all rules and scripts, it can therefore be accessed from any automation language.
    * The access to every key is tracked and the key is removed when all scripts that ever accessed that key are unloaded.
@@ -105,7 +74,7 @@ module.exports = {
    * @memberof cache
    * @type JSCache
    */
-  shared: (coreCacheAvail === true) ? new JSCache(sharedCache) : undefined,
+  shared: new JSCache(sharedCache),
   /**
    * Private cache for each script.
    * The private cache can only be accessed by the same script and is cleared when the script is unloaded.
@@ -115,6 +84,6 @@ module.exports = {
    * @memberof cache
    * @type JSCache
    */
-  private: (coreCacheAvail === true) ? new JSCache(privateCache) : undefined,
-  JSCache
+  private: new JSCache(privateCache),
+  JSCache // export class for unit tests
 };

src/rules/rules.js

@@ -428,16 +428,6 @@ function _getTriggeredData (input) {
         data.itemName = event.getItemName();
         data.eventType = 'update';
         data.triggerType = 'ItemStateUpdateTrigger';
-        Object.defineProperty(
-          data,
-          'state',
-          {
-            get: function () {
-              console.warn('"state" has been deprecated and will be removed in a future release. Please use "receivedState" instead.');
-              return input.get('state').toString();
-            }
-          }
-        );
         break;
       case 'org.openhab.core.thing.events.ThingStatusInfoChangedEvent':
         data.thingUID = event.getThingUID().toString();
@@ -454,16 +444,6 @@ function _getTriggeredData (input) {
         data.receivedEvent = event.getEvent();
         data.eventType = 'triggered';
         data.triggerType = 'ChannelEventTrigger';
-        Object.defineProperty(
-          data,
-          'receivedTrigger',
-          {
-            get: function () {
-              console.warn('"receivedTrigger" has been deprecated and will be removed in a future release. Please use "receivedEvent" instead.');
-              return event.getEvent();
-            }
-          }
-        );
         break;
     }
   }

test/cache.spec.js

@@ -86,14 +86,5 @@ describe('cache.js', () => {
         expect(console.warn).not.toHaveBeenCalled();
       });
     });
-
-    it('logs a warning if the deprecated option is set.', () => {
-      cache._deprecated = true;
-      cache.exists(key);
-      cache.get(key);
-      cache.put(key, value);
-      cache.remove(key);
-      expect(console.warn).toBeCalledTimes(4);
-    });
   });
 });

types/actions.d.ts

@@ -201,17 +201,6 @@ export class ScriptExecution {
      * @returns {*} a native openHAB Timer
      */
     static createTimer(identifier: string, zdt: time.ZonedDateTime, functionRef: Function, ...params: any[]): any;
-    /**
-     * Schedules a function (with argument) for later execution
-     *
-     * @deprecated
-     * @param {string} identifier an optional identifier, e.g. used for logging
-     * @param {time.ZonedDateTime} instant the point in time when the code should be executed
-     * @param {*} arg1 the argument to pass to the code block
-     * @param {function} closure the code block to execute
-     * @returns {*} a native openHAB Timer
-     */
-    static createTimerWithArgument(identifier: string, instant: time.ZonedDateTime, arg1: any, closure: Function): any;
 }
 /**
  * {@link https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/Semantics.html Semantics} Actions

types/cache.d.ts

@@ -4,12 +4,10 @@
 export class JSCache {
     /**
      * @param {*} valueCacheImpl an implementation of the Java {@link https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.automation.module.script.rulesupport/src/main/java/org/openhab/core/automation/module/script/rulesupport/shared/ValueCache.java ValueCache} interface
-     * @param {boolean} [deprecated]
      * @hideconstructor
      */
-    constructor(valueCacheImpl: any, deprecated?: boolean);
+    constructor(valueCacheImpl: any);
     _valueCache: any;
-    _deprecated: boolean;
     /**
      * Returns the value to which the specified key is mapped.
      *
@@ -41,10 +39,6 @@ export class JSCache {
      */
     exists(key: string): boolean;
 }
-export declare function get(key: any, defaultSupplier: any): any;
-export declare function put(key: any, value: any): any;
-export declare function remove(key: any): any;
-export declare function exists(key: any): any;
 export declare const shared: JSCache;
 declare const _private: JSCache;
 export { _private as private };