This is an automated email from the ASF dual-hosted git repository.
asf-gitbox-commits pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/struts-site.git
The following commit(s) were added to refs/heads/asf-site by this push:
new cbf7eb411 Automatic Site Publish by Buildbot
cbf7eb411 is described below
commit cbf7eb4118eb33e860797ec433c9595dce4ebd98
Author: buildbot <[email protected]>
AuthorDate: Sat Jul 25 07:26:23 2026 +0000
Automatic Site Publish by Buildbot
---
.../struts-parameter-annotation.html | 20 +++++++
output/plugins/json/index.html | 65 ++++++++++++++++++++++
2 files changed, 85 insertions(+)
diff --git a/output/core-developers/struts-parameter-annotation.html
b/output/core-developers/struts-parameter-annotation.html
index 7851c8912..8e744184e 100644
--- a/output/core-developers/struts-parameter-annotation.html
+++ b/output/core-developers/struts-parameter-annotation.html
@@ -308,6 +308,26 @@ collection or map needs <code class="language-plaintext
highlighter-rouge">depth
<span class="o">}</span>
</code></pre></div></div>
+<p>This covers the case where the whole collection is assigned at once (name
+<code class="language-plaintext highlighter-rouge">mySelection</code>, <code
class="language-plaintext highlighter-rouge">depth = 0</code>), as a checkbox
list submits it.</p>
+
+<p>When the collection is instead populated <strong>element by
element</strong> through indexed
+names — <code class="language-plaintext
highlighter-rouge">mySelection[0]</code>, <code class="language-plaintext
highlighter-rouge">mySelection[1]</code> — the annotation must be on the
+<strong>getter</strong> with <code class="language-plaintext
highlighter-rouge">depth = 1</code>, because each element path contains one
bracket. This
+is how JSON and REST payloads bind a collection of simple types: a body such as
+<code class="language-plaintext
highlighter-rouge">{"mySelection":["A","B"]}</code> populates <code
class="language-plaintext highlighter-rouge">mySelection[0]</code> and <code
class="language-plaintext highlighter-rouge">mySelection[1]</code>, so
+the getter must be annotated for the elements to be accepted.</p>
+<div class="language-java highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">MyAction</span> <span
class="o">{</span>
+ <span class="kd">private</span> <span class="nc">List</span><span
class="o"><</span><span class="nc">String</span><span class="o">></span>
<span class="n">mySelection</span><span class="o">;</span>
+
+ <span class="nd">@StrutsParameter</span><span class="o">(</span><span
class="n">depth</span> <span class="o">=</span> <span class="mi">1</span><span
class="o">)</span>
+ <span class="kd">public</span> <span class="nc">List</span><span
class="o"><</span><span class="nc">String</span><span class="o">></span>
<span class="nf">getMySelection</span><span class="o">()</span> <span
class="o">{</span>
+ <span class="k">return</span> <span class="n">mySelection</span><span
class="o">;</span>
+ <span class="o">}</span>
+ <span class="c1">// ... setter</span>
+<span class="o">}</span>
+</code></pre></div></div>
+
<p>When populating properties of objects that are already in a collection,
annotate the
getter. Because reaching an element’s property requires indexing into the
collection
<em>and then</em> following the property, this needs <code
class="language-plaintext highlighter-rouge">depth = 2</code> (see
diff --git a/output/plugins/json/index.html b/output/plugins/json/index.html
index 43f07cc62..efe51fe41 100644
--- a/output/plugins/json/index.html
+++ b/output/plugins/json/index.html
@@ -183,6 +183,7 @@
<li><a href="#accepting-json" id="markdown-toc-accepting-json">Accepting
JSON</a></li>
<li><a href="#deserialization-limits"
id="markdown-toc-deserialization-limits">Deserialization limits</a></li>
<li><a href="#parameter-authorization"
id="markdown-toc-parameter-authorization">Parameter authorization</a></li>
+ <li><a href="#input-parameter-filtering"
id="markdown-toc-input-parameter-filtering">Input parameter filtering</a></li>
</ul>
</li>
<li><a href="#json-rpc" id="markdown-toc-json-rpc">JSON RPC</a></li>
@@ -816,6 +817,70 @@ annotation <strong>per property, during
deserialization</strong> — unauthorize
never set on the target object. Annotate the action properties that may be
populated from the JSON request body.</p>
+<h3 id="input-parameter-filtering">Input parameter filtering</h3>
+
+<p>Since Struts 7.3.0, populating an action from a JSON request body applies
the
+same name/value acceptability controls that the
+<a href="../../core-developers/parameters-interceptor.html">Parameters
Interceptor</a>
+applies to ordinary HTTP request parameters. Filtering uses the same
+dotted/indexed key paths as form parameters (<code class="language-plaintext
highlighter-rouge">address.city</code>, <code class="language-plaintext
highlighter-rouge">items[0].name</code>),
+so the shared pattern checkers behave identically on JSON and form input.
+Population itself stays pure reflection over bean setters — no OGNL name
+evaluation is introduced on the JSON path.</p>
+
+<p>The following controls are <strong>always on</strong>:</p>
+
+<ul>
+ <li><strong>Excluded and accepted name patterns</strong> — the same
framework-wide
+accepted/excluded parameter-name patterns the Parameters Interceptor uses. A
+JSON key whose full dotted/indexed path matches an excluded pattern, or fails
+to match any accepted pattern, is not populated.</li>
+ <li><strong>Maximum key-path length</strong> — set with the <code
class="language-plaintext highlighter-rouge">paramNameMaxLength</code>
interceptor
+param (default <code class="language-plaintext highlighter-rouge">100</code>).
JSON keys whose full dotted path is longer are rejected.</li>
+ <li><strong><code class="language-plaintext
highlighter-rouge">ParameterNameAware</code> / <code class="language-plaintext
highlighter-rouge">ParameterValueAware</code></strong> action callbacks —
honored for
+JSON input exactly as for form parameters.</li>
+ <li><strong><code class="language-plaintext
highlighter-rouge">@StrutsParameter</code> authorization</strong> — see
+<a href="#parameter-authorization">Parameter authorization</a> above.</li>
+</ul>
+
+<p>The following controls are <strong>opt-in</strong> — disabled by default to
preserve existing
+behavior for permissive JSON apps:</p>
+
+<table>
+ <thead>
+ <tr>
+ <th>Interceptor param</th>
+ <th>Default</th>
+ <th>Effect</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code class="language-plaintext
highlighter-rouge">acceptedValuePatterns</code></td>
+ <td><em>(none)</em></td>
+ <td>Comma-delimited regular expressions; when set, only JSON leaf
<strong>values</strong> matching one of them are accepted (matching is
case-insensitive).</td>
+ </tr>
+ <tr>
+ <td><code class="language-plaintext
highlighter-rouge">excludedValuePatterns</code></td>
+ <td><em>(none)</em></td>
+ <td>Comma-delimited regular expressions; JSON leaf
<strong>values</strong> matching any of them are removed (matching is
case-insensitive).</td>
+ </tr>
+ <tr>
+ <td><code class="language-plaintext
highlighter-rouge">applyPropertyFiltersToInput</code></td>
+ <td><code class="language-plaintext highlighter-rouge">false</code></td>
+ <td>When <code class="language-plaintext highlighter-rouge">true</code>,
the interceptor’s own <code class="language-plaintext
highlighter-rouge">excludeProperties</code> / <code class="language-plaintext
highlighter-rouge">includeProperties</code> patterns — otherwise used only for
serialization output — also gate which JSON keys are populated on
<strong>input</strong>.</td>
+ </tr>
+ </tbody>
+</table>
+
+<div class="language-xml highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nt"><interceptor-ref</span> <span
class="na">name=</span><span class="s">"json"</span><span class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span
class="s">"paramNameMaxLength"</span><span class="nt">></span>120<span
class="nt"></param></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span
class="s">"acceptedValuePatterns"</span><span
class="nt">></span>[\w\s.@-]+<span class="nt"></param></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span
class="s">"applyPropertyFiltersToInput"</span><span
class="nt">></span>true<span class="nt"></param></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span
class="s">"excludeProperties"</span><span
class="nt">></span>login.password<span class="nt"></param></span>
+<span class="nt"></interceptor-ref></span>
+</code></pre></div></div>
+
<h2 id="json-rpc">JSON RPC</h2>
<p>The json plugin can be used to execute action methods from javascript and
return the output. This feature was developed
