JRule - OpenHAB Rules using Java

OpenHAB Rules using Java

java-logo-vert-blk

This automation package aims to enable Java development of OpenHAB Rules. The addon will allow the user to create custom OpenHAB rules in one or several .java-files. The Java Rules will need to define triggers in order for the rules engine to know how and when to execute them.

The triggers are very similar to the triggers in Rules DSL but expressed using java annotations. In order to execute rules based on items defined in OpenHAB either in .items-files or the GUI. The addon needs to know about these items and this is realized by the Rule Engine by generating a .java and a .class file for each item in the system. The class files are then packaged in a .jar-file which the user can use as a dependency when doing Rules Development.

For the addon to be able to pick up rules, they first need to be compiled by the rules engine. The source .java rules-files are placed in a specific rules folder and will be automatically compiled and loaded into OpenHAB when the rules engine is started. The syntax for rules as well as the design and thinking behind the addon is to provide something that is similar to Rules DSL but more powerful, flexible and customizable.

Documentation / Installation / Download

Bugs

Any bug you find is good to report. Preferred way of reporting bugs is to create an issue on github: Issues · seaside1/jrule · GitHub
I will look at failures in this thread as well.

Contribute

Create a Pull Request on github: Pull requests · seaside1/jrule · GitHub

Resources

https://github.com/seaside1/jrule/releases/latest/download/org.openhab.automation.jrule-3.x.x-latest.jar

13 Likes

I’ve opened up the repository now. It is working ok now I believe. Still expect major updates and changes. Anyone who want to contribute or change stuff please submit a PR.

/S

A few comments on usability for a wide openHAB audience:

  • If only .items files are supported that will be a deal killer for a huge portion of OH 3 users. More and more users are migrating to UI managed Items and new users never use .items files at all. If you were to support managed Items through REST API calls (or internal API calls) then you’d be able to get the Items from both .items files and managed since the .items files Items are reflected in the REST API as well.

  • If the .java files are only picked up when the binding starts, that means one needs to restart OH or at least restart the binding which becomes really awkward if in a develop/test loop working on rules.

  • The standard folder for JavaScript, Python, and Groovy rules (maybe jRuby too?) is /etc/openhab/automation. /etc/openhab/rules and /etc/openhab/scripts is legacy. Speaking only as myself, I’d prefer to see this jrule folder default under automation for consistency.

  • I would have expected this to be an automation type add-on, not a binding. It is counter intuitive to have to create a Thing to enable rules. I believe there is a way to specify add-on configuration through the UI without requiring a Thing.

  • This appears to be completely incompatible with UI created rules. So no Script Conditions or Script Actions appear supported.

It’s nice to see this coming along though and I look forward to see it progress. But I can’t even test it out right now because of the limitations.

1 Like

Hi!
Thanks for the feedback! I appreciate all feedback!

I’m not even sure this is my aim. I guess it depends on how it evolves, if more people are willing / have the interest to develop the binding further. Or if it will be just a handful of people preferring to use java to write rules. I could even see this being developed into something else, maybe we should view this as a Proof of Concept.

The binding connects to the itemRegistry to fetch the items. It should be possible to define
items in the GUI. I have not tested this yet, but should work.

The binding will reload the rules if you modify, add or delete files in the location, no need for restarts.

I agree, I’ll change this in the next changes.

Yes this was my original plan. I could not find a suitable base class to extend for a automation package. The base class used by the other JSR-automations will not work with this binding.
The documentation for automation is very limited (compared with binding documentation), as well as the number of automation addons gave me no apparent options how to add this.
I’ll look into it and see if I can transform it later on, I still expect it to work in a similar manner.

True, and it’s not a priority for me to this. I will add a note about this.

BR S

I guess I’m not sure why someone would bother to develop something for OH that only a small portion of the openHAB userbase could use. But everyone has their own goals. It just becomes really hard to manage all these different subsystems for writing rules when there is so little overlap between who they all work. We already have so many niche rules subsystems it’s unmanageable and really hard for new users to choose “the right one.” But given that’s the case, there probably isn’t any reason why you should stick to the Rules DSL precedent for how to structure the rules if Java pushes you in a different direction.

All Items no matter how they are defined should be available then.

Yes, but if there are a lot of adopters it will be easier to motivate a merge and add the needed functionality that is required for an official automation/binding-addon.
I developed this mostly because it makes my life so much easier being able to write my rules in java. With the approach I’ve chosen here, I find that my rules tend to work straight away, it’s more difficult to make syntax errors and you don’t have to spell the item names correctly (since you are using them as a dependency generated from OpenHAB). I never felt at home using Jython/Python/javascripts for creating rules. Rules DSL was fine but had too many limitations and held me back. I got stuck having so many ideas on how to make cool automations in my home, by not having the right tool for writing rules, I have create more addons than might be necessary and also held back with some work trying figure out if I would go the Python (Habapp) or Jython way.

