Marketing term for JSR223 scripting

[ThomDietrich]

Continuing from #428

@steve-bate @BClark09 In one of my first comments I asked if we should go with "JSR223 Scripting" in the long run? I feel the name might be too technical to attract the broad audience, maybe a simpler catchy name would be better? Do you think it's worth discussing that further?

[ThomDietrich]

Reply by @BClark09:

I think Java 9 includes this functionality natively and if were're going to migrate to that then this I guess (a wild one at that) support might have to change considerably, so definitely not in the loooong run. The problem is being able to serve those who know one of the scripting languages supported by JSR223, and those that know it includes more than that.

• Scripting for openHAB (See Wikipedia's friendly title for comparison)
• Using Other Scripting Languages
• Embedding Scripting Languages
• Javascript, Python and Gradle Support

[ThomDietrich]

Reply by @steve-bate:

I like the idea of moving away from using "JSR223" name to describe this scripting support. I quickly looked at the Java 9 scripting API and it looks very similar to JSR223 (same package, class names, etc.) so wouldn't expect the functionality to change much. In the future we may regret using the automation/jsr223 directory for user scripts given the deprecated name. Personally, I'd prefer to have all scripts in the scripts directory but I don't know if there are technical reasons for not doing that.

[ThomDietrich]

What do the others think? @smerschjohann @kaikreuzer @martinvw and others

[martinvw]

I do agree the current term is to technical so I would be happy with a correct but not to technical name 😄

[BClark09]

My vote is on "Scripting for openHAB", I also agree with @steve-bate and think we should also allow people to add these scripts to a "scripts" directory as well as the jsr223 directory (for legacy).

[ThomDietrich]

I like @BClark09's suggestion to follow "Scripting for the Java platform" and call it:
"Scripting for openHAB" or "Scripting" in short. It's meaning is intuitive while still having a technical touch and the term doesn't have a fixed meaning in the openHAB world yet. Users can later also talk about "scripting examples/solutions" or "Jython scripting". The term will be easy to establish and grasp

[kaikreuzer]

allow people to add these scripts to a "scripts" directory as well as the jsr223 directory (for legacy).

This won't work as the "scripts" folder specifically ONLY accepts xtext scripts (i.e. "old" rule engine stuff, just like "rules" is only for Xtext rules.

We already had a long discussion in January about that and the outcome was the automation/jsr223 folder.

I don't think that "Scripting for openHAB" is in any way specific enough. To me, it is the same as "programming for openHAB". It does not tell you what you actually do with it, i.e. in this case that it is about automation.
After all "scripting" is just the "other option" to programming in Java - it simply gives you more language choice (and by chance does not require code compilation). On the long run, you will be able to implement rules as scripts, but also actions, bindings, 3rd party integrations, etc. So instead of having one "scripting" topic, we will rather need to explain how to do certain things through "scripts".

[kaikreuzer]

More on the topic of the original question: I agree that jsr223 is very technical and I am fine with finding another term for it. But I think the right term might differ per topic that we want to describe.

Looking at the Python examples, we are actually looking at programmed classes and not at all at scripts...

[steve-bate]

This won't work as the "scripts" folder specifically ONLY accepts xtext scripts (i.e. "old" rule
engine stuff, just like "rules" is only for Xtext rules. We already had a long discussion in January >about that and the outcome was the automation/jsr223 folder.

I never understood during that discussion why it was so important to have only Xtext scripts in the scripts directory. I don't think having all scripts there would cause significant confusion for the users and could possibly be less confusing. I understand that there might be a technical issue with Xtext rules only being able to invoke Xtext scripts rather than any JSR223 scripts (not sure if that's true or not).

So instead of having one "scripting" topic, we will rather need to explain how to do certain things through "scripts".

I think we need both types of documentation. We need general scripting documentation and application-specific documentation.

I don't think that "Scripting for openHAB" is in any way specific enough. To me, it is the same as
"programming for openHAB". It does not tell you what you actually do with it, i.e. in this case that it is >about automation.

I understand your point, but most programmers understand the concept of scripts and we've already used that terminology for quite some time. Note that scripting doesn't require programmed classes. There is an example script in the documentation with no classes. Also, some scripting languages are compiled (Jython generates bytecode files). The primary difference I see with scripting is that there is much less programming and environment overhead. If a user wants to create a simple extension to openHAB, they don't need to know Java, OSGI, Maven, Thing APIs, Binding APIs, the Eclipse IDE and so on. Even for experienced Java programmers it is much easier if they already know how to program in one of the scripting languages.

