[WIP] NGRE/JSR223 Documentation refactoring

I think it makes sense to wait a bit for some progressbefore we have a look at the libraries.

I just read in https://www.graalvm.org/docs/getting-started/ that GraalVM is based on OpenJDK 8!

Has anyone tried to estimate whether the conversion effort would be small enough to switch from JSR223 to GraalVM already now in openHAB 2.5 or 2.6?

I only mean, because the expenditure which we start now, would build then already on the future-safe platform.

What do you mean?

No schedule, but it’s close… https://github.com/openhab/openhab-distro/issues/768.

Not so small :smile:! Here’s an example of what you can get from the javax.script.ScriptEngineFactories when JS, Groovy and Jython are present…

getEngineName getEngineVersion getLanguageName getLanguageVersion getMimeTypes getExtensions getNames
Oracle Nashorn 1.8.0_201 ECMAScript ECMA - 262 Edition 5.1 [application/javascript, application/ecmascript, text/javascript, text/ecmascript] js [nashorn, Nashorn, js, JS, JavaScript, javascript, ECMAScript, ecmascript]
Groovy Scripting Engine 2.0 Groovy 2.4.12 [application/x-groovy] groovy [groovy, Groovy]
jython 2.7.1 python 2.7 [text/python, application/python, text/x-python, application/x-python] py [python, jython]

I used a combination of getLanguageName and getLanguageVersion in the ScriptTypeModuleProvider. There is no dynamic way to identify the ScriptEngineFactory as compatible with JavaScript, so that it could be used in the name. I brought this up in several times when discussing the PR in GH. It could be changed so that the names aren’t generated dynamically, if it is really that important. Personally, I prefer seeing the actual name and version, so that I know specifically what is supported. For example, if we just say JavaScript, someone could try to use classes in their script.

I’m not sure of the level of effort, but the introduction of GraalVM would be a significant change that I expect would have to go into a major release. I do not know yet if it is something that is technically feasible or would be approved, but it’s about time to create an issue to start the discussion. Like javax.script, GraalVM can be used for much more than automation, so the discussion could take a while. From what I’ve picked up, it sounds like we will go from 2.5 to 3.0, which would leave very little time for it, and there is already a lot of work to do within automation before then.

I know what ECMAScript means. Dynamic reading is already best! There are many, many more important things! :wink:

The integration would not mean that all other facets that GraalVM can offer have to be done at the same time. It would also correct the later conversion to Java 11/12, if JSR223 has to be replaced.

Of course, it would only make sense if GraalVM could be made usable relatively easily in openHAB 2.5 and few classes would have to be adapted. Thank you for your estimation, you are much deeper in the story.

1 Like

Maybe we should cut out the graalvm topic from here, since it isn’t that related to the documentation.
I will prepare a little summary at the weekend and then we can have a look at things that could be done/prepared already.

2 Likes

In this context I think JDK11 and GraalVM are for openHAB 3. If I remember correctly from one of the heated topics Kai also indicated that openHAB 2.x would stay on JDK8.

I think it would be good to indicate for any of the given ideas whether you think it is for openHAB 2.x or 3.x.

1 Like

Several people reacted positively to this post. There may be some info in it that could be used in the docs.

3 Likes

We should definetely think about the generic rule presentation in the docs too, while organizing the jsr223 refactoring.

This is something we have to improve.
We should not say xtend is bad or jsr is better, but we should have a rules area that explains the possibilities and then afterwards shows more information about the different ways of doing rules.

I am also thinking of extracting the rules articles out of the configuration section and moving it into its own docs section.
Rules is such a big topic and you cant explain it with one side per rule techinque.

2 Likes

I agree. I wonder if a hierarchical organization makes sense. We have a root article that talks about what Rules are for and some of that generic stuff that I’ve mentioned above. Then under that we link to separate pages for Rules DSL and each of the JSR223 languages.

That way we privilege none of the languages over the others and it becomes apparent even to newer users that there is more than one option.

I’m ambivalent as to whether we should also mention third party options here. Part of me thinks it would be helpful and part of me thinks it’s not our job.

I had something similar in mind as wrote

Currently, there is no Concepts> Rules section. We could make one and put the general discussion and explanation of the differences between the rule engines in there. The Configuration Guide> Rules and JSR223 sections could be combined and use the fancy tabs as in Jerome’s example. IMO we should put emphasis on the new rule engine, with UI first and then put the DSL at the end. After 3.0, the DSL section can be tagged as legacy or moved to another area which includes steps for migrating .rule files. The New User Tutorial> Working with Rules and Script section could focus on working with rules in the UI, as that is what will be easiest for a beginner.

I really like the tabs! In looking at the docs, there is a wall of information that I think the tabs could help organize in a way that it is easier to locate what you are looking for. For example, the sidebar for the Installation Guide could just be Overview, OS and Hardware, with tabs in each section. This is too general for this discussion, but those tabs could really help the docs. :slightly_smiling_face:

Sorry for the delay, prio was on other topics.

I have edited the first post with an updated TODO list.

Feedback welcome.
I think i will setup a jsr-refactoring branch in the docs repo already, so we can do some improvements in a first run.

FYI… I plan to have the helper library directory restructuring completed today, and possibly the org and repo renaming too.

I was just on my way to ask you if i can already help anywhere. :smiley:

Nothing comes to mind, but thank you! I’m first pushing a Jython update for compatibility after the ESH reintegration package name changes. I’ve made it backwards compatible too, so no breaking changes. I’ve also added in all of the other OH classes, so that no changes should be necessary when the rest of the packages are renamed. This is ready to go, but I’ve been going through every file and it’s hard not to do some housekeeping while I’m in there!

Any ideas when this will be available?

Should be before tomorrow morning (ET), but probably much sooner!

Awesome. I’m having some troubles with the hello_world.py example (specifically it not being parsed because OH doesn’t seem to see the core modules under /lib/python - I get Error during evaluation of script 'file:/openhab/conf/automation/jsr223/personal/hello_world.py': ImportError: No module named core in <script> ) and I’m hoping that this will fix it, or at least rule out it being related to package names.

Open another topic (tagged with jsr223) and see what I can do to help. That does not sound like it would be caused by the package renaming.

@5iver I’ve pulled your latest changes and it all seems to be working now :slight_smile: no need to open a new thread.

Edit: And forgive me for being so rude, many thanks for this!

1 Like