JSON Plugin & AJAX

All examples are classes and mappings of one WAR, g11json.war, deployed under the context path /g11json on Tomcat 11.0.26. It is the Struts Bookshelf of Getting Started (the struts2-bom 7.4.0 and struts2-core) with one more dependency and one more package:

Source: JSON Plugin — Installation

The version comes from the BOM. Copying the jar into WEB-INF/lib is all the plugin needs: it has no other files to add. The domain classes are small. Book is a bean with id, title, author, subtitle, genre (an enum with a label), published (a Date) and an internalNote that must never reach the client; BookStore keeps three books in memory (Dune, Neuromancer and The Hobbit); BookRecord is a Java record used to show the 7.3 record support. The actions that matter are named where they appear.

The plugin jar contains a struts-plugin.xml, which the framework loads automatically (see the page on struts.xml and constants). It defines one package, json-default, that extends struts-default, and a few beans and constants. Reading the file of the 7.4.0 jar gives the whole surface of the plugin:

Source: JSON Plugin — Deserialization limits

The json interceptor is not part of defaultStack and no action uses it unless a mapping says so. That is deliberate: a JSON request body is only read for the actions that opt in, which keeps ordinary form actions unaffected. The result type, by contrast, is available to every package that extends json-default, and a package can list several parents (extends="struts-default,json-default"), which is how one package serves both pages and JSON (see Results and Result Types, which also lists the json result next to the other plugin results).

The interceptor acts only when the request Content-Type equals the configured jsonContentType (application/json by default) or jsonRpcContentType (application/json-rpc, for SMD). Any other content type, for example a form post or a GET, passes through untouched, which the scratch run confirmed: a form post to add-all filled note from the form fields and ignored the JSON machinery. The result then serializes whatever the mapping selects. The two halves are independent: an action can read JSON and answer with a page, or read a form and answer with JSON.

Source: JSON Plugin — Accepting JSON

The smallest JSON endpoint is an action and a json result without parameters. The mapping needs a package that extends json-default:

Source: JSON Plugin — Write the mapping for the action

DefaultJsonAction extends ActionSupport and has two getters, getBooks() and getCount(). The response contains exactly those two properties:

Three things are visible. Property names are sorted alphabetically. A null is written as null. And none of the getters that ActionSupport brings (getActionErrors(), getLocale(), getTexts() and so on) were serialized, because by default the writer looks only at the getters declared on the root object’s own class and ignores those of its base classes; the ignoreHierarchy parameter, covered below, changes that. Serialization is by getters: the plugin page says a field without a getter and a transient field are not serialized, and @JSON(serialize = false) removes a getter from the output.

Source: JSON Plugin — Example

The response headers of such a result are the ones of any Struts response (the stack adds Vary: Sec-Fetch-*, Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy-Report-Only, see the page on interceptors) plus Content-Type: application/json;charset=UTF-8 and a Content-Length. The headers other than those two are left out of the transcripts below.

Several result parameters control the envelope rather than the data:

Source: JSON Plugin — Wrapping

Source: JSON Plugin — JSONP

Source: JSON Plugin — Compressing the output

Source: JSON Plugin — Preventing the browser from caching the response

Source: JSON Plugin — Content Type

The mappings that produced these results differ from books only in the extra parameters, for example:

Source: JSON Plugin — Preventing the browser from caching the response

JSONP is a pre-CORS device for reading JSON from another origin through a <script> element, and it hands the page to whoever controls the callback name; do not enable it for an authenticated endpoint. The two deprecated cousins, a wrapWithComments wrapper and the prefix option that writes {}&&, are documented with the warning that comment wrapping can turn safe JSON into dangerous text (the example is a string containing */ followed by script), so use wrapPrefix if a hijacking-defence prefix is wanted at all.

An action receives a JSON body when its stack contains the json interceptor. The interceptor reads the request body (application/json), parses it into maps, lists and primitives, filters the keys, and then sets the properties of the action by reflection on its setters. Place it before defaultStack (or use the stack that suits the action):

Source: JSON Plugin — Accepting JSON

Source: JSON Plugin — Parameter authorization

The response shows the rules at work. book was populated, including the nested genre (a string converted to the enum) and published (parsed with the @JSON format), tags was filled with the list, and note was set. secret has a public setter but no @StrutsParameter, so it stayed untouched although the body asked for pwned: the interceptor applies the same annotation rule as the params interceptor to every key of the JSON tree, before anything is set (a rejected key is dropped and logged, not an error). The plugin page says the annotation is enforced per property during deserialization, so unauthorized fields are never set on the target object.

