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 f93626a19a Automatic Site Publish by Buildbot
f93626a19a is described below
commit f93626a19a320cedeab69f33d6af5d9db8dfacb0
Author: buildbot <[email protected]>
AuthorDate: Sat Oct 10 10:50:50 2026 +0000
Automatic Site Publish by Buildbot
---
output/plugins/json/index.html | 43 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 43 insertions(+)
diff --git a/output/plugins/json/index.html b/output/plugins/json/index.html
index 148bd3f269..67e66cf4ca 100644
--- a/output/plugins/json/index.html
+++ b/output/plugins/json/index.html
@@ -167,6 +167,7 @@
<li><a href="#base-classes" id="markdown-toc-base-classes">Base
Classes</a></li>
<li><a href="#enumerations"
id="markdown-toc-enumerations">Enumerations</a></li>
<li><a href="#java-records-and-optional"
id="markdown-toc-java-records-and-optional">Java records and Optional</a></li>
+ <li><a href="#using-registered-type-converters"
id="markdown-toc-using-registered-type-converters">Using registered type
converters</a></li>
<li><a href="#compressing-the-output"
id="markdown-toc-compressing-the-output">Compressing the output</a></li>
<li><a href="#preventing-the-browser-from-caching-the-response"
id="markdown-toc-preventing-the-browser-from-caching-the-response">Preventing
the browser from caching the response</a></li>
<li><a href="#excluding-properties-with-null-values"
id="markdown-toc-excluding-properties-with-null-values">Excluding properties
with null values</a></li>
@@ -522,6 +523,48 @@ therefore subject to <code class="language-plaintext
highlighter-rouge">excludeN
<div class="language-json highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="p">{</span><span
class="nl">"name"</span><span class="p">:</span><span class="w"> </span><span
class="s2">"Alice"</span><span class="p">,</span><span class="w"> </span><span
class="nl">"nickname"</span><span class="p">:</span><span class="w">
</span><span class="kc">null</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
+<h3 id="using-registered-type-converters">Using registered type converters</h3>
+
+<blockquote>
+ <p>Since Struts 7.5.0</p>
+</blockquote>
+
+<p>A value type that has an <a
href="../../core-developers/type-conversion.html#applying-a-type-converter-for-an-application">application-wide
type converter</a>
+can be serialized with that converter instead of as a nested bean, so the JSON
response shows the same string as
+the HTML view. This is off by default; enable it with a constant:</p>
+
+<div class="language-xml highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nt"><constant</span> <span
class="na">name=</span><span
class="s">"struts.json.writer.useTypeConverters"</span> <span
class="na">value=</span><span class="s">"true"</span><span
class="nt">/></span>
+</code></pre></div></div>
+
+<p>With a converter registered in <code class="language-plaintext
highlighter-rouge">struts-conversion.properties</code>:</p>
+
+<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre
class="highlight"><code>com.acme.Money = com.acme.MoneyConverter
+</code></pre></div></div>
+
+<p>a <code class="language-plaintext highlighter-rouge">Money</code> property
is written as the string returned by the converter’s <code
class="language-plaintext highlighter-rouge">convertToString()</code>:</p>
+
+<div class="language-json highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="p">{</span><span
class="nl">"price"</span><span class="p">:</span><span class="w"> </span><span
class="s2">"12.50 EUR"</span><span class="p">}</span><span class="w">
+</span></code></pre></div></div>
+
+<p>instead of:</p>
+
+<div class="language-json highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="p">{</span><span
class="nl">"price"</span><span class="p">:</span><span class="w"> </span><span
class="p">{</span><span class="nl">"amount"</span><span class="p">:</span><span
class="w"> </span><span class="s2">"12.50"</span><span class="p">,</span><span
class="w"> </span><span class="nl">"currency"</span><span
class="p">:</span><span class="w"> </span><span class="s2">"EUR"</spa [...]
+</span></code></pre></div></div>
+
+<ul>
+ <li>Only converters registered <strong>per type</strong> are used — in <code
class="language-plaintext
highlighter-rouge">struts-conversion.properties</code> or with
+<code class="language-plaintext highlighter-rouge">@TypeConversion(type =
ConversionType.APPLICATION)</code>. A converter registered for a superclass or
an interface applies to its subtypes. Per-property
+mappings from <code class="language-plaintext
highlighter-rouge">Foo-conversion.properties</code> are not used.</li>
+ <li>Types the plugin serializes natively are never converted: strings,
numbers (including <code class="language-plaintext
highlighter-rouge">BigDecimal</code>), booleans,
+characters, maps, collections, arrays, dates, <code class="language-plaintext
highlighter-rouge">java.time</code> values, locales and enums. Use <code
class="language-plaintext highlighter-rouge">@JSON(format)</code> or
+<code class="language-plaintext
highlighter-rouge">struts.json.dateformat</code> for dates.</li>
+ <li>A <code class="language-plaintext
highlighter-rouge">@JSONFieldBridge</code> on the property takes precedence
over a registered converter.</li>
+ <li>If the converter throws or returns something other than a <code
class="language-plaintext highlighter-rouge">String</code>, the value is
serialized as a bean, as before.</li>
+ <li>A converted value is written as a single string, so <code
class="language-plaintext highlighter-rouge">includeProperties</code> / <code
class="language-plaintext highlighter-rouge">excludeProperties</code> patterns
that point
+inside it, and <code class="language-plaintext highlighter-rouge">@JSON</code>
annotations on its members, no longer apply to it. Make sure the converter’s
output contains
+only what the response may expose.</li>
+</ul>
+
<h3 id="compressing-the-output">Compressing the output</h3>
<p>Set the <code class="language-plaintext
highlighter-rouge">enableGZIP</code> attribute to true to gzip the generated
json response. The request <strong>must</strong> include <code
class="language-plaintext highlighter-rouge">gzip</code>