Again, we already use the "script" terminology and that term doesn't specify what will be done with the scripts. However, since the JSR223-related scripting functionality is not openHAB-specific, should we consider "Scripting for Eclipse SmartHome" instead?

[kaikreuzer]

I think you did not really get my point, let me try to explain again:

"Scripting" is after all just a technical term for "programming" - and in that way it is equally technical & unspecific as "jsr223".
There is nothing like "scripting for openHAB/ESH", just like there isn't anything like "programming for openHAB/ESH".
Yes, openHAB already uses "script" as a terminology and it has a very specific meaning: It is a linear piece of code, which can be called from the console or from rules and which has access to items and openHAB actions. It therefore has a very clear definition of how this code is called and what you can do in/with it. This contract is the API of such a script. The jsr223 automation feature is NOT AT ALL about this API. This feature allows you to write rules, so imho they should rather reside in the "rules" folder, not in a "script" folder. Additionally, this feature can be used to define new rule module types. These should not be in "rules", but rather in "module-types". Equally for rule templates. All those examples (rules, module-types, templates) have their own specific API and all that there is in common is the programming language (and not even that, but only the fact that every jsr233-compliant language can be used). And once we offer to build bindings in such languages, there will be an API for that as well (likely to be very similar to the existing Java Binding-API). You would not want to have new bindings being deployed in "conf/scripts"...

So yes, we can have a general section that covers the similarities (but this will mainly be the information on how to get the scripting language engines technically set up). For this, I would prefer a term like the suggested "Using (Other?) Scripting Languages".

[steve-bate]

"Scripting" is after all just a technical term for "programming" - and in that way it
is equally technical & unspecific as "jsr223". There is nothing like "scripting for
openHAB/ESH", just like there isn't anything like "programming for openHAB/ESH".

Based on this clarification I think I did understand. However, I have a very different perspective. Scripting is a kind of programming but that doesn't make "scripting" and "programming" synonymous terms. I would hope you would agree that almost all the existing openHAB functionality is implemented using programming tools and techniques that would not be considered "scripting" by practically anybody's definition of the term.

Also, it's not particularly relevant but JSR223 is very specific. There are associated specifications and standardized APIs. The issue is that Java 9 platform will stop referring to the scripting APIs as JSR223 so the name will eventually become outdated.

Yes, openHAB already uses "script" as a terminology and it has a very specific meaning:
It is a linear piece of code, which can be called from the console or from rules and
which has access to items and openHAB actions.

JSR223 scripts can be called from rules (JSR223 rules at least, not sure about the NG rule engine) and has access to openHAB items and actions. It would be very easy to write a script to add a console handler for invoking scripts if someone needed that. The "linear piece of code" requirement seems to be the only real discriminator from your description. However, I'm guessing you really meant that a "script" is only the limited Xtext grammar supported by openHAB.

This contract is the API of such a script. The jsr223 automation feature is NOT AT ALL
about this API. This feature allows you to write rules, so imho they should rather reside
in the "rules" folder, not in a "script" folder.

You're correct that JSR223 is not about the openHAB-specific Xtext "scripting" API but is about the more general and powerful Java platform scripting API. In my opinion, I'd prefer it if Xtext was just another JSR223 script language. It's fine if it's very limited capabilities. Other JSR223 languages also vary in their capabilities and degree of integration with the Java runtime.

As for directories, I don't see as much value as you do in openHAB's rigid configuration directory structure. I could write pages on this topic alone, but I accept that you feel so strongly about it that you aren't likely to consider more flexible alternatives. That said, I don't care if we continue with the automation\jsr223 directory or referring to Java platform scripting as JSR223. I don't believe it's the best approach, but it will work for my purposes. It doesn't bother me at all to implement openHAB components as scripts in that directory.

For this, I would prefer a term like the suggested "Using (Other?) Scripting Languages".

I'm fine with that too.

[kaikreuzer]

Scripting is a kind of programming but that doesn't make "scripting" and "programming" synonymous terms.

So what would you call a binding implemented in Jython through JSR223 then? Is it scripted or programmed?

JSR223 scripts can be called from rules

No, definitely not if this "jsr223 script" is a binding or a rule module type handler.

I don't see as much value as you do in openHAB's rigid configuration directory structure

So you mean it would be better to have a single "conf" folder where people can throw in anything they like (rules, add-on configurations, item files, etc.)? I indeed prefer it a bit more sorted, so that the parsers know where to look for files and not only rely on file extensions and content.

I don't care if we continue with the automation\jsr223 directory

