Documentation for JSR223 cache preset (#1937)

* Documentation for JSR223 cache preset

Signed-off-by: Jan N. Klug <github@klug.nrw>

* fix

Signed-off-by: Jan N. Klug <github@klug.nrw>

* fix

Signed-off-by: Jan N. Klug <github@klug.nrw>

* add Nashorn example

Signed-off-by: Jan N. Klug <github@klug.nrw>

* improvement

Signed-off-by: Jan N. Klug <github@klug.nrw>

* address review comment

Signed-off-by: Jan N. Klug <github@klug.nrw>

* Update configuration/jsr223.md

Co-authored-by: Wouter Born <github@maindrain.net>

* add ruby

Signed-off-by: Jan N. Klug <github@klug.nrw>

Signed-off-by: Jan N. Klug <github@klug.nrw>
Co-authored-by: Wouter Born <github@maindrain.net>

configuration/jsr223.md

@@ -366,6 +366,78 @@ scriptExtension.importPreset("RuleFactories")
 | `ConditionHandlerFactory` | `org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedConditionHandlerFactory` |
 | `TriggerHandlerFactory`   | `org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedTriggerHandlerFactory`   |
 
+#### `cache` Preset
+
+The `cache` preset does not provide a default import and needs to be imported explicitly.
+
+:::: tabs
+
+::: tab Groovy
+
+```groovy
+scriptExtension.importPreset("cache")
+
+sharedCache.put("x", "y")
+```
+
+:::
+
+::: tab Nashorn JS
+
+```js
+scriptExtension.importPreset("cache")
+
+var valueX = sharedCache.get("x")
+```
+
+:::
+
+::: tab JSScripting
+
+```js
+var { sharedCache, privateCache } = require('@runtime/cache')
+
+sharedCache.remove("x")
+```
+
+:::
+
+::: tab Jython
+
+```python
+scriptExtension.importPreset("cache")
+```
+
+:::
+
+::: tab JRuby
+
+```ruby
+# the preset is imported automatically by the helper library.
+value_x = shared_cache[:x]
+shared_cache.delete(:x)
+shared_cache[:x] = "y"
+```
+
+:::
+
+::::
+
+It provides two different caches:
+
+- `sharedCache`: This cache is shared over all languages and all scripts (file-based and UI). Usage of entries is tracked and entries will be removed if the last script that ever accessed an entry is removed.
+- `privateCache`: This cache is private to a script engine, usually that means it is private to a script or rule, depending on the implementation of the scripting language.
+It is cleared when the script engine is unloaded (i.e. usually when the script is unloaded).
+
+In both cases values that are either a `ScheduledFuture<?>` or a `Timer` are cancelled by calling `.cancel()` on the object if the object is removed automatically.
+
+Both caches implement the `ValueCache` interface and therefore can be accessed by
+
+- `Object put(String key, Object value)`: Put a key/value pair to the cache. Returns old value if already set, otherwise `null`.
+- `Object remove(String key)`: Remove the key/value pair from the cache. Returns old value if already set, otherwise `null`.
+- `Object get(String key)`: Get the value for the given key from the cache. Non-existent keys return `null`.
+- `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`.
+
 ### `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.