Wildcard Mappings & Method Invocation

A conventional mapping names one URL, one class and one method. The Bookshelf with four operations needs four elements that differ only in a method name. A wildcard mapping states the pattern once.

Wildcard mappings come from Struts 1 and its predecessors (see Struts 1 (Classic) & Migration). The Struts 1 mailreader example that the Core Developer Guide still quotes maps /edit* to Edit{1}Action. In Struts 1 the same need was met with DispatchAction, an action class whose request parameter named the method to call, and with LookupDispatchAction, which looked the method up from a button label. Struts 2 offers three replacements, in the order the framework prefers them: the method attribute with a wildcard, strict method invocation with an allowed list, and, deprecated in practice, dynamic method invocation with the bang character. See the Struts 1 part of the history page for where those ideas came from.

Source: Struts Core Developer Guide — Wildcard Mappings

Source: Struts Core Developer Guide — default.properties

The StrutsPrepareAndExecuteFilter of the servlet filter chain hands the request to the ActionMapper. The default mapper splits the path into a namespace and an action name, removes the extension (action or none, because struts.action.extension is action,, in 7.4.0, so /crud/createBook and /crud/createBook.action are the same request) and, only when dynamic method invocation is on, splits the name at a bang. The configuration then looks the name up inside the namespace. The order of that lookup is the part that people get wrong.

The diagram is the whole rule: a name that has no wildcard is found first and is never compared with the patterns.

The substitution is done by ActionConfigMatcher.convert on a copy of the matched configuration. In 7.4.0 it replaces the placeholders in the following places and in no others.

Source: Struts Core Developer Guide — Wildcard Mappings, the edit* example

A result can be a whole redirect target. The mapping below sends /go/toabout to the action about of the /pages namespace.

Source: Struts Core Developer Guide — Wildcard Mappings

A mapping with no class at all, the last of these placeholder uses, is the catch-all that serves static-looking pages by name. The framework fills in ActionSupport as the default class, and the result location is built from the matched name.

Source: Struts Core Developer Guide — Action Configuration, Action Default

A single * cannot contain a slash, so /pages/../x cannot be built from the name, and the views stay under WEB-INF. A ** in the same position would remove that protection, so do not use it in a result location. The catch-all belongs at the end of the configuration of its namespace, as the documentation says, because anything declared after it that it also matches is never reached (see Which Pattern Wins).

Once a wildcard mapping exists, the framework treats the expanded name as an action of its own. The Core Developer Guide says that such a "virtual" mapping can have its own validations, message resources and type converters, just as a hand-written mapping can.

An exact name always beats a pattern, and a request that matches an exact name never reaches the wildcard matcher. Among several patterns that match, the order of declaration decides, and here the official documentation and the framework disagree.

Two packages with the same two patterns in opposite orders show it.

Source: Struts Core Developer Guide — Wildcard Mappings

