[jira] [Work started] (WW-5656) Mark ConversionRule.COLLECTION and the Collection_ prefix as @Deprecated

["Lukasz Lenart (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/WW-5656?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Work on WW-5656 started by Lukasz Lenart.
-----------------------------------------
> Mark ConversionRule.COLLECTION and the Collection_ prefix as @Deprecated
> ------------------------------------------------------------------------
>
>                 Key: WW-5656
>                 URL: https://issues.apache.org/jira/browse/WW-5656
>             Project: Struts 2
>          Issue Type: Improvement
>          Components: XML Validators
>            Reporter: Lukasz Lenart
>            Assignee: Lukasz Lenart
>            Priority: Minor
>             Fix For: 7.3.0
>
>
> h2. Summary
> {{ConversionRule.COLLECTION}} and {{DefaultObjectTypeDeterminer.DEPRECATED_ELEMENT_PREFIX}} ({{"Collection_"}}) have been documented as deprecated since WebWork 2.1.x, but neither carries an actual {{@Deprecated}} annotation. Users get no compile-time signal — only prose in Javadoc and an {{INFO}} log line at runtime, and the log fires only when the fallback is actually hit.
> h2. Background
> {{Collection_}} and {{Element_}} express the same thing: the element type inside a collection. {{Element_}} additionally covers the *values* of a {{Map}}, which is why WebWork 2.1 introduced it as the single name for both cases and kept {{Collection_}} working as a fallback so existing {{-conversion.properties}} files would not break.
> The deprecation is stated in three places today:
> * {{DefaultObjectTypeDeterminer}} class Javadoc, line 50: _"From WebWork 2.1.x, the *Collection_xxx* format is still supported and honored, although it is deprecated"_
> * {{DefaultObjectTypeDeterminer:120}} — {{LOG.info("The Collection_xxx pattern for collection type conversion is deprecated. Please use Element_xxx!")}}
> * {{TypeConversion.rule()}} Javadoc — _"The ConversionRule can be a PROPERTY, KEY, KEY_PROPERTY, ELEMENT, COLLECTION (deprecated) or a MAP"_
> The two rules are interchangeable in the engine: {{DefaultConversionAnnotationProcessor}} handles {{ELEMENT}} and {{COLLECTION}} in the same branch, and {{DefaultObjectTypeDeterminer.getElementClass}} reads {{Element_${property}}} first, then falls back to {{Collection_${property}}}.
> h2. Proposal
> Make the deprecation machine-visible so it reaches users through the compiler rather than through documentation nobody reads.
> {code:java}
> public enum ConversionRule {
>     PROPERTY,
>     /**
>      * @deprecated since 7.3.0, use {@link #ELEMENT} instead. The Collection_xxx key format has been
>      * superseded by Element_xxx since WebWork 2.1.x; both are handled identically by the engine.
>      */
>     @Deprecated(since = "7.3.0")
>     COLLECTION,
>     MAP, KEY, KEY_PROPERTY, ELEMENT, CREATE_IF_NULL;
> {code}
> Same treatment for {{DefaultObjectTypeDeterminer.DEPRECATED_ELEMENT_PREFIX}}, whose name already says what the annotation should.
> h3. Scope
> || Item || Change ||
> | {{ConversionRule.COLLECTION}} | add {{@Deprecated}} + {{@deprecated}} Javadoc pointing at {{ELEMENT}} |
> | {{DefaultObjectTypeDeterminer.DEPRECATED_ELEMENT_PREFIX}} | add {{@Deprecated}} + Javadoc |
> | {{TypeConversion}} Javadoc example, line 138 | switch the example from {{ConversionRule.COLLECTION}} to {{ConversionRule.ELEMENT}} so the annotation stops teaching the deprecated form |
> | Runtime behaviour | *unchanged* — the {{Collection_}} fallback keeps working |
> h3. In-tree call sites that will warn
> Deprecating the constant makes our own code warn, so each of these needs a decision — {{@SuppressWarnings("deprecation")}} where the reference is deliberate, or a migration to {{ELEMENT}} where it is incidental:
> * {{ConversionRule.prefix()}} — {{case COLLECTION -> DEPRECATED_ELEMENT_PREFIX}}. Both sides are deprecated references, and the switch is deliberately exhaustive with no {{default}}, so the case *cannot* be dropped without a compile error. Needs {{@SuppressWarnings("deprecation")}}.
> * {{DefaultConversionAnnotationProcessor:73}} — references {{ConversionRule.COLLECTION}} in a guard.
> * {{DefaultConversionFileProcessor:80}} and {{DefaultObjectTypeDeterminer:118}} — reference the prefix constant.
> * Test fixtures {{AnnotationUser:87}} and {{ConversionTestAction:74}} use {{rule = ConversionRule.COLLECTION}}. These deliberately cover the deprecated path and should keep doing so, with a suppression and a comment saying why.
> * {{ConversionRuleTest:31}} and {{XWorkConverterTest:845}} assert on the {{Collection_}} prefix and on the {{COLLECTION}}/{{ELEMENT}} key crossover (see WW-3871) — both must keep passing.
> h2. Open questions
> * *{{forRemoval}} or not?* Removing the enum constant is a source-breaking change for applications, so it belongs in a major release. Removing the {{Collection_}} *properties-file* fallback is a separate, larger decision — plenty of long-lived {{-conversion.properties}} files still use it, and it costs almost nothing to keep. These two can be decided independently; deprecating without {{forRemoval = true}} is the conservative first step.
> * *{{since}} value* — the version is chosen at release time by semver impact; {{7.3.0}} above is a placeholder matching the branch that surfaced this.
> h2. Notes
> Found while implementing WW-3871, which routes every {{@TypeConversion}} key through a single prefix resolver. That work has to treat {{Collection_}} as a first-class prefix precisely because {{COLLECTION}} and {{ELEMENT}} are interchangeable — {{@TypeConversion(key = "Element_users", rule = COLLECTION)}} is a legitimate combination today and must keep resolving to {{Element_users}}. Deprecating the constant does not change that; it only tells authors not to write new code against it.
> This is a documentation and API-hygiene change with no behavioural component.



--
This message was sent by Atlassian Jira
(v8.20.10#820010)