Configuration: struts.xml & Constants

A Struts application needs exactly one configuration file, and it is not a Struts file: web.xml must register the StrutsPrepareAndExecuteFilter (see Servlet Fundamentals for filters and the deployment descriptor). Everything else is optional, because the framework ships with its own configuration and every setting has a default. The documentation lists the files like this.

Two more files are loaded from the class path although the table does not list them: struts.properties, the legacy properties file (struts.properties, the Legacy File), and the two files struts-default.xml itself includes, struts-beans.xml (the framework’s own beans) and struts-excluded-classes.xml (the classes and packages OGNL may never touch). The same page describes how static content (the JavaScript and CSS of the UI tags) is served by the filter, which matters for the filter mapping (The Filter and Its Init-Params in web.xml).

Source: Struts — Configuration Files

Source: Struts — Configuration Elements

The Dispatcher (the object the filter creates in its init method) builds the configuration by registering providers one after another. For XML elements that define packages, later and earlier files are merged; for constants, which are plain name and value pairs, the provider registered last wins. The 7.4.0 Dispatcher.init() registers them in this order.

The documentation page "Constant Configuration" gives a shorter list ("struts-default.xml, struts-plugin.xml, struts.xml, default.properties, web.xml, struts-deferred.xml") and places default.properties after struts.xml; the "Plugins Architecture" page gives the XML part correctly (default, plugins, struts.xml, deferred). The 7.4.0 source and the experiment below show that the defaults file is read first, which is why a value in struts.xml can override it.

Source: Struts 7.4.0 source — Dispatcher.init()

Source: Struts — Plugins Architecture

struts.xml is the main file. It must be on the class path (in a Maven project, src/main/resources/struts.xml, which ends up in WEB-INF/classes), and it begins with a DOCTYPE that names a Struts DTD. The DTD is validating: the parser rejects an element in the wrong place when the application starts.

The content model is (package|include|bean|constant)*, bean-selection?, unknown-handler-stack?: packages, includes, beans and constants may be mixed in any order, but bean-selection and unknown-handler-stack must come last. The root element also takes an optional order attribute (Include Configuration).

The newest DTD is struts-6.0.dtd, and it is the right DOCTYPE for Struts 7.4: a request for https://struts.apache.org/dtds/struts-7.0.dtd returns 404 (checked 2026-10-08), and the file shipped inside struts2-core-7.4.0.jar (struts-default.xml) itself declares Struts Configuration 6.0.

The package extends struts-default, the abstract package of struts-default.xml that supplies the result types and the interceptor stacks (struts-default.xml); an action in a package that does not extend it has no defaultStack.

Source: Struts — struts.xml

Source: Struts Configuration DTD 6.0

The "divide and conquer" strategy for large configurations is the <include> element. The file attribute is a class path resource name, resolved from the root of the class path (not relative to the including file), and each included file must have the same format as struts.xml, including the DOCTYPE. In a team, each module owns its file.

The documentation shows only literal file names; the 7.4.0 XmlConfigurationProvider also accepts a pattern with *, as the example does, and resolves it against the class path when the file loads. Four behaviours of includes follow from the 7.4.0 source; the last was also observed.

Source: Struts — Include Configuration

Constants are the framework’s settings. The documentation names two roles: overriding a setting such as the maximum upload size or devMode, and choosing which implementation of a bean type the framework uses. A constant is always a string name and a string value; the name is conventionally struts. plus a dotted path, and Struts exposes every built-in name as a field of the StrutsConstants class.

Source: Struts — Constant Configuration, "Constant"

A constant whose name is misspelled is accepted without a message: adding <constant name="struts.devmod" value="true"/> to the Bookshelf’s struts.xml reloaded cleanly, the application kept answering and devMode stayed false (observed). The framework looks constants up by name and nobody looks up struts.devmod.

The framework’s own configuration is the file struts-default.xml in the core JAR. It is not copied into the application: it is loaded first by the Dispatcher (step 2) and it supplies

Your packages extends="struts-default" to inherit all of that. The page that shows the whole file also says how to leave it out: "see the struts.configuration.files setting in default.properties". That name does not exist in 7.4.0: it is not in default.properties, not in StrutsConstants, and not read by the Dispatcher. The working mechanism is the config filter init-param, a comma-separated list of XML files that replaces the default list struts-default.xml,struts-plugin.xml,struts.xml.

With that list the Bookshelf’s /books answered 200 and the action of the plugin JAR (/plugin/ping, which answered 204 before) answered 404, because struts-plugin.xml was no longer in the list; with only struts-default.xml in the list, /books answered 404 too (observed). A file whose name does not end in .xml is rejected with Invalid configuration file name. struts-deferred.xml is always loaded afterwards.

Source: Struts — struts-default.xml

Struts has its own small dependency injection container (the documentation compares it with Google Guice). It builds the key framework objects, which is how any part of the framework can be replaced, extended or removed, and how plugins add Spring or SiteMesh support. Most applications never touch it, but <bean> is also the way to register your own service so the framework can inject it into actions (see Dependency Injection and CDI).

A bean is used in one of two ways: created by the container and injected into other objects (usually with type), or, with static="true", only having values injected into its static members so that objects the container does not create can still receive constants.

The Bookshelf registers two implementations of a catalogue interface and picks one by name.

ConfigAction (above) asks for the sorted one with @Inject("sorted"), and the response confirms the choice.

