Results & Result Types

Once the action method (and the interceptors around it) has finished, the framework needs to produce the response. It asks the action invocation for a Result and calls its execute method. In Struts 7 the contract is the interface org.apache.struts2.result.Result (before 7.0 it was com.opensymphony.xwork2.Result; the package rename is part of the 6 to 7 migration) with exactly one method, execute(ActionInvocation). Almost every built-in result extends StrutsResultSupport, which adds the location property, the parse and encode switches and the evaluation of ${...} expressions against the value stack. What the action method returns decides how the framework reaches a Result:

Source: Apache Struts — Result Configuration, Returning Result Objects

The result is the last step before the response, but it is not the very last thing that happens. PreResultListener objects registered during the action or by an interceptor run first and may still change the result code (see Listeners Around the Result), and interceptors get control back after the result has run, so an interceptor that wraps invoke() sees a response that already exists.

The diagram shows why a typo in a result name is a runtime problem and not a startup problem: the framework cannot know which codes an action method will return, so the lookup happens per request. The rest of the page follows the diagram from the left: the configuration (Result Configuration), the shared parameters, and then each result type.

The scratch application behind the examples is the Bookshelf of the Getting Started page, extended with one action per result type. Its struts.xml begins with the pieces every example below relies on: a package that extends struts-default and the plugin packages that register the extra result types (see Plugin Results), one custom result type, and two global results.

Source: Apache Struts — Result Configuration, Global Results

Three details of that file come from the 7.4.0 DTD and defaults and are easy to miss. The element order inside package is fixed (result-types, interceptors, default-interceptor-ref, default-action-ref, default-class-ref, global-results, global-allowed-methods, global-exception-mappings, then the actions), so result-types must precede global-results. A package may extend several packages with a comma-separated list, which is how one package gets the json, velocity, xslt and tiles result types at once; only the packages named in extends contribute their result types. The struts.allowlist.packageNames constant is explained in Security: Dynamic Values and the Allowlist; without it the custom result of this page prints empty values.

A result element has two jobs: it gives a logical name (the code the action returns) and it names a result type with its parameters. Every part of the element has a default, so the common case is very short.

Source: Apache Struts — Result Configuration, Result Elements

Three defaults make the short forms possible, and each one can be changed:

Source: Apache Struts — struts-default.xml

Source: Apache Struts — Result Types, Default Parameters

Nine types are registered in struts-default.xml; velocity, xslt, json, tiles, jasper, jasperReport7 and chart come from plugins and exist only in the plugin’s own package.

Results built on StrutsResultSupport (all of the built-in ones except chain, httpheader and the Result objects you return) share three parameters, and the redirect family adds more.

Source: Apache Struts — Dispatcher Result, Parameters

The parse and encode switches matter most for redirect, where an expression sits inside a URL. In the run, the same location produced three different Location headers.

Source: Apache Struts — Redirect Result, Parameters

Without encode the value is pasted into the URL as it is, so the & in a b&c starts a second parameter. Putting values into the query string as separate param elements (next section) avoids the problem because the framework builds and encodes the query string itself.

dispatcher is the default type and the one almost every action ends with. It hands the request to a web resource, usually a JSP, through the servlet RequestDispatcher, so the target sees the same request and response objects and the action is still on the value stack (the JSP’s s:property tags read it). The documentation lists three ways the result can run, and the 7.4.0 source confirms the order of the checks:

Source: Apache Struts — Dispatcher Result

The target of a dispatch may be any resource of the web application, including one under WEB-INF, which a browser can never request directly. That is why the Bookshelf keeps every JSP in /WEB-INF/views/: the URL space belongs to the actions, and a visitor cannot bypass them to reach a view.

Source: Apache Struts — Dispatcher Result, Examples

A dispatch to a template that does not exist is reported by the container, not by Struts: on Tomcat 11 the request answers 404 with JSP file [/WEB-INF/views/nope.jsp] not found, so a mistyped location is found by calling the action, never at startup.

A dispatcher result answers the current request. If that request was a POST, the browser’s address bar still shows the POST URL, and pressing reload sends the form again. The remedy, known as Post/Redirect/Get, is to answer a successful POST with a redirect, so the browser issues a GET to a different URL. Struts has two result types for it: redirect sends the browser to a URL, and redirectAction sends it to an action by name, asking the configured ActionMapper for the URL.