Two details of that rule are not spelled out in the page and cost time:

The internalNote key of the body above was also ignored, but that is the effect of @JSON(deserialize = false) on the bean, as the plugin page’s table describes; it does not appear in any response to prove it, so the table rather than the run is the source for that statement.

Without any configuration, a malformed body is a server error with the container’s HTML page: the body {"book": made the interceptor throw JSONException ("Input string is not well formed JSON") and Tomcat answered 500 with an HTML report. A value that cannot be converted fails differently: the key "genre":"NOPE" raised a plain IllegalArgumentException from Enum.valueOf (also 500), not a JSONException, so an exception mapping for JSONException alone does not catch it. The page on exception handling describes the machinery; here it is used to answer in JSON. The exception interceptor must wrap the json interceptor, so it is listed before it:

Source: Core Developer Guide — Exception Configuration

The exception interceptor appears twice in the resulting stack (once explicitly and once inside defaultStack), which is harmless. The message is a constant: copying exception.message into the response would put parser internals, class names and paths in front of the client.

The writer and reader are Struts beans. The default struts implementations are registered with scope="prototype", and struts.json.writer and struts.json.reader select the implementation by bean name, so a custom one is a class, a bean declaration and a constant (the plugin page names the interface org.apache.struts2.json.JSONWriter and a Flexjson-based sample in the json-customize project of the struts-examples repository). The Bookshelf variant wraps every response in an envelope by extending the built-in writer:

Source: JSON Plugin — Customizing the output

The example was deployed as a second scratch WAR (g11jsonw) because the constant is global to the application. The bean must be prototype-scoped. Since 7.3.0 the interceptor gets a fresh reader and writer per request, and the built-in implementations keep their parse and write state in instance fields, so cross-request safety relies on the scope: a singleton implementation that holds per-request state leaks it between concurrent requests, which is exactly the mistake the next section’s bulletins describe in the framework’s own code. The same page records that the struts.json.writer and struts.json.reader overrides were ignored in 7.2.x (WW-5641, fixed in 7.3.0), so a workaround carried from that release can be removed.

Source: Javadoc — JSONWriter

The plugin can also expose action methods to a script. A Simple Method Definition (SMD) is a JSON description of the remote methods; a client that understands it generates a proxy, and each call is a JSON-RPC request. It was built for the Dojo toolkit and needs two things, both required together: enableSMD on the interceptor and on the result, and the @SMDMethod annotation on each method that may be called (a security measure: only annotated methods are reachable). The package of the annotation in 7.4.0 is org.apache.struts2.json.annotations:

Source: JSON Plugin — JSON RPC

A GET returns the SMD (the smd method only exists to give the result something to serialize) and a POST with the application/json-rpc content type invokes the method. Parameters are positional (p0, p1) unless @SMDMethodParameter names them. If the action could be a proxy (for instance when AOP interceptors wrap it), annotations on its methods are not inherited; the result parameter ignoreInterfaces and the interceptor parameter ignoreSMDMethodInterfaces, both set to false, make the plugin inspect interfaces and superclasses at a performance cost.

Source: JSON Plugin — Proxied objects

SMD is the weakest part of the plugin for a 2026 application. The documentation’s client is dojo.rpc.JsonService, and Dojo has not been part of Struts since 2.5; nothing else generates a client from an SMD document with any frequency; and the feature is the one surface of the plugin that a security bulletin touched (S2-071, below). A new API is better served by plain JSON endpoints, as in the earlier sections, or by the REST plugin of this section.

AJAX needs nothing from Struts. The Core Developer Guide says the point: an Ajax request is an ordinary request, the framework cannot tell it was sent by a script, and the Ajax response is simply a portion of a page, a fragment, a script or JSON. In Struts 7 the work of the old tag libraries is done by two plain mechanisms. The first is an action that returns JSON, called from fetch. The page below is ajax.html of the scratch WAR, served from the web root:

Source: MDN — Using the Fetch API

The title and author are inserted with textContent, so a title that contains markup is shown as text; building HTML from JSON by string concatenation and innerHTML is the cross-site scripting mistake of this style. The browser itself was not driven in this verification; the same fetch calls were run against the scratch Tomcat with Node 24 (whose fetch is the same API) and returned the three books, the created book (status 200), the 400 for a malformed body and the 400 validation document:

Posting JSON is the same call with a method, a header and a body, and it is what the json interceptor expects:

Source: MDN — Using the Fetch API

The second mechanism is the one the Core Developer Guide’s AJAX page itself describes for responses that are not JSON: a stream result that returns an HTML fragment (the page names JSON as the preferred route, but the stream result is the direct way to return text, HTML or a script). The fragment goes to a library such as htmx, which swaps it into the page by attributes alone:

Source: Core Developer Guide — AJAX, Configuring the TextResult Action

Source: htmx — Documentation

htmx sends the value of the input as the query parameter q on each change (after the 300 ms delay) and puts the returned fragment inside the results element. The browser behaviour of htmx was not exercised here, only the endpoint it calls (verified with curl, including a query for <b> that returns an empty list); the attributes shown are those of the htmx documentation. Two observations from the run belong in the pitfalls table: the contentType parameter text/html;charset=UTF-8 produced a plain text/html response (the stream result takes the character set from its separate contentCharSet parameter), and a getter that threw a NullPointerException (a book with a null title in the store) made the result fail with "Can not find a java.io.InputStream with the name [inputStream] in the invocation stack", because OGNL swallows the exception and the stream result then sees no value. The fix was the null check in the code above.

Source: Core Developer Guide — Stream Result

The Core Developer Guide AJAX page, the Tag Developer Guide’s "Ajax Tags" and "Ajax and JavaScript Recipes" pages and the second edition of the Manning book all describe a generation of Ajax support that is gone:

The recipes page is still worth reading for what it taught: request triggers and targets (bind), update of a region (div with href and reloadTopics), an indicator during the request, error handling with a message, and an autocompleter that loads its options from an action. Every one has a direct translation: a fetch or an htmx attribute for the request, a fragment or JSON for the response, the browser’s input event and datalist for autocompletion. The recipe’s JSON autocompleter in particular used the json result with root set to a map (<param name="root">options</param>), which is the same mapping as the books action above with another root.

Source: Tag Developer Guide — Ajax Tags

Source: Tag Developer Guide — Ajax and JavaScript Recipes, Using the JSON plugin to generate the values

Source: Core Developer Guide — AJAX, Ajax Plugins

An action can also return plain JSON without the plugin, through the plain or stream results or a JSP that prints JSON by hand (the AJAX page shows the JSP variant with a book.jsp scriptlet). It works, but hand-built JSON is the source of broken escaping; use the plugin or a JSON library, and write the result with application/json.

Three bulletins of August 2026 concern the plugin, and every fix is in 7.3.0 or later, so an application on 7.4.0 has them:

Source: Security Bulletin S2-070

Source: Security Bulletin S2-071

Source: Security Bulletin S2-072

The lesson common to the three is the lifetime of the reader and writer objects, and the 7.3.0 design (fresh reader and writer per request, prototype beans) is what a custom writer must preserve. For an application the controls are: use the plugin only where an action needs it, put the json interceptor only on actions that accept a body, annotate the properties that may be set with @StrutsParameter, leave enableSMD off, set body limits that fit the API (maxLength of a few kilobytes is usually enough) and keep Struts patched. The page on security hardening in this section covers the rest of the stack, including the request-size limit at the container, which is the only bound that does not depend on Struts code.

Source: Apache Struts — JSON Plugin

Source: Core Developer Guide — AJAX, Ajax Plugins

Struts 2 in Action (2008) builds its AJAX chapters on the Dojo-based tags and the ajax theme, and its result chapter shows a hand-written JSON result. Struts in Action (Struts 1) wrote the response from the action itself. The ideas survive (the response of an Ajax call is not a page; a custom result can write anything), the tools do not.

Source: Core Developer Guide — AJAX

Source: Tag Developer Guide — Ajax Tags

Several details of the official pages disagree with the 7.4.0 jar or with themselves. They are listed so that a reader who meets them is not misled.

The JSON plugin makes JSON a first-class result and body format: map the action in a package that extends json-default, name the root, shape the output with includeProperties, excludeProperties, excludeNullProperties and the @JSON annotation, and use statusCode for a JSON error. To accept JSON, put the json interceptor before defaultStack, annotate every property that may be set (both accessors of a nested bean), bound the body with maxLength and the other limits, and map the exceptions of the interceptor to a JSON 400 with the exception interceptor in front. Use jsonValidation for AJAX validation, a prototype-scoped JSONWriter for custom output, and leave SMD alone. For the client, use fetch for JSON and a stream result for HTML fragments with htmx, and treat the Dojo, jQuery and YUI material as history. Keep CSRF defences, because JSON endpoints are reached by cookies like any other action.