DSL Rules: example to disable a thing

[dilyanpalauzov]

No description provided.

[netlify]

✅ Thanks for your pull request to the openHAB documentation! The result can be previewed at the URL below (this comment and the preview will be updated if you add more commits).

Built without sensitive environment variables

Name	Link
🔨 Latest commit	55f939f
🔍 Latest deploy log	https://app.netlify.com/projects/openhab-docs-preview/deploys/69dde33dd6e58b000829e721
😎 Deploy Preview	https://deploy-preview-2700--openhab-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[stefan-hoehn]

@rkoshak @cweitkamp Can you review this?

[rkoshak]

Same as the "runRule" updates, I can't really comment on the code in the example. And I recommend delaying moving on this until we figure out what 's happening with openhab/openhab-core#5481 which will greatly change this.

[dilyanpalauzov]

This example shows how to combine openHAB services, exposed over OSGi, and Xbase. This example should have been included in the OH-documentation some years ago.

Even if openhab/openhab-core#5481 is integrated, it does not yet mean, that the changes offered from it, will be written down as user-visible documentation.

That said I suggest to proceed with the herein proposed change. It can reduce questions on the forum.

[rkoshak]

, it does not yet mean, that the changes offered from it, will be written down as user-visible documentation.

The whole point of openhab/openhab-core#5481 is to create simple Actions users can call so they don't have to go through all the work of pulling the OSGI services to do this. To disable a Thing the user just requires one line of code.

If the work in that PR doesn't get put into the docs, that PR has no point.

[dilyanpalauzov]

If the work in that PR doesn't get put into the docs, that PR has no point.

Currently many things are not documented and it is unpredictable how the documentarion will evolve, in particular if that PR or any other PR will be described in user-visible texts. It is insignificant if documenting that PR makes sense or not.

A reason why options are not documented is, that reviewing proposed changes for documentation takes sooooo long, that one just looses the wish to propose further changes.

Given that, the herein proposed changes reflect the current state of the software and are at this moment useful.

[lolodomo]

There is an easy way coming for 5.2 (if contribution is merged).
So let's pause this change and merge it just before 5.2 is released only if the other change is not merged.

[florian-h05]

@Nadahar What are your thoughts on this doc change? You authored both openhab/openhab-core#5481 and #2728 and know better than me about the status quo of rules DSL.

[Nadahar]

This operation can be performed easier now that openhab/openhab-core#5481 has been merged, but it could easily be done even much easier. I just didn't think of that there were a need for ThingManager, so there's no "convenience method" to retrieve it. The same goes for setting enabled status for a Thing. If this is something people really would like to do from rules, I could easily extend what has already been done to make this a "one liner".

It would be something like this instead as the code is now:

getInstance(org.openhab.core.thing.ThingManager).setEnabled(new org.openhab.core.thing.ThingUID("thing_uid"), false)

I don't think it should be merged as-is, since the example is much more "complicated" than needed now. And, as said, if there's a desire, it would be very easy to provide this as an extension so that you basically just can do MyThing.setEnabled(false). As I said during openhab/openhab-core#5481, I didn't know what to add/what the needs are, so I just added things I thought would be useful.

[florian-h05]

Thanks for your input.

And, as said, if there's a desire, it would be very easy to provide this as an extension so that you basically just can do MyThing.setEnabled(false).

Enabling/disabling a Thing programatically is (at least in my experience) only interesting for handling of Thing offline issues. Normally, Things should just work, or reconnect automatically IMO, but not all Things do so.

[florian-h05]

See the feedback above. We won't merge this for now.

[dilyanpalauzov]

Having an example in the documentation, how to disable a Thing, is on its own a very good idea. I suggest creating tabs per language, as done in other places in the documentation. Each tab performs the same action, as the other tabs, and each tab is written for a different language. In the current case for disabling a Thing, just by replacing val with var the example is applicable for Groovy. So this can be initially two tabs: one tab for Groovy (almost as is now), which by coincidence applies also to DSL Rules/Scripts, and one more tab for DSL Rules/Scripts.

[Nadahar]

What do you mean by "on its own"? These methods are now part of Rules DSL, there's no reason to deal directly with OSGi to do it. You can always find a way to do something in a more low-level/primitive way, that doesn't mean that you should do it, or document it as examples.

Also, if you want to do it as primitively as your example, there should be a try/finally that makes sure that ungetService() is always called.

[dilyanpalauzov]

What do you mean by "on its own"?

I meant “The idea itself is very good”.

What can throw what exception, which will prevent ungetService() of being called without try/finally?

[Nadahar]

I meant “The idea itself is very good”.

I still don't understand what you mean. What idea is very good? Documenting a very difficult thing to do something, to educate users in how things really work?

What can throw what exception, which will prevent ungetService() of being called without try/finally?

That isn't really the point, there might be exceptions from the methods, but more generally, you "always" do things like that inside try/catch just because you rarely know that an exception can never be thrown. Also, the code might be changed in the future, without anybody being aware that the change means that you need to add try/finally. Likewise, the code you're calling might change in the future and start throwing where it didn't use to. Most important here is the fact that it's part of the documentation, and you must expect users to use such code with their own "tweaks". They won't know when to add try/finally.