ValueStack, ActionContext & OGNL

The Javadoc of ActionContext calls it the context in which an action is executed: each context is a container of the objects an action needs for execution, like the session, parameters and locale. It is thread local, which means that the values stored in it are unique per thread; the benefit stated by the Javadoc is that nobody has to worry about a user specific action context and nobody has to make actions thread safe. ActionContext.getContext() returns the context bound to the current thread, and getContextMap() returns the underlying map, which is the same map that OGNL sees as its context.

The 7.4.0 class exposes the request state through typed getters and fluent with... setters (the setters return the context, so they chain). The table lists the getters and the OGNL name or map key behind each one.

Source: Struts Javadoc — ActionContext

The key names in the last column were read from ActionContext.getContext().getContextMap().keySet() printed by the shelf action on Tomcat 11.0.26 (see the next listing). They are the 7.x names: before the repackaging of 7.0 the same keys started with com.opensymphony.xwork2.ActionContext, and code that still asks for such a key gets null.

Source: Struts Javadoc — ActionContext.getContextMap()

With <s:property value="contextKeys"/> in the JSP, the response of the shelf action contained (line breaks added):

Source: Tag Developer Guide — OGNL, Context

Two groups of keys appear. The short ones (action, application, attr, parameters, request, session) are the names the views use with a #; they are the "Struts named objects" of the OGNL Basics page. The long dotted ones are the typed state behind the getters, and a few bookkeeping entries (current.property.path, last.bean.accessed, report.conversion.errors, __component_stack, __requestWrapper.getAttribute) belong to OGNL, to type conversion and to the tags. The two xwork. entries show that parts of the internal naming were not renamed in the 7.0 repackaging. Application code should use the typed getters and treat the dotted keys as internal.

Three ways exist to read or write the session, request and application from Java, and the Core Developer Guide ranks them (the servlet-level objects behind these maps are described in Servlet Fundamentals, Sessions, and the action classes that receive them in Actions). The recommended one is the Aware interfaces of org.apache.struts2.action: the framework, through the servletConfig interceptor of defaultStack, calls the single method of each interface that an action implements, and the action stores what it is given. The guide says that using ActionContext directly for this is a bad practice and should be avoided, with the *Aware interfaces as the alternative; ServletActionContext (static helpers for the request, response, servlet context, page context, action mapping and the stack of a request) is the third way and ties the action to the servlet API in the same way as ServletRequestAware.

Source: Core Developer Guide — Accessing application, session, request objects, Accessing from Java

The Aware interfaces were renamed in 6.0 (setSession became withSession, setServletRequest became withServletRequest) and moved from org.apache.struts2.interceptor to org.apache.struts2.action; code written for the older names does not compile on 7.x.

Source: Core Developer Guide — Servlet Config Interceptor

The view reads the same data back with the # names. The aware.jsp page and its response on Tomcat 11.0.26:

Source: Core Developer Guide — Accessing application, session, request objects, Accessing from the view

Source: Tag Developer Guide — OGNL Basics, Struts 2 Named Objects

sameMapAsContext=true shows that the map handed to withSession is the very map the context holds and the view reads, so a write through any of the routes is visible through all of them. The values banner and seenBanner come from the interceptor of the next section, and ${banner} in W6 is JSP EL reading an object of the value stack; how that works is explained in the section on EL beside OGNL.

The 7.4.0 API creates and binds a context with static factories, which is what makes unit tests without a servlet container possible: ActionContext.of(map) (or of()) creates a context around a map, the with... methods fill it, bind() attaches it to the current thread and clear() removes it.

Source: Struts Javadoc — ActionContext.bind()

Compiled and run with the WAR’s libraries on Java 21, the program printed:

Source: Struts Javadoc — ActionContext.of(Map)

The third line is the practical consequence of the thread-local design: a thread that the container did not dispatch the request to (a task submitted to an executor, a CompletableFuture, a servlet async callback) sees null from ActionContext.getContext(). Code that has to run there must receive the data it needs as arguments, or capture the values before leaving the request thread.

The interceptors that fill the stack (modelDriven, params, servletConfig) are described on Interceptors. The Javadoc describes the value stack as a structure that allows multiple beans to be pushed in and dynamic expressions to be evaluated against it; when an expression is evaluated, the stack is searched from the latest object pushed in to the earliest, looking for a bean with a getter or setter for the given property, or a method of the given name. Four things put objects on it during a request:

Source: Struts Javadoc — ValueStack