titles is sorted, so the container injected SortedCatalog, and the other values are the effective constants of the fourth step of Load Order: Who Wins (this run used the WAR with its struts.properties).

The injected field can be private. A constructor with parameters is not supported for an action: the first attempt to inject the same four values through an @Inject constructor made the whole application fail to start with Unable to load configuration and Caused by: Action class [org.example.bookshelf.ConfigAction] does not have a public no-arg constructor (observed); every URL of the context then answered 404.

The documentation’s own bean example registers com.opensymphony.xwork2.ObjectFactory. In Struts 7 the package was renamed (the 6 to 7 migration guide: "the com.opensymphony.xwork2 package has been renamed/migrated to org.apache.struts2`"), and in 7.4.0 the type is `org.apache.struts2.ObjectFactory; use the org.apache.struts2 names in every type= attribute.

Source: Struts — Bean Configuration

Source: Struts — Dependency Injection

Source: Struts 7 Javadoc — @Inject

A plugin is a JAR on the class path. If it contains struts-plugin.xml at its root, Struts loads it with the same parser and format as struts.xml, before struts.xml, so a plugin can add packages, results, interceptors and actions, override constants and register beans. A struts-deferred.xml is loaded after everything else, which is where a plugin declares an extension point that must see the final configuration. Because struts.xml comes later, the application always has the last word over the plugin’s constants.

Put into WEB-INF/lib/bookshelf-plugin.jar, this file added the /plugin/ping action with no change to the application’s struts.xml (curl answered 204), and its constants lost to the application’s (first row of the table in Load Order: Who Wins). The same mechanism is what the Convention, JSON, Spring, Tiles and other official plugins use; the developer guide to writing a plugin, extension points and the plugin registry is the "Plugins Architecture" page.

Source: Struts — Plugins Architecture

Two constants decide whether configuration changes need a restart.

The development-mode page lists the same three effects, and warns that the option "can expose sensitive data of your application". In 7.4.0 the StrutsBeanSelectionProvider does the switching: when devMode is true it sets struts.i18n.reload, struts.configuration.xml.reload and a zero FreeMarker cache delay only if the application has not set them. The reload is conditional: the ConfigurationManager asks every provider needsReload() and rebuilds only when a tracked file changed, so the cost is a file-timestamp check per request, not a rebuild.

The Bookshelf sets struts.configuration.xml.reload to true explicitly, and the reload behaviour was verified in the exploded WAR without restarting Tomcat.

The same run showed three limits.

Production: leave both reload constants off, devMode false. The ${env.STRUTS_DEV_MODE:false} form of Value Substitution keeps that safe by default.

Source: Struts — Development Mode

Source: Struts — Reloading configuration

The documentation names two ways to enable Struts: the single StrutsPrepareAndExecuteFilter, or the pair StrutsPrepareFilter and StrutsExecuteFilter when another filter (SiteMesh) has to sit between the prepare and execute phases. Both live in org.apache.struts2.dispatcher.filter. The Bookshelf’s web.xml is the Servlet 6.1 form (version="6.1", https://jakarta.ee/xml/ns/jakartaee).

Source: Struts — web.xml

The init-params the 7.4.0 Dispatcher reads, besides every constant, are these.

Mapping the filter to /* is "the preferred way". With a narrower mapping such as *.action the filter no longer sees the requests for its static files and a second <filter-mapping> for /static/* is needed, and the constant struts.action.excludePattern (a comma-separated list of regular expressions, for example .*unfiltered.*,.*\.nofilter) makes the filter pass chosen URLs through untouched. A <taglib> entry in web.xml for the Struts tags is "neither required nor recommended": the TLD in the core JAR is discovered by the container.

Static content has a path mismatch in the documentation. The Configuration Files page says requests that start with /struts/ are served from org.apache.struts2.static and template; in 7.4.0 the prefix is struts.ui.staticContentPath, default /static, and GET /g8conf/struts/utils.js answered 404 while /g8conf/static/utils.js answered 200 (observed).

Source: Struts — Static Content

Applications and books of the Struts 1 era configure with struts-config.xml, a *.do servlet mapping and a plug-in element. The elements have direct, simpler equivalents in Struts 7. Struts 1 reached end of life on 2013-04-05 (see introduction and history), and its documentation is no longer online.

The two configuration systems share nothing at run time: Struts 1 is not part of Struts 7, and the migration guides are the reference.

Source: Struts — Struts 1 end-of-life announcement

The 6 to 7 migration guide says the OGNL limit "has been reduced from 200 to 150", but the 7.4.0 default.properties has struts.ognl.expressionMaxLength=256 and the security guide also says 256; this page uses 256 because that is what the JAR contains.

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

Source: Struts — Version Notes 7.4.0

Struts in Action (Manning, 2002) configures Struts 1 with struts-config.xml; its chapters on first application and configuration are covered by the table in From struts-config.xml to struts.xml. Struts 2 in Action (Manning, 2008, both listed in the section bibliography) is the Struts 2.0 book and its chapters on plugins and configuration still describe the right ideas and the wrong details.

The official pages need the same care: the pages quoted above still show com.opensymphony.xwork2 names, the Java EE 3.1 namespace in the web.xml examples, struts.configuration.files, the /struts/ static prefix and the "default.properties in your application" advice, and none of those work as written in 7.4.0.