I’m choosing to share my work because I want give back to the community and also because I find it interesting to develop these type of addons. I’m hoping some more people with pick up this track, and that it can grow with the help of others. If only a handful of people want to use this addon that’s fine. It’s also fine if more people want to use this and it grows into something else and eventually will reach a point where it can be merged.
I never had the intention to reach the wide OpenHAB user base but at the same time I’m sure that there are more people like me who perfer text-based configuration, not using GUI:s for creating rules and in general wants to use Java rather than something else.

This is understandable and probably caused by OpenHAB being such a open, powerful and generic platform. I have written that this is not for beginners and I should probably highlight that more. If you are a new user to OpenHAB this is probably not for you. The target group for this addon would be someone with Programming knowledge (preferably java).
For you, since you tend to be the person everyone asks for help and feedback when it comes to writing rules and automations (as well as design patterns) I can understand your frustration.

I honestly don’t know what language for writing rules I would choose if I began my OH-journey now, but I would probably be confused.

I tried to keep it similar to rules DSL, when I rewrote most of my DSL rules I just copy pasted them into to the java source, and could quite easily convert them into java. But yes probably better to see where Java can be utilized rather than sticking to the limitations and structure of DSL.

/S

As I wrote in the other thread , I am afraid it will never get merged until it is refactored to be an automation bundle.

Probably true, not a big issue as far as I see. The binding is not using much binding stuff and should be easy to convert when I figure out the automation base class to use.

/S

From the developer guide:

A binding is an extension to openHAB that integrates an external system like a software service or a hardware device. The external system is represented as a set of Things and sometimes Bridges with Channels .

There is also a section for automation modules.

Don‘t get me wrong, I don‘t want to disencourage you, but I think it would be better to do it right from the beginning instead of having never ending discussions later on…

Like I said I agree. It should not be a big refactoring since it is not relaying on channels or binding specific things.

/s

Small suggestion with regard to installation/compilation. You might try to simplify integration by removing explicit need for slf4j-api jar. Their packages are available within pax-logging-api (look for specific JAR/version in system/org/ops4j/pax/logging). It is always there if you use Karaf/OH!

The slf4j-api is not used by the binding, it is used when developing java-rules in a standalone Java ide, to be able to log directly from the rules. I could probably remove the dependency by adding a wrapper around slf4j, but I haven’t looked that much into that yet.

/S

I have refactored it from a binding to an automation package instead.
default location is now set to: /etc/openhab/automation/jrule and there is no need to add a jrule thing.

Br S

2 Likes

Out of curiosity and for future developers who come along, what was the right class to inherit from?

I didn’t extend any class. I got locked on extending some factory class due to the fact that’s what you do in bindings as well as the other automation modules I looked at.
Instead I added a @activate and @Deactivate method.

@Component(configurationPid = "automation.jrule")
@NonNullByDefault
public class JRuleFactory {

    private final ItemRegistry itemRegistry;
    private final JRuleEventSubscriber eventSubscriber;
    private final EventPublisher eventPublisher;
    private final VoiceManager voiceManager;
    private final JRuleHandler jRuleHandler;

    @Activate
    public JRuleFactory(Map<String, Object> properties, final @Reference JRuleEventSubscriber eventSubscriber,
            final @Reference ItemRegistry itemRegistry, final @Reference EventPublisher eventPublisher,
            final @Reference VoiceManager voiceManager) {
        this.itemRegistry = itemRegistry;
        this.eventSubscriber = eventSubscriber;
        this.eventPublisher = eventPublisher;
        this.voiceManager = voiceManager;
        jRuleHandler = new JRuleHandler(properties, itemRegistry, eventPublisher, eventSubscriber, voiceManager);
        jRuleHandler.initialize();
    }

    @Deactivate
    public void dispose() {
        jRuleHandler.dispose();
    }
2 Likes

I’ve built a new release, fixing internal dependencies and jar-generation. The previous jar was 7.5mbs :smile: Now 156kb.

Built an ALPHA2 version where you can add 3rd party jar dependencies.

Created and ALPHA3 prebuilt jar. Fixed some issues for 3rd party libraries and reloading rules when they are changed on disk.

Added an ALPHA4 build:

  • Refactored completable futures
  • Added 5 seconds of delay for initialization of the rule engine to avoid multiple reloads
  • Added support for play & pause for player item
  • Added commandLineExecute

Added an ALPHA5 build.

  • Removed dependencies on slf4japi and eclipse annotations
  • Added logInfo logDebug (to wrap slf4j and remove dep)
  • Fixed compilation of rules to be more robust with internal dependencies

You can still use sl4j for logging, but then you need to add it as an external dependency.