So the rule to apply is the one in the framework’s own javadoc: write the specific pattern first and the catch-all last. Physical order is a property of XML; the Convention plugin has no such order, because annotated classes are found by scanning. Since Struts 7.3.0 the names of annotated wildcard actions are sorted most specific first before they are registered (WW-3784), with these keys in order: fewer ** tokens, fewer wildcard tokens (a *, a ** run or a {var} group), more literal characters, then alphabetical order as a tie-breaker. Struts 7.3.0 applied the ** key third and 7.4.0 moves it to the first place, so a/*/* is registered before a/** (WW-5743). XML mappings are unaffected and keep their declared order.

By default an action name has no slash: /admin/book/42 is read as namespace /admin/book, name 42. The Core Developer Guide’s section "Parameters after the action name" shows how to keep the rest of the path in the name. Two constants are needed.

The second constant matters because struts.mapper.alwaysSelectFullNamespace is true in the 7.4.0 default.properties (a change of the 6 to 7 line). With it set to true the mapper takes the whole path before the last slash as the namespace and never looks for a shorter namespace that has a longer action name.

Source: Struts Core Developer Guide — Wildcard Mappings, Parameters after the action name

The constant struts.enable.SlashesInActionNames changes the whole application, not one package. The Core Developer Guide links the side effects to WW-1383, and the validation-file naming for names with slashes is covered on the page Validation. The related constant struts.allowed.action.names holds the regular expression that an action name must match; the default is [a-zA-Z0-9._!/\-]*, and a name that does not match is answered with the default action.

Strict method invocation (SMI) is the rule that decides which Java methods a request may run. It replaces the older "strict DMI" and applies to every way of selecting a method: a method attribute with placeholders, a bang URL and a method: parameter. The check is made by ActionConfig.isAllowedMethod: a method is allowed when it is the method written in the mapping, when it equals execute for a mapping without a method, or when it is on the allowed list of the action.

Dynamic method invocation (DMI) lets the caller name the method in the URL. The bang form book!create.action runs the book mapping with the method create. The parameter form sends a request parameter whose name starts with method:, as in book.action?method:create=x, and the value is ignored. Struts uses the second form for buttons: <s:submit method="create"/> renders as name="method:create".

The Core Developer Guide explains why the framework does not like it. The code scans the action name for a bang and then tricks the framework into calling another method while the configuration is that of execute, including its validation. The framework "believes" it is running execute. The wildcard method feature is implemented differently: the framework behaves as if the mapping Category!create had been written in the file, so the virtual mapping has its own validations, messages and type converters. For that reason the guide says wildcard method selection is preferred. A DMI request also reaches a method that no mapping mentions, and the security guide recommends disabling DMI to avoid XSS in the automatically generated error pages that contain the action name.

The default matcher knows only * and **. When the URL should carry named values, with no file extension and with real regular expressions, set struts.patternMatcher to regex. The Core Developer Guide’s "Advanced Wildcards" section lists four constants.

The official example project wildcard-regex of the struts-examples repository sets struts.patternMatcher to regex and uses the 6.5 DTD. A name can contain {FIELD_NAME}, which matches (.*?) and fills the field of that name, or {FIELD_NAME:REGEX} with a Java regular expression. The groups can still be read as {1}, {2}, and {0} is the whole input.

Source: Struts Core Developer Guide — Wildcard Mappings, Advanced Wildcards

Source: Struts Core Developer Guide — Wildcard Mappings, Advanced Wildcards

Four properties of this matcher are not in the guide, and the scratch runs showed them.

The third matcher puts variables in the namespace. The guide’s example is @Namespace("/users/{userID}") on an action class, which makes /users/10/detail run DetailsAction with the field userID set to 10. The XML form is a package namespace.

Source: Struts Core Developer Guide — Wildcard Mappings, Parameters in namespaces

The guide lists the limits. The named-variable matcher and the wildcard matcher cannot be used together, so a * in an action name stops working. Some tags write the literal namespace with the braces into the HTML (/{user}/2w) instead of the namespace of the request when they guess a namespace from the current action: <s:form>, <s:url> and action= attributes. The workaround is a plain HTML tag with an explicit URL. A custom ActionMapper can do the same job, and the default mapper is the class that calls the pattern matcher.

A value that the pattern extracts reaches the action in one of two ways, and the two ways have different security rules.

Both ways are different from a query-string parameter, which binds only through a setter annotated with @StrutsParameter. The scratch app proves the difference and a consequence.

Source: Struts security guide — Defining and annotating your Action parameters

The first request shows that the path variable binds although the setter is not annotated, and that the query parameter type does not replace it, because the setter is not annotated. The second shows the other side: the setter of BookCrudAction is annotated, so a query parameter with the same name overrides the value that came from the path. Treat a path variable like any other input. Validate it, and do not assume it is the value the route says it is.

A wildcard can build the class name, as in class="org.example.bookshelf.Edit{1}Action", and the default configuration comment of Struts 7 still suggests <action name="*/*" method="{2}" class="actions.{1}">. In Struts 7 that mapping fails by default. The OGNL allowlist (struts.allowlist.enable is on by default from 7.0) allows the classes that the configuration names, and a class that appears only through a placeholder is not named anywhere. The framework calls execute() through OGNL and the call is blocked.

EditBookAction in the same package worked because a different mapping (direct) names it. Adding the package to the allowlist fixes the other class.

Source: Struts security guide — Allowlist Capability

The failure shows as an HTTP 500 and a NoSuchMethodException for a method that exists. An application that logs at WARN level also shows a warning from SecurityMemberAccess that names the blocked class and recommends struts.allowlist.classes or struts.allowlist.packageNames, which is the clue to read. The better design avoids the problem: a mapping whose class comes from request text means that the request chooses which Java class to run, so allowlist a small package of such classes and keep other classes out of it.

The Convention plugin (see Convention Plugin & Annotations) builds mappings from annotations. A wildcard name in @Action is a wildcard mapping like any other, and the plugin’s registration order has no relation to the source order of the classes. That was a bug until 7.3.0: a broad pattern registered before a narrower one that it also matches could shadow it, in an order that differed between JVMs (WW-3784). The sort rule of Which Pattern Wins is the fix, and 7.4.0 corrects the position of the ** key (WW-5743).

Source: Struts Core Developer Guide — Wildcard Mappings, Ordering of annotated wildcard actions

Source: Struts 7.4.0 Version Notes

Source: Apache JIRA — WW-4405

Source: Apache JIRA — WW-3784

Source: Apache JIRA — WW-5743

Struts in Action (Manning, 2002, Struts 1) and Struts 2 in Action (Manning, 2008, Struts 2.0) are listed in the section bibliography. They teach the same problem, and the answers have moved.