This is an automated email from the ASF dual-hosted git repository. lukaszlenart pushed a commit to branch docs/struts-7.3.0-content-audit in repository https://gitbox.apache.org/repos/asf/struts-site.git
commit 690aa24dd16c6af9baae34a04626dfeb8efac171 Author: Lukasz Lenart <[email protected]> AuthorDate: Mon Aug 3 07:31:46 2026 +0200 docs: document @TypeConversion key derivation and ConversionRule.COLLECTION deprecation WW-3871: @TypeConversion accepts a bare property name in `key` for every ConversionRule at class, method and field level — the rule prefix is derived. The annotation is now also valid on fields (@Target METHOD, FIELD). WW-5656: ConversionRule.COLLECTION and the Collection_ prefix are deprecated since 7.3.0 in favour of ConversionRule.ELEMENT / Element_. Co-Authored-By: Claude Opus 5 <[email protected]> --- .../core-developers/type-conversion-annotation.md | 30 ++++++++++++++++++++-- source/core-developers/type-conversion.md | 5 +++- 2 files changed, 32 insertions(+), 3 deletions(-) diff --git a/source/core-developers/type-conversion-annotation.md b/source/core-developers/type-conversion-annotation.md index 26aacdd1e..56fad7e72 100644 --- a/source/core-developers/type-conversion-annotation.md +++ b/source/core-developers/type-conversion-annotation.md @@ -23,7 +23,28 @@ This annotation is used for class and application wide conversion rules. ## Usage -The `TypeConversion` annotation can be applied at property and method level. +The `TypeConversion` annotation can be applied at method level, and since Struts 7.3.0 also at field level. + +## Key derivation + +> Since Struts 7.3.0 + +The `key` parameter accepts a bare property name for every `ConversionRule`; the rule's prefix is derived +automatically. It used to be derived only for method-level annotations, so class-level `@Conversion(conversions = ...)` +entries had to spell the prefix out: + +```java +// before Struts 7.3.0 — prefix spelled out +@Conversion(conversions = @TypeConversion(key = "CreateIfNull_users", rule = ConversionRule.CREATE_IF_NULL, value = "true")) + +// since Struts 7.3.0 — the CreateIfNull_ prefix is derived +@Conversion(conversions = @TypeConversion(key = "users", rule = ConversionRule.CREATE_IF_NULL, value = "true")) +``` + +Existing annotations that already carry a prefix keep working: a `key` starting with any known rule prefix is used +as-is, never prefixed twice. The prefixes are `CreateIfNull_`, `Element_`, `Key_` and `KeyProperty_`; +`ConversionRule.PROPERTY` and `ConversionRule.MAP` have no prefix of their own. Keys of +`ConversionType.APPLICATION` annotations are class names and are never prefixed. ## Parameters @@ -78,6 +99,11 @@ The `TypeConversion` annotation can be applied at property and method level. </p> +`ConversionRule.COLLECTION` is deprecated since Struts 7.3.0 — use `ConversionRule.ELEMENT` instead. The two are handled +identically by the engine, and `ELEMENT` additionally covers the values of a `Map`. Existing annotations using +`COLLECTION` keep working and produce the deprecated `Collection_xxx` key, which is still read as a fallback. +{:.alert .alert-warning} + ## Examples ```java @@ -103,7 +129,7 @@ The `TypeConversion` annotation can be applied at property and method level. this.convertDouble = convertDouble; } - @TypeConversion(rule = ConversionRule.COLLECTION, converterClass = String.class) + @TypeConversion(rule = ConversionRule.ELEMENT, converterClass = String.class) @StrutsParameter public void setUsers( List users ) { this.users = users; diff --git a/source/core-developers/type-conversion.md b/source/core-developers/type-conversion.md index f52d61ef6..d7464cf5e 100644 --- a/source/core-developers/type-conversion.md +++ b/source/core-developers/type-conversion.md @@ -226,7 +226,10 @@ contained within Maps and Collections. For Collections, such as Lists, the eleme and the value may be specified by using the pattern `Key_xxx` and `Element_xxx`, respectively. From WebWork 2.1.x, the `Collection_xxx` format is still supported and honored, although it is deprecated and will be -removed eventually. +removed eventually. Since Struts 7.3.0 the matching `ConversionRule.COLLECTION` enum constant used by the +[TypeConversion Annotation](type-conversion-annotation) is marked `@Deprecated` as well — use `ConversionRule.ELEMENT`, +which produces the current `Element_xxx` key and additionally covers the values of a `Map`. +{:.alert .alert-warning} Additionally, you can create your own custom `ObjectTypeDeterminer` by implementing the `ObjectTypeDeterminer` interface. There is also an optional `ObjectTypeDeterminer` that utilizes Java 5 generics. See the [Annotations](annotations)