The root of the stack is a CompoundRoot, a list that ValueStack.getRoot() returns, so printing its elements shows what a view can reach. This action property lists the class of every element from the top; it is used by all the stack experiments below.

Source: Struts Javadoc — ValueStack.getRoot()

In shelf.jsp, <s:property value="stackReport"/> printed the stack of a plain action, and the same property inside <s:push value="books[1]"> printed the stack with a Book pushed on top:

Source: Tag Developer Guide — push

The line A26 prints, inside the s:push body, title (the Book), filter (not a Book property, so the search continues down to the action), [0].top.label (the top of the stack, a Book) and [1].top.filter (the top of the stack cut at element 1, the action). Outside the body the stack is again the two original elements: s:push pops what it pushed.

Source: Struts Javadoc — ValueStack, method detail

The members were listed from the 7.4.0 class with javap and match the Javadoc. Two details of OgnlValueStack matter in practice. A failed lookup is swallowed: findValue logs and returns null instead of throwing, unless the caller asked for exceptions (struts.devMode and struts.ognl.logMissingProperties control how loudly). And when the stack lookup returns null or fails, the implementation tries the context map under the same name, which is the "fallback to context" discussed in the OGNL and security sections.

Source: Struts Javadoc — ValueStack.findValue(String)

With the request /g9valuestack/shelf?filter=sci the property printed (line A25):

Source: Struts Javadoc — ValueStack.findString(String)

Three observations come out of that line. The filter property was set from the request by the params interceptor, so it is visible on the stack. books.size() returned null on Tomcat 11.0.26 with the 7.x defaults: the OGNL allowlist refuses a method whose declaring class (java.util.AbstractCollection) is not allowlisted, and the property form books.size works (see the security section). And an old key lookup would fail silently: a variant of this method that asked the context for com.opensymphony.xwork2.ActionContext.name, the key of the 2.x documentation and of the books, returned null, while the typed getter returned shelf.

An interceptor reaches both objects through the ActionInvocation: getStack() for the stack and getInvocationContext() for the ActionContext. This one puts a banner text on the stack and a flag in the session before the action runs.

Source: Struts Javadoc — ActionInvocation.getStack()

