Skip to content
javahacks.dev
Struts

Struts 2 to 6 Migration Upgrade Path and Struts 7 Notes

Upgrade Struts 2.5 to 6 and then 7: raise the Java baseline, clean up deprecated APIs and OGNL limits, and move to the Jakarta namespace.

5 min read
Summarize in AI
Flat illustration of a staircase from one version to the next, with the Gradle, Spring Boot and Apache Maven logos.

Struts 2 has a long upgrade path, and the security fixes arrive in new versions. Staying current is cheaper than a late emergency upgrade, as the incident history in Struts 2 security shows. The versions below follow the Apache Struts release lines, and each step should be checked against the migration guide for the exact release.

Step 0: the latest 2.5.x

Move to the final 2.5 release first. Security fixes landed there, and the compiler warnings point at what the next version removes:

XML
<properties>
  <struts.version>2.5.33</struts.version>
</properties>

Build with -Xlint:deprecation and fix every warning. Compile errors found at this stage are cheaper to understand than ones that arrive together with a major version.

Step 1: Struts 6

Struts 6.0 kept the javax namespace and the com.opensymphony.xwork2 packages. The changes people hit:

  • Java and dependencies. The baseline for 6.x is Java 8, and dependency versions such as Commons FileUpload, Log4j 2 and Freemarker are raised. Align the project's versions with what the Struts BOM requires, as in Maven dependency conflicts.
  • OGNL restrictions. Struts 6 limits what expressions can reach. Static method access and member access to many classes are disabled, and an allowlist of classes and packages applies. Expressions that call @java.lang.Math@max(...) or read properties from excluded classes now fail or evaluate to nothing.
  • Defaults. Strict method invocation, a Content-Security-Policy and other safe defaults are enabled in later 6.x releases, which can change which URLs an action accepts.
  • Removed APIs. Classes deprecated in 2.5 are gone. Find replacements from the deprecation notes.

A typical fix for OGNL is to move logic into the action:

java
public int getMaxQuantity() { return Math.max(a, b); }
XML
<s:property value="maxQuantity" />

Prefer a getter to an expression that calls into the JDK.

Step 2: Struts 7

Struts 7 is the Jakarta release. Expect:

  • The servlet API moves from javax.servlet to jakarta.servlet, so you need Tomcat 10.1 or later, Jetty 12 or another Jakarta container. The ripple through dependencies is the one in javax to jakarta.
  • A Java 17 baseline.
  • Packages renamed from com.opensymphony.xwork2 to org.apache.struts2, so imports change for ActionSupport and interceptors. Use search and replace, then compile.
  • Third-party plugins must have Jakarta-compatible versions. Check each plugin before starting.

For the namespace work, an automated recipe saves hours, see OpenRewrite for javax to jakarta.

Verify each step

  1. Run the existing tests at each version, with the application deployed in the target container.
  2. Test the slow paths: file upload, validation, redirects with parameters, error pages.
  3. Scan with the dependency checker for known vulnerabilities.
  4. Compare the struts.xml constants against the migration notes for renamed ones.

Move every Struts artifact together

Struts is split into a core jar and plugins, and the plugin versions are expected to match the core. A build that upgrades struts2-core and leaves struts2-spring-plugin or struts2-convention-plugin on the old line produces NoSuchMethodError or ClassNotFoundException at startup, in classes that have nothing to do with the code you changed. List them all before editing anything:

Shell
./mvnw dependency:tree | grep -i struts

Put one property in the POM and use it for every artifact, so the next upgrade is a one-line change:

XML
<properties>
    <struts.version>6.7.0</struts.version>
</properties>

Check the latest release on the Apache Struts download page for your line before copying a number, since patch releases carry security fixes.

A smoke test before the first step

Upgrading with no tests means the first test is a user. A minimal inventory runs every action once and checks that it reaches a result. The Struts JUnit plugin supplies a base class for it:

java
public class LoginActionTest extends StrutsJUnit4TestCase<LoginAction> {

    @Test
    public void loginPageRenders() throws Exception {
        String result = executeAction("/login.action");
        assertEquals(200, response.getStatus());
        assertNotNull(getAction());
    }
}

One test per URL in struts.xml is enough at this stage. The purpose is to find the actions that no longer start, and a handful of dull tests find them faster than a manual click-through.

What changes in the move to Struts 7

Struts 7 requires Java 17 and the Jakarta namespace, so it belongs to the same project as the move from javax to jakarta, described in the Jakarta rename. The container has to move as well, to Tomcat 10.1 or later or another Servlet 6 container. The framework also moved its own packages from com.opensymphony.xwork2 to org.apache.struts2, so custom interceptors, result types, converters and validators need their imports updated, and so does any struts.xml entry that names such a class. A global search for com.opensymphony across Java files and XML is the checklist.

OGNL restrictions tighten with each line

Recent releases limit which classes and members an OGNL expression may reach, as part of the response to the remote code execution advisories. An expression that worked because it could call a static method on a utility class, or read a property of a JDK type, can start failing with an error about a blocked class. Treat such a failure as a prompt to move the logic into the action, and list a class in the allow settings only when the access is truly intended. Read the security notes for the target release in full, because the defaults change between minor versions.

Common failures after each step

SymptomLikely cause
Startup fails with NoSuchMethodError in the frameworkA plugin jar from the old line is still on the classpath
There is no Action mapped for namespaceThe convention plugin scans different packages, or its default namespace rules changed
Parameters stop bindingThe parameter allow-list now rejects the name
Validation messages disappearResource bundle lookup order changed, or the file was renamed
A result page renders blankA tag library URI changed, check <%@ taglib %> lines
ClassNotFoundException: javax.servlet... on 7A library built for the old namespace

Fix the failures in the order they appear in the startup log, because each one often hides the next. Re-run the smoke test after each fix, and commit when it passes, so a bad step can be reverted without losing the steps before it.

Where this does not apply

A Struts 1 application cannot take this route, see Struts 1 to 2. If the application is staying for only a short time, the cheaper option may be a move off Struts, see migrating to Spring MVC. The reference is the official Struts migration guides, and the Struts downloads page lists the supported lines.

Also inJakarta EE
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.