[
https://issues.apache.org/jira/browse/WW-5656?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Lukasz Lenart updated WW-5656:
------------------------------
Description:
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.
h2. Final step
Create a ticket to remove these deprecated elements with the next major release
was:
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.
> 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.
> h2. Final step
> Create a ticket to remove these deprecated elements with the next major
> release
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