As said above, I am fully with you that jsr223 is very technical and not the best term for end users and I am open for better alternatives. I could imagine that we instead use automation/rules, automation/module-types and automation/templates instead (which actually already exist for rules/moduletypes/templates that are defined a json or xml).

[steve-bate]

Scripting is a kind of programming but that doesn't make "scripting" and "programming" synonymous terms.

So what would you call a binding implemented in Jython through JSR223 then? Is it scripted or programmed?

Yes. Either answer is correct. Scripting is a subcategory of programming, not synonymous with it. The artifacts created by the script (like a binding) seems to me to be irrelevant to the question.

JSR223 scripts can be called from rules

No, definitely not if this "jsr223 script" is a binding or a rule module type handler.

I should have been more precise. The artifacts created by a JSR223 script can be used (or called) from scripted rules (which are just another artifact). This includes abstract bindings or rule module type handlers. For example, a rule could trigger from an event, use the event data to subclass an abstract binding implementation (defined in another script) and register an instance of the new binding class as an OSGi service.

So you mean it would be better to have a single "conf" folder where people can throw in anything they like (rules, add-on configurations, item files, etc.)?

No, that's not what I meant although a flexible file loader would allow that approach if that's what worked best for a specific user. For me personally, I'd like to be able to organize openHAB file artifacts so that a subdirectory could contain all the files for a specific automation purpose. For example, if I add support for a device or a function, like presence detection, I'd like to have the items, rules, scripts, transforms and so on for that functionality located together rather than spread across several directories.

I indeed prefer it a bit more sorted, so that the parsers know where to look for files and not only rely on file extensions and content.

I'm not sure how to respond to this because looking for files sounds more like a file watcher responsibility than one for a parser. In JSR223, once of a script has been detected the javax.script engine manager is already able to handle various file extensions without having specific directories associated with either extensions or content. To force a directory structure based on content would be a step backward with no technical benefit.

A script can define multiple kinds of artifacts. It could define rules, items, transforms, functions, classes, bindings, module handlers, console commands or whatever in a single script. A directory structure that assumes a single kind of artifact in each script wouldn't work well for a script like that. Likewise, a directory structure that forces a single file extension per directory wouldn't be necessary or desirable (in my opinion).

We need one or more JSR223-related directory hierarchies, ideally configurable, for the file watchers to watch but beyond that I think we should not constrain the scripting directory structure any further unless there is a clear technical benefit.

[kaikreuzer]

I think I start seeing where the confusion comes from.

You seem to think about jsr223 scripts as "code that is added to the classpath", so similar as (compiled) Java code can be thrown into "add-ons", you would want a folder (tree) where you can put any kind of scripted code.

What you are missing here is that openHAB is not a monolithic Java application, but that it is highly modular and different parts of its code are isolated from each other (by having different classpaths).
Scripts in folders like automation/jsr223 are loaded by the feature that defines the API (in this case the Rule Engine API) and thus these scripts share the classpath of that feature. It also provides the execution scope (i.e. available services) for those scripts. Having a single script that "define[s] rules, items, transforms, functions, classes, bindings, module handlers, console commands" therefore simply would not work.

Of course one could say that we could define a "master" script loader that puts all scripts on the boot classpath and makes available all services in the scope. But this would fully spoil the openHAB architecture, leading to security issues, stability issues and probably many further unforeseen problems.

[steve-bate]

What you are missing here is that openHAB is not a monolithic Java application, but that it is highly modular and different parts of its code are isolated from each other (by having different classpaths).

If I'm missing something, it's not that. I understand OSGi class path behavior and Java class loaders in general.

Having a single script that "define[s] rules, items, transforms, functions, classes, bindings, module handlers, console commands" therefore simply would not work.

Not true. The Jython scripts can define services for those types of components and register them with OSGi using the bundle context of the JSR223 script loader. Take a look at my GitHub repo for several examples. Although the components are currently defined in separate scripts, they are all loaded by the same script loader with the same OSGi class path. There should be no issue with combining them into one script, if I wanted (which I don't).

This does not require all scripts to be on the boot class path.

Furthermore, in the scripts I can create custom class loaders to extend the class path and, if needed, I can query for existing OSGi services and use their classpath to load classes that are not on the JSR223 API class path.

you would want a folder (tree) where you can put any kind of scripted code.

The automation/jsr223 directory tree is already that, at least for languages that support the JSR223 API.

[Confectrician]

We have significant changes for the whole rule/scripting area of openHAB, so this does not fit anymore.