Sitemap DSL serialization and parsing

[mherwege]

This PR builds on #5004 and partially replaces #4945 (YAML is not covered).
It also makes further steps towards #5007

I see the following steps to take:

1. Sitemap parsing and serialization to/from a sitemap DTO matching the new sitemap registry object format. This PR covers the parsing/serialization to/from DSL.
2. Add endpoints to create/remove/edit a sitemap in this new sitemap DTO format. This should be part of this PR to make 1 relevant.
3. Convert a sitemap to/from the UIComponent sitemap format as currently used in the UI. This is required to avoid immediately changing the full UI sitemap handling. There is a lot of code there, and while it will ultimately be easier without using the UIComponent format, it should be done gradually to avoid risks. This (temporary) step is implemented in this PR.

What this will give us is a full set of new REST endpoints to manage sitemaps in the new registry format without immediately impacting the UI.

As next steps (separate PR's) I see:

4. Use the sitemap DTO in the UI instead of the UIComponent format. This will be a web PR.
5. I see two options:

• Keep the UIComponent format only for storing managed sitemaps and always translate to/from. This avoids managed sitemap storage upgrades but keeps this translation around.
• Implement a separate sitemap storage in core. Upgrade tool to move the UIComponent sitemap storage to a separate managed sitemap storage. Retire the UIComponent translation layer from core.

I have not decided on 5 yet, but I see 4 and 5 as next steps after this PR (and a YAML parsing/serialization PR).

@lolodomo This first commit in this PR is the parsing/serialization part. But as I pointed out in the other PR, without the extra work, it is still somewhat limited in its use. The REST endpoints work, but the DTO is not understood by the rest of the sitemap REST endpoints.

[Copilot]

Pull request overview

Adds infrastructure to parse/serialize sitemap DSL to/from a new sitemap DTO format, plus a temporary translation layer to/from the UIComponent sitemap representation, and exposes sitemap conversion via the existing file-format REST resource.

Changes:

• Introduces sitemap DTOs + mappers and sitemap parser/serializer SPI (SitemapParser/SitemapSerializer).
• Implements DSL sitemap parsing/serialization via a new DslSitemapConverter and updates the DSL provider behavior to support isolated parsing.
• Extends the file-format REST API to create/parse text/vnd.openhab.dsl.sitemap and wires UIComponent sitemaps as a managed provider.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/internal/components/UIComponentSitemapProvider.java	Makes UIComponent sitemap provider managed (add/update/remove/get).
bundles/org.openhab.core.ui/src/main/java/org/openhab/core/ui/internal/components/UIComponentSitemapMapper.java	Adds mapper between Sitemap model and UIComponent representation.
bundles/org.openhab.core.sitemap/src/main/java/org/openhab/core/sitemap/fileconverter/SitemapSerializer.java	Adds sitemap serializer SPI.
bundles/org.openhab.core.sitemap/src/main/java/org/openhab/core/sitemap/fileconverter/SitemapParser.java	Adds sitemap parser SPI.
bundles/org.openhab.core.sitemap/src/main/java/org/openhab/core/sitemap/fileconverter/AbstractSitemapSerializer.java	Base class for sitemap serializers.
bundles/org.openhab.core.sitemap/src/main/java/org/openhab/core/sitemap/dto/AbstractSitemapDTO.java	Adds base sitemap DTO used across REST/file-format conversion.
bundles/org.openhab.core.sitemap/src/main/java/org/openhab/core/sitemap/dto/SitemapDTO.java	Adds sitemap definition DTO including widgets list.
bundles/org.openhab.core.sitemap/src/main/java/org/openhab/core/sitemap/dto/AbstractWidgetDTO.java	Adds shared widget DTO fields for reuse.
bundles/org.openhab.core.sitemap/src/main/java/org/openhab/core/sitemap/dto/WidgetDTO.java	Adds widget definition DTO including rules/buttons/children.
bundles/org.openhab.core.sitemap/src/main/java/org/openhab/core/sitemap/dto/RuleDTO.java	Adds rule DTO (conditions + argument).
bundles/org.openhab.core.sitemap/src/main/java/org/openhab/core/sitemap/dto/ConditionDTO.java	Adds condition DTO.
bundles/org.openhab.core.sitemap/src/main/java/org/openhab/core/sitemap/dto/MappingDTO.java	Moves/defines mapping DTO in sitemap bundle.
bundles/org.openhab.core.sitemap/src/main/java/org/openhab/core/sitemap/dto/ButtonDefinitionDTO.java	Adds buttongrid button definition DTO.
bundles/org.openhab.core.sitemap/src/main/java/org/openhab/core/sitemap/dto/SitemapDTOMapper.java	Adds bidirectional mapping between model Sitemap and DTOs.
bundles/org.openhab.core.model.sitemap/src/org/openhab/core/model/sitemap/internal/fileconverter/DslSitemapConverter.java	Implements DSL sitemap parsing/serialization using ModelRepository.
bundles/org.openhab.core.model.sitemap/src/org/openhab/core/model/sitemap/internal/DslSitemapProvider.java	Refactors DSL sitemap provider caching/notifications for model-based + isolated parsing use.
bundles/org.openhab.core.model.sitemap/src/org/openhab/core/model/sitemap/formatting/SitemapIndentationInformation.java	Sets DSL formatter indentation to 2 spaces.
bundles/org.openhab.core.model.sitemap/src/org/openhab/core/model/sitemap/formatting/SitemapFormatter.xtend	Adds formatting rules for sitemap DSL output.
bundles/org.openhab.core.model.sitemap/src/org/openhab/core/model/sitemap/SitemapStandaloneSetup.xtend	Caches Xtext injector to reuse setup.
bundles/org.openhab.core.model.sitemap/src/org/openhab/core/model/sitemap/SitemapRuntimeModule.xtend	Binds formatter + indentation info in runtime module.
bundles/org.openhab.core.model.sitemap/bnd.bnd	Adds sitemap fileconverter package import.
bundles/org.openhab.core.io.rest.sitemap/src/main/java/org/openhab/core/io/rest/sitemap/internal/WidgetDTO.java	Reuses shared widget DTO fields by extending AbstractWidgetDTO.
bundles/org.openhab.core.io.rest.sitemap/src/main/java/org/openhab/core/io/rest/sitemap/internal/SitemapDTO.java	Reuses shared sitemap DTO fields by extending AbstractSitemapDTO.
bundles/org.openhab.core.io.rest.sitemap/src/main/java/org/openhab/core/io/rest/sitemap/internal/SitemapResource.java	Adjusts mapping handling to account for DTO field refactor.
bundles/org.openhab.core.io.rest.core/src/main/java/org/openhab/core/io/rest/core/internal/fileformat/FileFormatResource.java	Adds sitemap DSL create/parse endpoints and registry-based sitemap serialization.
bundles/org.openhab.core.io.rest.core/src/main/java/org/openhab/core/io/rest/core/fileformat/FileFormatDTO.java	Extends file-format JSON DTO to include sitemaps.
bundles/org.openhab.core.io.rest.core/pom.xml	Adds dependency on org.openhab.core.sitemap for DTOs/mappers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 27 out of 27 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated 8 comments.

Comments suppressed due to low confidence (1)

bundles/org.openhab.core.model.sitemap/src/org/openhab/core/model/sitemap/internal/DslSitemapProvider.java:403

• modelChanged now parses and caches all .sitemap models, including isolated models created via ModelRepository.createIsolatedModel(...) (names start with ModelCoreConstants.PREFIX_TMP_MODEL). Because getAll()/getSitemapNames()/getSitemap() read from sitemapCache, isolated parses can temporarily leak into the SitemapRegistry, violating SitemapParser's contract (“without impacting the sitemap registry”) and potentially shadowing real sitemaps with the same name. Exclude isolated models from registry-visible APIs and from listener notifications (or keep a separate cache for isolated models only used by getAllFromModel).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[lolodomo]

Review of io.rest.core and io/rest.sitemap bundles

[lolodomo]

Review of model.sitemap bundle

[lolodomo]

@mherwege : I cannot mark comments as resolved, can you please do it for all those with my comment "OK" or "Done" ?

[mherwege]

@mherwege : I cannot mark comments as resolved, can you please do it for all those with my comment "OK" or "Done" ?

@lolodomo Done.

The code is now working as expected as far as I can see. The new sitemap endpoints allow adding, removing and updating managed sitemaps and update the UIComponentRegistry correctly, so are visible as managed sitemaps in the UI. Unmanaged sitemaps are still not visible, but that would be a next step in the UI code.
The file conversions are working.

I will go through the code one more time and have copilot do one or more reviews before I take this out of Draft.

[lolodomo]

Review of core.sitemap bundle

[mherwege]

@lolodomo I believe this is all good now. copilot is not able to come up with meaningful remarks anymore, so from my perspective this is ready.

[lolodomo]

@lolodomo I believe this is all good now. copilot is not able to come up with meaningful remarks anymore, so from my perspective this is ready.

Still few things to adjust.
My review is finished.

[mherwege]

@lolodomo I made a few changes, but also commented on some of your remarks where I believe there is no issue. Can you check again? Thanks for all your effort reviewing this.

[lolodomo]

Final comments

[lolodomo]

LGTM, thank you Mark.

[lolodomo]

@openhab/core-maintainers : could we have your attention please ? This is the second step (after the sitemap registry) and we are already working on next steps (Mark to update Main UI and finally expose new features to users and myself to add the new YAML format).

[lolodomo]

@mherwege : can you please fix the signature of this method, @nullable is missing for the parameter (while present in the implementation)
void setService(@Nullable String service);

https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.sitemap/src/main/java/org/openhab/core/sitemap/Chart.java#L39

https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.sitemap/src/main/java/org/openhab/core/sitemap/internal/ChartImpl.java#L47

Edit: For all, it is not a requirement for a change in that PR, it can be fixed in a separate PR. I can even fix it in my own PR. What I mean is that it should not delay the merge.

[mherwege]

@lolodomo I pushed the fix here.

There is another thing I was thinking of. The validation checks for minValue < maxValue only work if both are set. The documentation says if these are not set, they will default to 0 and 100. This does not happen in the sitemap model or core sitemap code, so I assume this happens when rendering.
But that raises the question if we should not extend that check to also check against these default 0 and 100 values. And maybe even move these defaults to the core sitemap code.
This should not be done in this PR, but something to consider.

[mherwege]

@lolodomo I have another question about Mapview validation. The current code (before and after this PR) has the item as required for Mapview. However, the documentation shows it as optional (no further comment on it). Would UI's support this being optional? If none provided, it would just show a map? Or do we adjust the documentation?

[lolodomo]

@holgerfriedrich @kaikreuzer : is it possible to merge that PR so that we can make progress ?
Don't know if it has any value but I fully reviewed the code and this looks very good to me. I can even say that I have tested it while working on next steps.