Introduce dedicated persistence aliases

[mherwege]

See discussion #4359

At its current state, defining and using aliases for persistence is largely broken.

1. At the point of definining aliases, one can define an alias in the syntax for an item, item group or all items. There are several issues with this way of defining:

• The last two options obviously don't make sense.
• One has to define with all parameters (strategy, filters) for each item you want to define an alias for (otherwise the default will be used). It becomes impossible to use a group definition for the strategy and filters.
• It is not possible to define an alias for an item without a strategy (once you define it, the default strategy will be applied). This can be useful if an item is persisted manually through a rule, and not through a strategy.

2. There are methods to store items with aliases. However, on retrieval (query), it is assumed the itemName in the FilterCriteria is the alias. Many persistence services use this filter itemName to look up the item in the item registry (e.g. to find the unit). This does not work if an alias is passed in the filter criteria.

This PR does 2 things:

1. Redefine syntax to have a separate section to define aliases. This is a breaking change, but allows defining aliases in a proper and consistent way, and is easy enough to apply.
2. Add interface methods (with default implemention) QueryablePersistenceService.query(FilterCriteria, String) and ModifiablePersistenceService.remove(FilterCriteria, String). The second argument defaults to null in its default implementation. Persistence services implementing support for aliases and using item registry lookups, should implement these new methods to make querying with aliases work. However, as there is a default implementation, if the persistence service is not changed, it will behave as it does now (failing if the persistence service tries to do a lookup in the item registry). All core calls to the query and remove methods are also changed to add the alias if one exists. I expect some classes in the ui repo (and maybe some scripting addons) will need limited changes as well to properly support aliases. (I have not done this, but the methods without alias could be annotated @Deprecated to make it clear to the consumer they should use the methods with alias arguments).

For 2, the better approach would probably be to make the individual persistence services completely independent of the item registry. The interface should then have store, query and remove methods that are only concerned about the storage key and values, whereby the storage key is the item name or alias. The core persistence layer would be responsible for using item name or alias when calling these methods, and then also for all actions currently done in the individual persistence services where the lookup in the item registry is required (e.g. unit lookup and conversion). Also ChartServlets would be impacted by this. As this is obviously a major API change, I have refrained from doing that. With the current proposal, the interaction with persistence services should keep on working as before, and persistence services that support aliases (that is a limited number) can easily be enhanced to properly support them (instead of the broken support in the current implementation without applying required changes).

Another option would be to completely remove support for aliases from openHAB core, and leave it to individual persistence services if they want to implement something, marking the store methods with alias parameters as deprecated. I also think that would be a step back and is not needed. But it may simplify code and, as it stands, I don't have the impression aliases are used a lot (if they where, I would expect to see many more issues being created as they don't work).

This PR is offered as a starting point and open for discussion. My design premises have been to try to fix it while not breaking the interface with persistence addons. I would very much appreciate feedback if this approach makes sense, and would be accepted before I invest further time in it.

@jpg0 FYI and evaluation.

EDIT: changed the default query method implementations to do an alias lookup, so the returned results are correct as long as the implementing persistence service does not do an item registry lookup. This again limits impact on persistence service implementations.

[jpg0]

Thanks for the PR. I think it addresses the current problems and introduces the least possible change. The code looks fine from a quick look.

[mherwege]

This is now tested, and if the concept is accepted, it is ready from my perspective. This is of course open for further discussion.

[openhab-bot]

This pull request has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/ideas-and-discussion-what-features-do-you-want-in-openhab-5-0/160573/572

[kaikreuzer]

Thanks @mherwege for bringing this up and suggesting a solution. I'd be fine with this change, but could also consider to wipe aliases completely in openHAB 5 - as you say, they do not seem to be used much anyhow. But your suggestion is clearly less intrusive.

When we merge this, we would need a "breaking change note" in the distro and an update of the documentation, right?
I'd hence refrain from merging this just before creating milestone 1.

[mherwege]

I'd be fine with this change, but could also consider to wipe aliases completely in openHAB 5 - as you say, they do not seem to be used much anyhow.

I see value in the functionality when changing item names. So I would want to keep it and improve it.

When we merge this, we would need a "breaking change note" in the distro and an update of the documentation, right?

Absolutely. I will prepare these.

I have rebased and resolved some conflicts with already merged persistence enhancements.

[mherwege]

Breaking change alert and documentation update have been created.

[kaikreuzer]

Excellent, many thanks for your work!

[holgerfriedrich]

@mherwege did you create a PR to addons as well?
This seems to break MapDbPersistenceService.java in line 214, and MapDbPersistenceServiceOSGiTest.java.

@lsiepel FYI
https://github.com/openhab/openhab-addons/actions/runs/13395224956/attempts/2

[mherwege]

@holgerfriedrich I am preparing one where I get aliases to work for all persistence services.

I have the fix already for mapdb and will split it out in a separate PR. The issue is actually caused by parallel work on openhab/openhab-addons#17820 and this PR, requiring a further update to mapdb as the mapdb PR got merged earlier.

[holgerfriedrich]

@mherwege no problem, good to know that you are working on it 👍

The addon build was red for a few days now and I had hoped that my last PR on core had resolved all issues....
So once you are ready, the CI will hopefully turn green again.

[mherwege]

PR created: openhab/openhab-addons#18285