A redirect is a new request, so the action instance, its field errors and its messages are gone by the time the next action runs. The redirect result documentation says this plainly: the only ways to pass data are the session or request parameters. The Bookshelf passes the new id as the added parameter. The store interceptor (MessageStoreInterceptor, registered in struts-default.xml but not part of the default stack) exists to carry action messages and errors across a redirect; it belongs to the interceptors page of this section.

The chain result runs an entire other action, with its own interceptor stack and result, inside the current request. The browser sees one request and one URL; unlike a redirect, the first action remains on the value stack, and the chain interceptor (part of the default stack) copies the properties of the earlier action to the later one. Its parameters are actionName (the default parameter), namespace, method and skipActions (a comma-separated list of action names that must not be chained to).

Source: Apache Struts — Chain Result, Examples

The framework’s own guidance is cautious: the Action Chaining page advises against chaining as a rule and names the Redirect After Post technique as the first alternative to try. Chained actions are hard to follow, couple one action to another’s properties, and run a second interceptor stack on the same request. ActionChainResult keeps a chain history in the action context, and a chain that comes back to an action already in it fails: two actions chaining to each other answered 500 with Infinite recursion detected: [//loop-a!execute, //loop-b, //loop-a, //loop-b] (a StrutsException). The detailed behaviour of the chain interceptor, and the session and scope alternatives, belong to the action-chaining page of this section; here the rule of thumb is to chain only for read-only lookups that need no fresh request, and to redirect for everything that changes state.

stream copies an InputStream from the action straight to the response. It is the result for file downloads, generated images, PDF documents and CSV exports, because nothing is rendered: the bytes go out as they are, with the headers the configuration sets. The Bookshelf export is a good example because every parameter has a visible effect.

Source: Apache Struts — Stream Result, Parameters

Since Struts 2.5.2 a parameter takes its value from the action only if the configuration says so with an expression: to read contentType from getContentType(), write <param name="contentType">${contentType}</param>. Before 2.5.2 each parameter was resolved automatically from the value stack, including inputName; a configuration migrated from an older version that relied on that behaviour streams nothing or the wrong thing.

Source: Apache Struts — Stream Result, XML Based Configuration

Three details of the example are worth stating. The getter returns a new stream on each call; the result asks the action for the stream once, but returning a fresh object keeps the action reusable if it is ever called twice. The cell method defuses CSV injection: a value that starts with =, +, -, @, a tab or a carriage return is prefixed with an apostrophe because a spreadsheet would otherwise evaluate it as a formula. And the file name comes from the server, never from the request; user-controlled text in Content-Disposition or in the path of the stream is a header-injection and path-traversal risk (the File Upload and Download page of this section develops a safe download).

If the property named by inputName is missing or returns null, the request fails with an IllegalArgumentException whose message names the parameter and hints at the cause. In the run, a result with inputName set to nope answered 500 with Can not find a java.io.InputStream with the name [nope] in the invocation stack. Check the <param name="inputName"> tag specified for this action is correct, not excluded and accepted.. The words "excluded and accepted" refer to the allowlist and the accepted-patterns checks described in Security: Dynamic Values and the Allowlist: an inputName that is itself an expression is evaluated only if it passes them.

httpheader sets the status line, headers and, optionally, an error on the response and writes no body. It suits endpoints that answer with a status (204 after a delete, 304, 405), and actions that must signal an error to the container so that the configured error-page renders. The parameters are status, headers (a map), error, errorMessage and parse (default true: values are evaluated against the value stack).

Source: Apache Struts — HttpHeader Result, Examples

A header name with a hyphen cannot be written in the dotted form: the documentation’s headers.a works, but in the run headers.X-Book-Count set no header at all (the name is read as an expression), while the indexed form headers['X-Book-Count'] worked. The two ways to signal a problem differ. status calls setStatus and leaves the response open, so nothing else is rendered. error calls sendError, which hands control to the container: its error page, or the default one that shows the message, takes over. The second form is the one to use for a 404 or 403 that should look like the rest of the site.

plainText sends the content of a web resource as text/plain, without interpreting it. The documentation describes it as useful for showing the raw content of a JSP or an HTML file. The resource is read through the servlet context, so anything the application can read, including files under WEB-INF, can be served. Parameters: location (the default) and charSet.

Source: Apache Struts — PlainText Result, Examples

Without charSet the content type is a bare text/plain, and in the run the container then answered text/plain;charset=ISO-8859-1, so a UTF-8 file with accented characters is garbled; always set charSet. The result is meant for diagnostics. Pointing it at a JSP, a configuration file or a template with a location that comes from the request would publish source code and secrets; the location must be a constant.

Since Struts 6.0.0 an action method may return a PlainResult, a functional interface with one method that receives a ResponseBuilder. No result element is needed. The builder collects the body, headers and cookies; the default content type is text/plain; charset=UTF-8, and helper methods switch it to HTML or JSON. The result refuses to write when the response is already committed (a StrutsException) unless the implementation overrides ignoreCommitted().

Source: Apache Struts — Plain Result, Examples

write and writeLine append the string exactly as given (the 7.4.0 BodyWriter is a plain StringWriter), so a PlainResult that writes HTML or JSON built from user input must escape it itself; for JSON use the json result, which serialises objects correctly. The action class here is a POJO: it does not extend ActionSupport, which would also work, but execute() could not then change its return type.

postback answers with a small HTML page whose form carries the current request’s parameters as hidden fields and submits itself to another destination at once. It exists to turn the current request into a POST to another action or URL, for example to continue a flow with a third party. Parameters: location (default; a URL), or actionName, namespace and method (resolved as expressions) for an action, plus prependServletContext (default true) and cache (default true; false adds no-cache headers).

Source: Apache Struts — Postback Result, Examples

The run exposed a quirk worth knowing before relying on this result. The hidden field’s value is URL-encoded by the result (Dune & Co became Dune+%26+Co) and a browser submits that text as it is, so the receiving action got the encoded string, and a value with an accent arrives as Caf%C3%A9. The page is also sent without a character set (the container answered ISO-8859-1). The destination must decode the value itself, or the parameters sent through a postback should be restricted to ASCII identifiers. The result also skips parameters whose name starts with action:, and the form submits through a script, so a page served with a strict content security policy needs the script allowed.

Two result types render a template instead of dispatching to a JSP. freemarker is part of struts-default.xml (the FreeMarker library is a dependency of struts2-core), velocity comes from the Velocity plugin. Both take location as the default parameter and both expose the action and the value stack to the template, so ${book.title} reads the property of the action. FreeMarker templates load from the web application root (/WEB-INF/views/home.ftl) or from the classpath; the freemarker result also accepts contentType (default text/html), parse and writeIfCompleted (default false: write to the response only if the template completed without an error; template_exception_handler=rethrow in freemarker.properties has the same effect). The FreeMarker and Velocity Views page of this section covers the template language and the tag libraries; here is only what the result type itself does, using one Bookshelf fragment in both engines.

Source: Apache Struts — FreeMarker Result, Examples

Source: Apache Struts — Velocity Result, Examples

The difference between the two outputs is the most important fact about these result types. In the run, FreeMarker escaped the title (HTML auto-escaping is on in 7.4.0) while Velocity printed it as it was, so the Velocity template is a cross-site scripting hole as soon as the value contains user input; escape each reference with a Velocity escape tool or use the Struts tags. The FreeMarker side has a related trap: the old ${title?html} built-in is rejected under auto-escaping with a ParseException that says legacy ?html escaping is not allowed when auto-escaping is on, so templates written for Struts 2.3 or 2.5 fail at the first request. Drop the built-in and let the engine escape.

Every plugin that adds a result type registers it in its own package, and an application package uses the type only if it extends that package or registers the type itself. The table below was read from the struts-plugin.xml of each 7.4.0 plugin jar.

Source: Apache Struts — Plugins

A result type is any class that implements org.apache.struts2.result.Result. Extending StrutsResultSupport is almost always easier, because the base class provides the location property, the parse and encode switches and the evaluation of ${...}; the subclass implements only doExecute(String finalLocation, ActionInvocation invocation). The framework creates the result for each request, sets the param values through setters and injects its own beans into @Inject methods. Registering takes one line in a package’s result-types, after which the type name is available to every action of that package and of the packages that extend it.

Source: Apache Struts — Result Types, Registering Result Types

Source: Apache Struts — Result Types, Extending

The first run of this example printed ` — ` and nothing else. The cause is in the next section: the Book class was not on the OGNL allowlist, so book.title evaluated to nothing and the log showed a warning. A custom result is also the place to put a response format the built-in types do not offer (a vCard, an image with a computed watermark), but a plain action method returning a PlainResult is the shorter route when the output is a string.

Two small interfaces let code observe or influence the result phase without being a result.

A PreResultListener runs after the action (and the interceptors above it) has produced a result code and before the result is looked up. An action or an interceptor registers it on the ActionInvocation; beforeResult(invocation, resultCode) may inspect or modify the response, the action or even the result code. The documentation shows the registration from an action and from an interceptor (AbstractInterceptor.intercept); the Custom Interceptors page of this section builds on the second form.

Source: Apache Struts — PreResultListener, By an Action

A DispatcherListener is called when the Dispatcher (the framework’s central object, created by the filter) is initialised and when it is destroyed. It is registered statically with Dispatcher.addDispatcherListener, so the registration must happen before the filter initialises: a ServletContextListener runs before filters, and the example sets a servlet context attribute that the health action above reports.

The health response shown earlier ("dispatcherReady":true) is the proof that the callback ran.

Source: Apache Struts — DispatcherListener, Example

Results are where request data meets the response, and three rules keep that meeting safe.

Expressions in results are evaluated, so their inputs must be trusted. A ${...} in a result is evaluated against the value stack, the same mechanism that powers tags. The expressions in the examples above refer to properties the action computes (${newId}, ${nextAction}, ${fileName}). A property filled from a request parameter and then used as the whole target of a redirect is an open redirect: the visitor chooses where the browser goes. The run shows both forms.

Source: Apache Struts — Result Configuration, Dynamic Results

Only parameters the action opted into can be set, and only allowlisted classes can be reached. Struts 7 enables both struts.parameters.requireAnnotations (a request parameter may set only a property whose setter or getter carries @StrutsParameter) and struts.allowlist.enable (OGNL expressions may reach only the minimal set of classes the application needs); both are new defaults of 7.0. The 6.x to 7.x migration guide says most applications need no configuration, but those that use POJOs or DTOs for parameter injection and template rendering must allow their classes or packages with struts.allowlist.packageNames or struts.allowlist.classes. The Bookshelf Book class was not allowlisted until the constant in the shared package named its package, and the log said so:

Source: Apache Struts — Struts 6.x.x to 7.x.x migration

The allowlist does not apply to FreeMarker, which reads the property through its own object wrapper: in the run the same book.title printed in book-card.ftl while the OGNL expression in the label result printed nothing. That asymmetry is why a result that works in one engine can fail in another.

The stream result evaluates inputName only when it passes the accepted-patterns check, and a configuration that takes the name from a request value would let a visitor choose any stream property; keep inputName, like location, a constant. The same constants (struts.excludedClasses, struts.excludedPackageNames, and the accepted patterns) that protect parameters protect these expressions; the Security Hardening page of this section lists them.

Source: Apache Struts — Result Configuration

Source: Apache Struts — Struts 6.x.x to 7.x.x migration

Source: Apache Struts — Version Notes 7.4.0

Source: Apache Struts — JSON Plugin, Java Records and Optional

Struts in Action (Struts 1, ActionForward and ActionMapping chapters) and Struts 2 in Action (the results chapter) are listed in the section bibliography. Their concepts survive: a name chosen by the controller, a mapping to a view, a global list for shared outcomes. The details do not.

Source: Apache Struts — Result Types

Source: Apache Struts — Convention Plugin

Source: Manning — Struts in Action

Source: Manning — Struts 2 in Action

The official documentation has gaps and stale spots of its own, found while testing for this page.

Source: Apache Struts — Result Types, Extending

A result is the second half of an action: the action returns a code, result elements map codes to types, and the type turns the code into a response. Most result elements need only a location because the name, the type and the parameter all have defaults. dispatcher forwards to a JSP under WEB-INF, redirectAction ends a POST with a redirect, stream sends files, httpheader sends statuses, PlainResult writes strings from Java, and the plugin packages add JSON, XSLT, Tiles, Velocity and reports. Treat every expression in a result as code that runs on the server: compute it in the action, never take it from the request, and let the allowlist stay on.