This is an automated email from the ASF dual-hosted git repository. lukaszlenart pushed a commit to branch docs/struts-7-5-configuration-grammar in repository https://gitbox.apache.org/repos/asf/struts-intellij-plugin.git
commit d9d8213d87c2497b3773cac98132fe2059f1f946 Author: Lukasz Lenart <[email protected]> AuthorDate: Wed Nov 11 09:55:41 2026 +0100 docs: specify Struts 6.5 and 7.5 configuration grammar Record the agreed DTD, DOM, and file-template design for issue 147 so the editor can accept the published 7.5 struts.xml syntax. Co-authored-by: Cursor <[email protected]> --- ...1-11-struts-7-5-configuration-grammar-design.md | 195 +++++++++++++++++++++ 1 file changed, 195 insertions(+) diff --git a/docs/superpowers/specs/2026-11-11-struts-7-5-configuration-grammar-design.md b/docs/superpowers/specs/2026-11-11-struts-7-5-configuration-grammar-design.md new file mode 100644 index 0000000..42c8d82 --- /dev/null +++ b/docs/superpowers/specs/2026-11-11-struts-7-5-configuration-grammar-design.md @@ -0,0 +1,195 @@ +# Struts 6.5 and 7.5 Configuration Grammar + +**Date:** 2026-11-11 +**Status:** Pending review +**Issue:** https://github.com/apache/struts-intellij-plugin/issues/147 + +## Problem + +Struts 7.5.0 publishes new `struts.xml` grammar. The plugin bundles configuration DTDs through `struts-6.0.dtd`, so a 6.5 or 7.5 DOCTYPE is unrecognized and the new syntax is invalid in the editor. + +The published catalog is https://struts.apache.org/dtds/. Compared with the bundled 6.0 DTD: + +- `struts-6.5.dtd` adds `final` on `<package>`. +- `struts-7.5.dtd` adds `final` and `extension` on `<package>`, `<scoped-constant name value>`, and `http-method` and `extension` on `<action>`. + +Release notes: https://cwiki.apache.org/confluence/spaces/WW/pages/462816288/Version+Notes+7.5.0 + +## Goals + +1. Validate files that use the published 6.5 and 7.5 DOCTYPEs against bundled copies of those DTDs. +2. Complete and check `<scoped-constant>`, `http-method`, `extension`, and `final`. +3. Select the 6.5 or 7.5 DOCTYPE for a new `struts.xml` from the detected `struts2-core` version, using the table in File Templates. +4. Keep the change static, in the existing DTD, DOM, and file-template paths. + +## Non-Goals + +- OGNL property resolution and the `@StrutsParameter` inspection. +- Tag libraries and validators. Those already come from the Struts JAR on the classpath. +- Struts 1, Tiles, and XWork DTDs on the same catalog. +- Reading `ScopableConstants` implementations from the classpath. +- Rewriting the DOCTYPE of an existing `struts.xml`. + +## Decision + +Use a static DTD and DOM update, the same style as the 7.2.1 constant metadata. + +One DOM model serves every DTD version. The bundled DTD for a file decides whether the new syntax is legal in that file. Completion is not switched per DTD version. + +## Alternatives Considered + +### DTD registration only + +Bundle and register the two files so DOCTYPE checks and XML validation accept 6.5 and 7.5 documents. Leave the DOM unchanged. + +Rejected because `http-method`, `extension`, and `<scoped-constant>` would get no value completion or semantic checks. + +### Classpath discovery for scopable names + +Read `<scoped-constant>` names from `ScopableConstants` beans in the module's Struts JAR. + +Rejected because the built-in set has three names, and the rest of the plugin's constants are static lists. + +## DTD Registration + +Copy these files from https://struts.apache.org/dtds/ unchanged into `src/main/resources/resources/dtds/`: + +- `struts-6.5.dtd` +- `struts-7.5.dtd` + +Register each system URI and public ID in `StrutsConstants` and `Struts2ResourceProvider`. Add the `https` URIs to `StrutsConstants.STRUTS_DTDS`. + +| File | System URI | Public ID | +|---|---|---| +| `struts-6.5.dtd` | `https://struts.apache.org/dtds/struts-6.5.dtd` | `-//Apache Software Foundation//DTD Struts Configuration 6.5//EN` | +| `struts-7.5.dtd` | `https://struts.apache.org/dtds/struts-7.5.dtd` | `-//Apache Software Foundation//DTD Struts Configuration 7.5//EN` | + +An `http://` URI for either file is reported as "use https" by the existing `http://struts.apache.org/dtds/struts-` prefix check in `StrutsDtdValidator`. + +## File Templates + +Add `struts_6_5.xml.ft` and `struts_7_5.xml.ft` under `src/main/resources/fileTemplates/j2ee/`, beside `struts_6_0.xml.ft`, plus a matching `.html` description for each. The descriptor names registered in `StrutsFileTemplateGroupDescriptorFactory` are `struts_6_5.xml` and `struts_7_5.xml`. Each template body is an empty `<struts>` document with the DOCTYPE from the table above. + +`StrutsFileTemplateProvider` selects a template from the `struts2-core` version detected in the module. The detected value is a Maven version such as `6.5.0` or `7.5.0`. The existing `isNewerThan` helper is a strict greater-than, so the new steps use an inclusive comparison and the boundary versions match. + +The mapping from a version string to a template name is a package-visible method on `StrutsFileTemplateProvider`. `determineFileTemplate` calls that method and then loads the J2EE template. + +| Detected version | Template | +|---|---| +| At least 7.5, including 7.5.0, 7.6, and 8.0 | `struts_7_5.xml` | +| At least 6.5 and below 7.0, including 6.5.0 and 6.6 | `struts_6_5.xml` | +| Above 6.0 and below 6.5, and from 7.0.0 through 7.4.x | `struts_6_0.xml`, unchanged | +| Older than the 6.0 step | The existing older templates, unchanged | +| No version detected | The current fallback, unchanged | + +There is no `struts-7.0.dtd`. Modules on 7.0.0 through 7.4.x keep the 6.0 template they get today. + +## DOM + +`StrutsPackage` gains: + +- `final`, a boolean attribute, the same as `abstract`. An omitted `final` means the package is not final. +- `extension`, a comma-separated string. +- a list of `<scoped-constant>` children. + +`Action` gains: + +- `http-method`, a comma-separated string. +- `extension`, a comma-separated string. + +`<scoped-constant>` is a new element with required `name` and `value`, the same shape as `<constant>`. Required `name` and `value` use the normal DOM required-attribute check. Omitted optional attributes stay valid. + +## Checks + +### Final parent + +When `extends` resolves to one or more packages and any resolved parent has `final` true, highlight that `extends` value. Struts rejects that parent at startup with "Parent package is final and unextendable". An unresolved parent stays with the existing `extends` resolver. + +`Struts2ModelInspectionVisitor` reports this when it visits the package. + +### Scoped constant + +Name completion is this static set intersected with the constants already registered for the module: + +- `struts.ui.theme` +- `struts.ui.templateDir` +- `struts.convention.result.path`, only when the Convention contributor is active for that module + +`value` uses the existing constant-value converter. For `struts.ui.theme` that offers `simple`, `xhtml`, `css_xhtml`, `html5`, and deprecated `ajax`. `struts.ui.templateDir` and `struts.convention.result.path` stay free text. + +A name outside the scopable set is highlighted. A name registered only by a custom `ScopableConstants` bean is outside the set, so it is highlighted too. + +### HTTP method + +Completion offers `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `TRACE`, `OPTIONS`, `CONNECT`, and `PATCH`. The list is comma-separated, in the same converter style as `allowed-methods`. A token matches one of those nine names ignoring case. Any other token is highlighted. + +### Extension + +The same comma-separated rules apply on `<package>` and `<action>`. There is no fixed completion list. The tokens are application-specific, such as `action`, `do`, or an empty token for an extensionless URL. + +Split on `,` and do not trim. A token is highlighted when it starts with `.`, contains `/`, or contains whitespace. An empty token is valid, including a trailing comma that produces one. + +## Data Flow + +```text +struts.xml DOCTYPE system id + | + v +Struts2ResourceProvider --> bundled struts-6.5.dtd or struts-7.5.dtd + | + v +StrutsDtdValidator accepts the same https URI + +<scoped-constant>, http-method, extension + | + v +DOM converters --> completion variants and unresolved tokens + +<package extends="..."> + | + v +Struts2ModelInspectionVisitor highlights a resolved final parent + +Create struts.xml + | + v +detected struts2-core version --> struts_6_5.xml or struts_7_5.xml +``` + +## Testing + +Add cases to the existing test classes. Highlighting fixtures use the `<error descr="...">` style already used for `allowed-methods`. + +`StrutsDtdValidatorTest`: + +- The 6.5 and 7.5 `https` URIs are `OK`. +- The `http://` form of each is `HTTP_INSTEAD_OF_HTTPS`. + +`StrutsHighlightingTest`: + +- Extending a `final` package is highlighted. +- An unknown `<scoped-constant>` name is highlighted, and `struts.ui.theme` is clean. +- An unknown `http-method` token is highlighted, and `post` is clean. +- An `extension` token with a leading `.`, a `/`, or whitespace is highlighted, and an empty token is clean. + +`StrutsCompletionTest`, in the default fixture where the Convention contributor is inactive: + +- `http-method` offers the nine methods. +- A scoped-constant name offers `struts.ui.theme` and `struts.ui.templateDir`, and does not offer `struts.convention.result.path`. +- The value for `struts.ui.theme` offers `simple`, `xhtml`, `css_xhtml`, `html5`, and `ajax`. + +`StrutsFileTemplateProviderTest` calls the package-visible version mapping directly, with no fake JAR: + +- `6.4.0` and `7.4.0` stay on the 6.0 template. +- `6.5.0` selects the 6.5 template. +- `7.5.0` and `7.6.0` select the 7.5 template. +- A missing version keeps today's fallback. + +`CHANGELOG.md` gets an unreleased note for the 6.5 and 7.5 DTD and DOM support. + +Run the focused tests, then the suite: + +```bash +./gradlew test -x rat --tests "StrutsDtdValidatorTest" --tests "StrutsHighlightingTest" --tests "StrutsCompletionTest" --tests "StrutsFileTemplateProviderTest" +./gradlew test -x rat +```