The earlier aware.jsp output already showed the results (banner=Bookshelf open, #session.seenBanner=true). With <s:property value="stackReport"/> added to the JSP, the stack at render time was:

Source: Core Developer Guide — Writing Interceptors

The HashMap on top is the map that set("banner", ...) pushed, found by the plain name banner like a property of any other element. Writing interceptors in general is the subject of Custom Interceptors (the stack that contains this one is on Interceptors); the point here is that an interceptor puts values where the view can reach them without the action knowing.

A ModelDriven action exposes one object, the model, that the modelDriven interceptor pushes on top of the action. The form fields and the view then address the model’s properties directly, and the action’s own properties stay reachable below.

Source: Core Developer Guide — Model Driven Interceptor

Source: Tag Developer Guide — OGNL Basics, Struts-specific language features

Source: Core Developer Guide — Model Driven Interceptor, Parameters

Both objects have a title, and the plain title returns the model’s because the model is on top (M1). [1].title cuts the stack at element 1 and finds the action’s getter (M3), and #action.title reaches the action directly through the context map whatever the stack looks like (M7). author exists only on the model and is found without any marker (M4). The tie between names is the rule of the next section.

The OGNL Basics page explains why Struts needs more than plain OGNL. Standard OGNL has exactly one root, so a name that is not a property of the root needs a # prefix. Struts wants many "roots", so the whole stack is the root and a special property accessor looks at the entries from the top down until it finds an object that has the property. With an Animal on top of a Person the docs show that species reads the animal, salary reads the person and name reads the animal’s (the top wins a tie). To reach the lower one, XWork added indexes on the stack.

Source: Tag Developer Guide — OGNL Basics, Struts-specific language features

On the plain shelf action the lines A20 to A22 printed [0].top.filter=sci, [1].top as the string form of org.apache.struts2.text.DefaultTextProvider and top.filter=sci, confirming that the cut [1] starts below the action. When no object has the name, two things can happen: the search ends with null, or, if the lookup fails or yields null, the stack falls back to the context map under the same name. On the probe action, the bare name session returned the session map {user=alice} and the bare names action and struts.actionMapping returned the action and the mapping, all of them context entries read without a #; with struts.ognl.valueStackFallbackToContext set to false the bare session returned null while #session.user still returned alice. The fallback is convenient and unintended in most code, and the security section lists it among the settings to switch off.

OGNL, the Object-Graph Navigation Language, is an expression language for getting and setting properties of Java objects. It is a separate open source library (the project lives at https://github.com/orphan-oss/ognl, and Struts 7.4.0 pins version 3.4.12); Struts uses it in four places that you meet daily: the tags (value, test, list and %{...} attributes), the params interceptor (a request parameter name such as book.title is an OGNL expression that is set on the stack), the validators and the result configuration (${...} in a result parameter is OGNL as well, see Results and Result Types). The Tag Developer Guide gives the minimum the framework adds to plain OGNL, and everything in this section is built on it:

The OGNL language itself (operators, literals, projection, selection, lambdas, instanceof, new, the @class@member static syntax) is documented by the OGNL project in its Language Guide; this page covers what Struts 7.4.0 lets through.

Struts places the request parameters and the request, session and application attributes in the context. The OGNL Basics page lists them; the right column shows what each one printed on the shelf action after it had put user in the session and requestId in the request, called as /g9valuestack/shelf?filter=sci:

Source: Tag Developer Guide — OGNL Basics, Struts 2 Named Objects

The Core Developer Guide adds the precision about scopes for #attr: it looks first in the page scope (when a PageContext exists), then request, session and application, and the first match wins. Writing just # followed by a name that is not one of the named objects reads a variable of the OGNL context, which is how the variables created by s:set, s:iterator var and s:bean var are reached (examples below).

Source: Tag Developer Guide — OGNL, Referencing an Action property

The page shelf.jsp of the example WAR printed A1 filter=sci, A2 #session.user=alice and so on, exactly the values of the table. The tag s:property writes the result of the expression into the page, HTML-escaped by default (its escapeHtml attribute defaults to true); escapeJavaScript, escapeCsv and escapeXml are the other escapers, and default supplies a text when the value is null.

The following table collects the expression forms of the OGNL pages of the Struts guides, run against the Bookshelf, with the output observed on Tomcat 11.0.26. Rows marked "JSP" were printed by s:property in shelf.jsp or more.jsp; rows marked "probe" were evaluated by the scratch probe action. The books are Dune (1965), Neuromancer (1984) and Hyperion (1989).

Source: Tag Developer Guide — OGNL, Collections (Maps, Lists, Sets)

The JSP behind the first rows of the table, with the output that Tomcat returned:

Source: Tag Developer Guide — OGNL, Collections (Maps, Lists, Sets), selection and projection

Source: Tag Developer Guide — OGNL, Collections (Maps, Lists, Sets)

Inside a selection or projection #this is the element being examined. The result of a selection with ?, ^ or $ is always a list, even for ^ and $, so printing it shows brackets and a following projection (.{title}) is usually needed to show something readable. The guides also show the same forms in the control tags, where they are most useful: a list literal as the options of a select, a map literal as value and label pairs, in and not in in an s:if, and selection or projection as the value of an s:iterator.

Source: Tag Developer Guide — OGNL, Collections (Maps, Lists, Sets), s:select and s:iterator

The rendered result (whitespace trimmed) was two select elements and two list items:

Source: Tag Developer Guide — OGNL, Collections (Maps, Lists, Sets)

Several tags create named values that later expressions reach with #. The lines B1, B7 and B21 of more.jsp exercise them; the output shows, in particular, where each variable ends up.

Source: Tag Developer Guide — set

Source: Tag Developer Guide — iterator

Source: Tag Developer Guide — bean

The lessons, all observed:

The tag s:push makes an object the top of the stack for its body, which lets a block of markup use short names. The line B23 combined it with the stack index: outside the tag books.size was 3; inside <s:push value="books[2]"> the expression [0].top.title printed Hyperion; after the tag the stack was the original again.

Source: Tag Developer Guide — push

The block rendered <p>Hyperion by Dan Simmons</p>.

The Tag Syntax page reduces the way Struts evaluates attributes to three rules: every attribute whose Java type is String is parsed for the %{ ... } notation, and what is outside of it is literal; every attribute of a non-String type (boolean, integer, Object, collection) is evaluated directly as an expression; and if a non-String attribute does use %{...}, the notation is stripped as redundant and the content is evaluated. The value attribute of the form tags (textfield, hidden, select and so on) is a String attribute, so there it must be written value="%{filter}" to read a property, while s:property, s:set, s:if and s:iterator take an expression in value and test without the wrapper.

Source: Tag Developer Guide — Tag Syntax, The value attribute of form tags

Source: Tag Developer Guide — Tag Syntax, Non-String Attributes

Source: Tag Developer Guide — textfield

The first field shows the literal text filter, the second the property; begin and end are integers, so the second s:iterator ran for the single element between index 1 and %{1}, the wrapper being ignored. The same rules give the label trick of the OGNL page: <s:textfield name="username" label="%{#request.foo}"/> puts the request attribute foo into a String attribute (label) that would otherwise take its text literally.

The Struts tags are declared in the TLD with attributes that do not accept runtime expressions, which is a different mechanism from the OGNL evaluation. Writing a JSP EL expression where an OGNL expression belongs is therefore not silently wrong, it fails when the page is translated.

Source: Tag Developer Guide — Tag Syntax, Expression Language Notations

On Tomcat 11.0.26 the request returned HTTP 500 with the message According to TLD or attribute directive in tag file, attribute [value] does not accept any expressions (a JasperException at the line and column of the attribute). The repair is the OGNL form <s:property value="filter"/>.

JSP EL looks a name up through the scopes, page first (the scope rules are on Implicit Objects & Scopes), and ends with request.getAttribute(name). Struts wraps the request in a StrutsRequestWrapper, whose getAttribute returns the real attribute if there is one and otherwise asks the value stack for the same name with findValue(name). That is why ${filter}, ${books[0].title} and ${banner} print values that nobody put into a scope: they were found on the stack. The line A32 of shelf.jsp shows it:

Source: Struts 7.4.0 source — StrutsRequestWrapper.getAttribute

Source: Core Developer Guide — Accessing application, session, request objects, Accessing from the view

filter and books came from the stack (the action), user from the session (the context-aware lookup: the attribute user is not a request attribute, it is found because the stack search reaches the context fallback), and requestId from the request. The constant struts.disableRequestAttributeValueStackLookup, introduced for "JSTL accessibility" according to its Javadoc and false by default, switches the stack lookup off. With it set to true, the same page printed A32 EL filter=|titles=|user=alice|requestId=42: the stack-based names went empty, while the real scope attributes and sessionScope.user still worked. The setting closes a path from a request-supplied attribute name to the stack and is part of the hardened configurations; it also means that EL in a page must then use the scopes explicitly or s:set to publish what it needs, which is the technique of the next paragraph.

The older Tag Developer Guide page "Access to ValueStack from JSPs" describes the same need for third-party tag libraries that read JSP EL (it names DisplayTag): expose a value with s:set in the request scope (its example is <s:set name="'a'" value="{ 1, 2, 3, 4 }" scope="request"/>, with the old name attribute that today is var) and then use ${a[0]} in the third-party tag. The B21 output above is the modern form of that idea (${v2} found the request-scope variable). The rest of that page, a custom EL function vs() backed by a wwel.tld and a Functions class that imports com.opensymphony.xwork.ActionContext (the pre-2.0 WebWork package) and a.getName(), is a historical workaround from the JSP 2.0 era; since the request wrapper does the lookup, no custom function is needed, and the code shown does not compile against org.apache.struts2.ActionContext.

Source: Tag Developer Guide — Access to ValueStack from JSPs

The page rendered <p>Shelf size: 3</p>; a third-party tag whose attribute accepts EL would receive the same 3.

s:property escapes HTML by default, JSP EL never does. With the strings '<b>', the line B30 printed three values:

Source: Tag Developer Guide — property, Attributes

Source: Security Guide — Use Struts tags instead of raw EL expressions

The security guide draws the conclusion (the JSP side of the same rule is on JSP Security): never print incoming values with a raw ${...}; use a Struts tag (or an escaping function such as fn:escapeXml or c:out) instead.

Java records are the case where the pages of this section once disagreed, so this is the single place that states the rule; the other pages link here. Two independent mechanisms decide whether a record component is printed, and both were re-checked on Tomcat 11.0.26 with Struts 7.4.0 and OGNL 3.4.12.

So, for a view that iterates over records, either qualify every name (top.title, or a var and #b.title) or give the record JavaBean getters (public String getTitle() { return title; }), which makes the bare name work again; with a getter the unqualified title printed the value in the same test. A JavaBean model, as the Bookshelf of this page uses, avoids the question. JSP EL is a separate engine: ${b.title} reads records through RecordELResolver in EL 6.0.

Source: Tag Developer Guide — OGNL Basics, Struts-specific language features

Source: Struts 7.4.0 source — CompoundRootAccessor, Struts 7.4.0 source — IteratorComponent