Skip to content

Commit

Permalink
Merge pull request openhab#9 from jimtng/jruby-configurations
Browse files Browse the repository at this point in the history 
[jrubyscripting] Add ConfigurableService
  • Loading branch information
@boc-tothefuture
boc-tothefuture authored Nov 13, 2021
2 parents 01f33a8 + 1624409 commit 5de8cf1
Show file tree
Hide file tree
Showing 7 changed files with 92 additions and 23 deletions.
32 changes: 15 additions & 17 deletions bundles/org.openhab.automation.jrubyscripting/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,38 +1,38 @@
# JRuby Scripting
# JRuby Scripting

This add-on provides [JRuby](https://www.jruby.org/) 9.3.1 that can be used as a scripting language within automation rules.

## JRuby Scripting Configuration

JRuby configuration parameters may be set by creating a jruby.cfg file in $OPENHAB_CONF/services/
After installing this add-on, you will find configuration options in the openHAB portal under _Settings -> Other Services -> JRuby Scripting_.

Alternatively, JRuby configuration parameters may be set by creating a `jruby.cfg` file in `conf/services/`

| Parameter | Default | Description |
|-------------------------------------------------------|-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| org.openhab.automation.jrubyscripting:gem_home | $OPENHAB_CONF/scripts/lib/ruby/gem_home | Location ruby gems will be installed and loaded, directory will be created if missing and gem installs are specified from |
| org.openhab.automation.jrubyscripting:rubylib | $OPENHAB_CONF/automation/lib/ruby/ | Search path for user libraries |
| org.openhab.automation.jrubyscripting:local_context | threadsafe | The local context holds Ruby runtime, name-value pairs for sharing variables between Java and Ruby. See [this](https://github.com/jruby/jruby/wiki/RedBridge#Context_Instance_Type) for options and details |
| org.openhab.automation.jrubyscripting:local_variables | transient | Defines how variables are shared between Ruby and Java. See [this](https://github.com/jruby/jruby/wiki/RedBridge#local-variable-behavior-options) for options and details |
| org.openhab.automation.jrubyscripting:gems | | Comma separated list of [Ruby Gems](https://rubygems.org/) to install. |

| Parameter | Default | Description |
| --------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| gem_home | $OPENHAB_CONF/scripts/lib/ruby/gem_home | Location ruby gems will be installed and loaded, directory will be created if missing and gem installs are specified |
| rubylib | $OPENHAB_CONF/automation/lib/ruby/ | Search path for user libraries. Separate each path with a colon (semicolon in Windows). |
| local_context | singlethread | The local context holds Ruby runtime, name-value pairs for sharing variables between Java and Ruby. See [this](https://github.com/jruby/jruby/wiki/RedBridge#Context_Instance_Type) for options and details |
| local_variables | transient | Defines how variables are shared between Ruby and Java. See [this](https://github.com/jruby/jruby/wiki/RedBridge#local-variable-behavior-options) for options and details |
| gems | | Comma separated list of [Ruby Gems](https://rubygems.org/) to install. |

## Ruby Gems

This automation add-on will install user specified gems and make them available on the library search path.
Gem versions may be specified using the standard ruby gem_name=version format.
The version number follows the [pessimistic version constraint](https://guides.rubygems.org/patterns/#pessimistic-version-constraint) syntax.
The version number follows the [pessimistic version constraint](https://guides.rubygems.org/patterns/#pessimistic-version-constraint) syntax.

For example this configuration will install version 4 or higher of the [openHAB JRuby Scripting Library](https://boc-tothefuture.github.io/openhab-jruby/).

```text
org.openhab.automation.jrubyscripting:gems=openhab-scripting=~>4.0
gems=openhab-scripting=~>4.0
```

## Creating JRuby Scripts

When this add-on is installed, you can select JRuby as a scripting language when creating a script action within the rule editor of the UI.

Alternatively, you can create scripts in the `automation/jsr223` configuration directory.
Alternatively, you can create scripts in the `automation/jsr223/ruby/personal` configuration directory.
If you create an empty file called `test.rb`, you will see a log line with information similar to:

```text
Expand All @@ -51,9 +51,8 @@ log:set DEBUG org.openhab.automation.jrubyscripting

All [ScriptExtensions]({{base}}/configuration/jsr223.html#scriptextension-objects-all-jsr223-languages) are available in JRuby with the following exceptions/modifications:

* The File variable, referencing java.io.File is not available as it conflicts with Ruby's File class preventing Ruby from initializing
* Globals scriptExtension, automationManager, ruleRegistry, items, voice, rules, things, events, itemRegistry, ir, actions, se, audio, lifecycleTracker are prepended with a $ (e.g. $automationManager) making them available as a global objects in Ruby.

- The File variable, referencing java.io.File is not available as it conflicts with Ruby's File class preventing Ruby from initializing
- Globals scriptExtension, automationManager, ruleRegistry, items, voice, rules, things, events, itemRegistry, ir, actions, se, audio, lifecycleTracker are prepended with a $ (e.g. $automationManager) making them available as a global objects in Ruby.

## Script Examples

Expand All @@ -71,4 +70,3 @@ LoggerFactory.getLogger("org.openhab.core.automation.examples").info("Hello worl

JRuby can [import Java classes](https://github.com/jruby/jruby/wiki/CallingJavaFromJRuby).
Depending on the openHAB logging configuration, you may need to prefix logger names with `org.openhab.core.automation` for them to show up in the log file (or you modify the logging configuration).

6 changes: 1 addition & 5 deletions bundles/org.openhab.automation.jrubyscripting/pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,7 @@
<name>openHAB Add-ons :: Automation :: JRuby Scripting</name>

<properties>
<bnd.importpackage>
com.ibm.icu.*;resolution:=optional,
org.abego.treelayout.*;resolution:=optional,
org.apache.ivy.*;resolution:=optional,
org.stringtemplate.v4.*;resolution:=optional</bnd.importpackage>
<bnd.importpackage>com.sun.nio.*;resolution:=optional,com.sun.security.*;resolution:=optional,org.apache.tools.ant.*;resolution:=optional,org.bouncycastle.*;resolution:=optional,org.joda.*;resolution:=optional,sun.management.*;resolution:=optional,sun.nio.*;resolution:=optional</bnd.importpackage>
<jruby.version>9.3.1.0</jruby.version>
</properties>

Expand Down
1 change: 1 addition & 0 deletions bundles/org.openhab.automation.jrubyscripting/src/main/feature/feature.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,6 @@
<feature name="openhab-automation-jrubyscripting" description="JRuby Scripting" version="${project.version}">
<feature>openhab-runtime-base</feature>
<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.automation.jrubyscripting/${project.version}</bundle>
<configfile finalname="${openhab.conf}/services/jruby.cfg" override="false">mvn:org.openhab.addons.features.karaf/org.openhab.addons.features.karaf.openhab-addons-external/${project.version}/cfg/jruby</configfile>
</feature>
</features>
2 changes: 1 addition & 1 deletion ...ernal/JRubyScriptEngineConfiguration.java → ...ernal/JRubyScriptEngineConfiguration.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ public class JRubyScriptEngineConfiguration {
private final static Map<String, OptionalConfigurationElement> CONFIGURATION_PARAMETERS = Map.ofEntries(
Map.entry("local_context",
new OptionalConfigurationElement.Builder(OptionalConfigurationElement.Type.SYSTEM_PROPERTY)
.mappedTo("org.jruby.embed.localcontext.scope").defaultValue("threadsafe").build()),
.mappedTo("org.jruby.embed.localcontext.scope").defaultValue("singlethread").build()),

Map.entry("local_variable",
new OptionalConfigurationElement.Builder(OptionalConfigurationElement.Type.SYSTEM_PROPERTY)
Expand Down
4 changes: 4 additions & 0 deletions ...ng/internal/JRubyScriptEngineFactory.java → ...ng/internal/JRubyScriptEngineFactory.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
import org.eclipse.jdt.annotation.Nullable;
import org.openhab.core.automation.module.script.AbstractScriptEngineFactory;
import org.openhab.core.automation.module.script.ScriptEngineFactory;
import org.openhab.core.config.core.ConfigurableService;
import org.osgi.service.component.ComponentContext;
import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;
Expand All @@ -36,10 +37,13 @@
*/
@NonNullByDefault
@Component(service = ScriptEngineFactory.class, configurationPid = "org.openhab.automation.jrubyscripting")
@ConfigurableService(category = "automation", label = "JRuby Scripting", description_uri = JRubyScriptEngineFactory.CONFIG_URI)
public class JRubyScriptEngineFactory extends AbstractScriptEngineFactory {

private final JRubyScriptEngineConfiguration configuration = new JRubyScriptEngineConfiguration();

protected static final String CONFIG_URI = "automation:jruby";

// Filter out the File entry to prevent shadowing the Ruby File class which breaks Ruby in spectacularly
// difficult ways to debug.
private final static Set<String> FILTERED_PRESETS = Set.of("File");
Expand Down
0 ...jrubyscripting/internal/package-info.java → ...jrubyscripting/internal/package-info.java
View file
File renamed without changes.
70 changes: 70 additions & 0 deletions bundles/org.openhab.automation.jrubyscripting/src/main/resources/OH-INF/config/config.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
<?xml version="1.0" encoding="UTF-8"?>
<config-description:config-descriptions
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:config-description="https://openhab.org/schemas/config-description/v1.0.0"
xsi:schemaLocation="https://openhab.org/schemas/config-description/v1.0.0
https://openhab.org/schemas/config-description-1.0.0.xsd">
<config-description uri="automation:jruby">

<parameter-group name="system">
<label>System Properties</label>
<description>This group defines JRuby system properties.</description>
<advanced>true</advanced>
</parameter-group>

<parameter-group name="environment">
<label>Ruby Environment</label>
<description>This group defines Ruby's environment.</description>
<advanced>false</advanced>
</parameter-group>

<parameter-group name="gems">
<label>Gems</label>
<description>This group defines the list of GEMS to install.</description>
<advanced>false</advanced>
</parameter-group>

<parameter name="local_context" type="text" required="false" groupName="system">
<label>Context Instance Type</label>
<description>The local context holds Ruby runtime, name-value pairs for sharing variables between Java and Ruby. See
https://github.com/jruby/jruby/wiki/RedBridge#Context_Instance_Type for options and details.</description>
<default>singlethread</default>
<options>
<option value="singleton">Singleton</option>
<option value="threadsafe">ThreadSafe</option>
<option value="singlethread">SingleThread</option>
<option value="concurrent">Concurrent</option>
</options>
</parameter>

<parameter name="local_variable" type="text" required="false" groupName="system">
<label>Local Variable Behavior</label>
<description>Defines how variables are shared between Ruby and Java. See
https://github.com/jruby/jruby/wiki/RedBridge#local-variable-behavior-options for options and details.</description>
<default>transient</default>
<options>
<option value="transient">Transient</option>
<option value="persistent">Persistent</option>
<option value="global">Global</option>
</options>
</parameter>

<parameter name="gem_home" type="text" required="false" groupName="environment">
<label>GEM_HOME</label>
<description>Location ruby gems will be installed and loaded, directory will be created if missing and gem installs
are specified</description>
<default></default>
</parameter>

<parameter name="rubylib" type="text" required="false" groupName="environment">
<label>RUBYLIB</label>
<description>Search path for user libraries. Separate each path with a colon (semicolon in Windows).</description>
</parameter>

<parameter name="gems" type="text" required="false" groupName="gems">
<label>Gems</label>
<description>Comma separated list of Ruby Gems to install.</description>
</parameter>

</config-description>
</config-description:config-descriptions>

0 comments on commit 5de8cf1

Please sign in to comment.