This is an automated email from the ASF dual-hosted git repository.
lukaszlenart pushed a commit to branch feature/struts-parameter
in repository https://gitbox.apache.org/repos/asf/struts-site.git
commit 10f8364d9fad1042f64c4a122a20d5d8ea3d3b09
Author: Lukasz Lenart <lukaszlen...@apache.org>
AuthorDate: Sun Oct 5 10:27:01 2025 +0200
Documents how to use @StrutsParameter annotation
---
source/core-developers/annotations.md | 10 ++++-
.../core-developers/struts-parameter-annotation.md | 51 ++++++++++++++++++++++
2 files changed, 59 insertions(+), 2 deletions(-)
diff --git a/source/core-developers/annotations.md
b/source/core-developers/annotations.md
index 2b186d52a..2b9c4eca7 100644
--- a/source/core-developers/annotations.md
+++ b/source/core-developers/annotations.md
@@ -15,6 +15,14 @@ parent:
In many places, applications can use Java 5 annotations as an alternative to
XML and Java properties configuration.
This page serves as a reference for all annotations across the framework.
+## Security annotation
+
+This a group of annotation used to improve security of your application.
+
+| Annotation | Description
|
+|-----------------------------------------------------------|--------------------------------------------------------------------------------------------|
+| [StrutsParameter Annotation](struts-parameter-annotation) | Marks which
fields and methods in your Action class can receive values from user requests. |
+
## Action Annotations
Since Struts 2.1, these annotations are provided by the [Convention
Plugin](../plugins/convention/). Codebehind and Zero Config
@@ -114,5 +122,3 @@ Instead tiles definitions can be created by annotating
actions.
|TilesPutListAttribute|Represents a `<put-list-attribute>` element in
tiles.xml|
|TilesAddAttribute|Represents a `<add-attribute>` element in tiles.xml|
|TilesAddListAttribute|Represents a `<add-list-attribute>` element in
tiles.xml|
-
-
diff --git a/source/core-developers/struts-parameter-annotation.md
b/source/core-developers/struts-parameter-annotation.md
new file mode 100644
index 000000000..c9d335fbb
--- /dev/null
+++ b/source/core-developers/struts-parameter-annotation.md
@@ -0,0 +1,51 @@
+---
+layout: default
+title: StrutsParameter Annotation
+parent:
+ title: Annotations
+ url: annotations.html
+---
+
+# StrutsParameter Annotation
+
+`@StrutsParameter` is a security annotation that marks which fields and
methods in your Action class can receive values from user requests.
+
+Why it matters: by default (when annotations are required), Struts will only
inject request parameters into fields or setter methods that have this
annotation. This prevents attackers from setting values on fields you didn't
intend to expose.
+
+## Usage
+
+Used to annotate public _getter/setter_ methods or _fields_ on Action classes
that are intended for parameter injection
+
+## Parameters
+
+- `depth` controls how deep into nested objects parameters can be set:
+
+## Examples
+
+```java
+public class MyAction {
+ @StrutsParameter
+ public String username; // ✅ Can receive request parameter
+
+ public String password; // ❌ Cannot receive request parameter (not
annotated)
+}
+```
+
+The `depth` controls how deep into nested objects parameters can be set:
+- `depth = 0` (default): Only sets values directly on your action
+ ```
+ @StrutsParameter
+ public String name; // Accepts: ?name=value
+ ```
+- `depth = 1`: Allows one level of nesting
+ ```
+ @StrutsParameter(depth = 1)
+ public User user; // Accepts: ?user.name=value
+ ```
+- `depth = 2`: Allows two levels of nesting
+ ```
+ @StrutsParameter(depth = 2)
+ public User user; // Accepts: ?user.address.city=value
+ ```
+
+Rule of thumb: The depth equals the number of dots (or brackets) allowed in
the parameter name.
