From 0e4a9b34b4224a04a6ebe8d8dae54e774399f27b Mon Sep 17 00:00:00 2001 From: Kai Kreuzer Date: Sun, 20 Dec 2020 23:42:37 +0100 Subject: [PATCH] Delete jsr223-jython.md (#1349) Signed-off-by: Kai Kreuzer --- configuration/jsr223-jython.md | 161 --------------------------------- 1 file changed, 161 deletions(-) delete mode 100644 configuration/jsr223-jython.md diff --git a/configuration/jsr223-jython.md b/configuration/jsr223-jython.md deleted file mode 100644 index d2448c428..000000000 --- a/configuration/jsr223-jython.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -layout: documentation -title: JSR223 Jython Scripting ---- - -{% include base.html %} - -# JSR223 Jython Scripting - -## Configuration - -[Download](https://jython.github.io/index) the Jython 2.7.0 standalone or installer package, or install through a package repository. -Install Jython on the local filesystem into a directory of your choice. -A good installation directory is `/etc/openhab2/automation/jython`. -For the easiest installation mechanism simply download `jython-standalone-2.7.0.jar` and copy it into your installation directory. Alternatively you can execute the installer and specify your installation directory during the install. -Note that newer versions than 2.7.0 are not yet supported. - -The Jython implementation will need to be added to openHAB's Java classpath. -How this is done depends on the specific installation technique and operating system. - -### Linux Package Installers - -Modify the `EXTRA_JAVA_OPTS` environment variable in `/etc/default/openhab2` to: - -```bash -EXTRA_JAVA_OPTS="-Xbootclasspath/a:/etc/openhab2/automation/jython/jython-standalone-2.7.0.jar -Dpython.home=/etc/openhab2/automation/jython -Dpython.path=/etc/openhab2/automation/lib/python" -``` - -This will add the Jython library to the Java classpath, -set the Jython home directory and specify the initial Python path for the Jython runtime. -Specifically `bootclasspath` must point to your installation directory plus the Jython library, which is -`jython-standalone-2.7.0.jar` if you copied the jar directly or `jython.jar` if you ran the installer. -Similarly `python.home` points to your installation directory. -Python modules and packages can be installed into the `python.path` locations and imported from scripts. -Note that library modules and packages are not automatically reloaded when they change. - -### Mac and Windows or Manual Installation - -Set the `EXTRA_JAVA_OPTS` environment variable to the value described in the Linux configuration. -Note that on Windows the environment variable value should be set as a single line -(without backslashes to combine the line fragments). - -## Configuration Testing - -In the `automation/jsr223` directory create an empty file called `test.py`. - -Watch the openHAB log file carefully ([Karaf logging]({{base}}/administration/logging.html) -or viewing the `openhab.log` file directly). -You should see a log line with information similar to: - -```text - ... [INFO ] [.a.m.s.r.i.l.ScriptFileWatcher:150 ] - Loading script 'test.py' -``` - -Look for any potentially related error messages. - -To enable debug logging, use the [Karaf logging]({{base}}/administration/logging.html) commands to -enable debug logging for the automation functionality: - -```text -log:set DEBUG org.openhab.core.automation -``` - -## Script Examples - -Jython scripts provide access to almost all the functionality in an openHAB runtime environment. -As a simple example, the following script logs "Hello, World!" into the openhab.log file. -Note that `print` will usually not work since the output has no terminal to display the text. -One exception is when the openHAB server is running from the Eclipse IDE. -The openHAB server uses the [SLFJ](https://www.slf4j.org/) library for logging. - -```python -from org.slf4j import LoggerFactory - -LoggerFactory.getLogger("org.openhab.core.automation.examples").info("Hello world!") -``` - -Jython can [import Java classes](http://www.jython.org/jythonbook/en/1.0/ModulesPackages.html). -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). - -::: tip Note -Be careful with using wildcards when importing Java packages (e.g., `import org.sl4j.*`). -This will work in some cases, but it might not work in some situations. -It's best to use explicit imports with Java packages. -For more details, see the Jython documentation on -[Java package scanning](http://www.jython.org/jythonbook/en/1.0/ModulesPackages.html#java-package-scanning). -::: - -The script then uses the [LoggerFactory](https://www.slf4j.org/apidocs/org/slf4j/Logger.html) -to obtain a named logger and then logs a message like: - -```text - ... [INFO ] [.openhab.core.automation.examples:-2 ] - Hello world! -``` - -Notice that no rules were required for this simple script. -This can be a useful way to experiment with simple Jython code before defining rules or other more advanced functionality. - -If you want to respond to openHAB events you can create rules in the scripts. -The following script requires two string items, `TestString1` and `TestString2`. -The rule created in the script is triggered by an update to `TestString1` and, -when triggered, the rule updates `TestString2`. - -```python -scriptExtension.importPreset("RuleSupport") -scriptExtension.importPreset("RuleSimple") - -class MyRule(SimpleRule): - def __init__(self): - self.triggers = [ - TriggerBuilder.create() - .withId("MyTrigger") - .withTypeUID("core.ItemStateUpdateTrigger") - .withConfiguration( - Configuration({ - "itemName": "TestString1" - })).build() - ] - - def execute(self, module, input): - events.postUpdate("TestString2", "some data") -automationManager.addRule(MyRule()) -``` - -When a script is loaded, some names are already defined in the script *scope* (the local Jython namespace). -To define rules, you must include some additional [script *extensions*](jsr223.html#presets) -(implemented as "presets") that add more names to the script scope for specific purposes. -In this case, the `RuleSimple` extension is used to import the `SimpleRule` base class. -The `RuleSupport` extensions provides the `automationManager` that allows you to register rule instances with openHAB. - -The Jython rule class uses the `SimpleRule` subclass to simplify some aspects of the openHAB interface for use with JSR223. -In the constructor, the `triggers` atribute is set to a list of [triggers](jsr223.html#trigger_types). -In this example, the trigger is a state update trigger. -The trigger name identifies the trigger and the configuration direction provides trigger-specific options. -For the item update trigger, the configuration provides the item name of the monitored item. - -The `execute` method is invoked when the rule is triggered. -The `module` and `input` arguments can be used in advanced rules. -The information provided varies by the trigger type. - -### Resources - - - [Scripted Rule Support](https://github.com/eclipse/smarthome/wiki/Scripted-Rule-Support) - - Early documentation on JSR223 usage in openHAB 2. Includes IDE setup instructions. - - - [openhab2-jython](https://github.com/steve-bate/openhab2-jython) (github) - - Provides information and examples related to advanced, exploratory openHAB JSR223 Jython usage. - - - Wrappers to simplify `Trigger` usage in rules. - - Python decorators to define simple time-triggered and item-triggered functions - - Python logging bridge to openHAB logger - - Custom Trigger Implementations: `StartupTrigger`, `OsgiEventTrigger`, ... - - OSGI console command implemented in Jython - - OH2 Module Implementations in Jython (things, item providers, ...) - - Jython-based ScriptExtension (preset) provider support. - - Example of using Pykka Actor library. - - Unit-testing support