Lukasz Lenart created WW-5656:
---------------------------------
Summary: 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
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)
