Persistence item info REST endpoint enhancements

[mherwege]

The persistence/items?serviceId=id endpoint is not very usable as it is in its current form.

The content that should go into the response comes from the Set<PersistedItemInfo> getItemInfo() in the QueryablePersistenceService interface. Persistence addons implement this interface.

The method is meant to return a Set of items that have been persisted in the backend with potentially some extra information (count, time of first record, time of last record). Not all persistence services are able to provide this, and even if they are, it might be too expensive a query. Therefore the interface documentation allows the persistence add-on to return an empty set in this case. This is problematic as that makes it impossible for the consumer of the result to know the difference between nothing persisted or not supported.
The contract is now to throw a UnsupportedOperationException when not supported. The default implementation will just do this, aleviating the persistence add-ons to implement anything.

To make this call more useful, I have also added persistence/items?serviceId=id&itemname=itemName. This will get the same information, but only for one item. I see a use for this in the UI, to be able to show in the UI if an item is persisted (see openhab/openhab-webui#3765). This adds an overload to the getItemInfo method with the Item name and alias. The default implementation just queries for the last persisted value and returns that, doesn't attempt returning count and first value to avoid creating an expensive query. The persistence add-ons could implement more efficient queries that return all parameters if realistic.

These changes are breaking and the add-on build may fail because the getItemInfo method can now return null if it checks for this in the build. I am preparing a PR to adapt the persistence add-ons to this change.

I also took the opportunity to synchronize the REST error response status between the different methods. I don't expect this will be an issue, but it is of course also a breaking change of the consumers of the REST API are specific about these.

[wborn]

To be able to make this distinction, I propose to change the contract and to allow returning null, meaning not implemented.

Why not throw an UnsupportedOperationException to make this distinction instead of using magic values like null?

[mherwege]

Why not throw an UnsupportedOperationException to make this distinction instead of using magic values like null?

That's indeed a better approach. Implemented, but still needs further testing.

[mherwege]

This has now been tested for mapdb, rrd4j and inmemory in combination with openhab/openhab-addons#20200

Behaviour is as expected.