Struts Getting Started

Struts 7 is an action-based MVC framework that installs itself in a web application as a single servlet filter. A request is matched to an action (a Java class) by name, the action does its work, returns a string, and that string selects a result (usually a JSP). Four things are needed to bring that to life:

The Bookshelf of this page is small on purpose: a welcome page, a "hello" action that shows a message produced by a model object, and a "books" action that lists the catalogue and accepts an optional author filter. Later pages of Part II grow it into actions with forms, validation, interceptors and CRUD.

Source: Struts — How To Create A Struts Web Application, Java Requirements

Source: Apache Struts — End of Life versions

The figure shows the whole idea of this page. The dotted lines are the two files that wire Struts into the web application, pom.xml and web.xml; the solid line is what happens to each request, and struts.xml is the table the filter consults.

The tutorial assumes a working knowledge of Java, filters, JSP and tag libraries, JavaBeans, HTML and HTTP, web containers and XML; the Struts site collects the background in its Key Technologies Primer, and this section covers the same ground in Servlet Fundamentals and in Part I. To follow along, the machine needs only what the section Getting Started page installs: a JDK 21, Maven and Tomcat 11 (see Installing Tomcat 11). The commands below assume Tomcat is unpacked in $CATALINA_HOME and listens on port 8080.

A Struts application is a normal WAR. Everything that makes it a Struts application is configuration that Struts reads at start-up, so a mistake in web.xml or struts.xml shows up when the web application is deployed, not when the first request arrives. That is a useful property when debugging, and the later sections show the messages.

Source: Struts — How To Create A Struts Web Application

Source: Apache Struts — Key Technologies Primer

Struts publishes Maven archetypes (struts2-archetype-blank, struts2-archetype-convention and others), and mvn archetype:generate -Dfilter=org.apache:struts lists them. The archetypes, however, stop at version 6.0.0: the metadata of struts2-archetype-blank on Maven Central names 6.0.0 as both latest and release (last updated 2023-03-15), while struts2-core is at 7.4.0. An archetype-generated project therefore pins a Struts 6.0 baseline and the javax-era conventions of its time, and it still has to be upgraded by hand. Building the project from an empty Maven WAR is only seven small steps, takes less than ten minutes, and teaches where each piece lives; the official tutorial does the same.

The Struts examples repository (apache/struts-examples) holds the finished projects of every Getting Started tutorial. The two used here are basic-struts (the empty application of "How To Create A Struts Web Application") and helloworld (its extension from "Hello World Using Struts"); the other tutorials of the series, from "Using Tags" to "JasperReports", are projects of the same repository and are used by the pages of Part II that cover their topic.

Source: Struts — Maven Archetypes

Source: apache/struts-examples on GitHub

Maven’s standard WAR layout is all Struts needs. struts.xml goes in src/main/resources, so that it lands in WEB-INF/classes and is found on the class path; the views go under WEB-INF so that no one can request them directly.

Source: Struts — Configuration Files

The second figure follows the files from the build to the running container: what ends up in WEB-INF/classes and WEB-INF/lib, and what Struts reads when the filter starts. The WAR built for this page contains four classes, struts.xml and log4j2.xml in WEB-INF/classes, the two views and web.xml under WEB-INF, index.jsp at the root and fifteen jars in WEB-INF/lib (struts2-core 7.4.0 with ognl 3.4.12, freemarker 2.3.35, javassist, caffeine, commons-lang3, commons-text, commons-io, commons-fileupload2 2.0.0-M5 and webjars-locator-lite, plus log4j-api and log4j-core 2.26.1).

The tutorial adds struts2-core to the dependencies and, optionally, uses the bill of materials so that no Struts or Log4j module needs a version of its own. The BOM is the better way for a new project, because every Struts module (the plugins that later pages add) is then managed to the same version. The Jakarta Servlet and Pages APIs are provided, since Tomcat supplies them.

Source: Struts — How To Create A Struts Web Application, Step 4 (BOM and Log4j 2 dependencies)

Four details of this file deserve a comment.

Source: struts2-bom 7.4.0 on Maven Central

Source: Apache Struts — Plugins

Struts 2 and later are filter-based; the ActionServlet of Struts 1 no longer exists. The filter org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter is the single entry point of the framework: when the web application starts, its init method builds the configuration and the dispatcher; for each request its doFilter decides whether the request is an action request. If it is, the filter runs the action and the result and does not call the rest of the filter chain; if it is not, the request is passed on to the next filter and eventually to the container’s default servlet or the JSP servlet.

Source: Struts — web.xml, Simple Example

Source: apache/struts-examples — helloworld web.xml

The deployment descriptor uses the Jakarta EE 11 schema (version="6.1"); the tutorial’s file declares version 6.0 and the web-app_6_0.xsd schema, and either is accepted by Tomcat 11. The welcome file /index is explained in the section on the index page below. What the descriptor must contain, and what it may contain, is summarised in the next table.

Source: Struts — web.xml

Source: Struts — Static Content, Preventing Struts from Handling a Request

A mapping other than /* is where most first-time problems start. With *.action the filter ignores a request for /books, and the extension rules of the next section decide whether the action is still reachable. Keeping /* and excluding the paths that Struts must not touch, with struts.action.excludePattern, is the safer pair. The servlet-level meaning of the filter, its position in the chain and its dispatcher types are explained in Servlet Fundamentals, Filters, and the architecture and request lifecycle page of Part II follows the request through the filter and beyond.

struts.xml is the core configuration file; it must be on the class path of the web application, usually in WEB-INF/classes, which is where Maven puts src/main/resources. The file may include other files, and a JAR can carry its own struts-plugin.xml that is plugged in automatically; the page on configuration files and constants covers load order, include, bean and the constants in detail. For the first application a minimal file is enough.

Source: Struts — How To Create A Struts Web Application, Step 6 — Create struts.xml

Source: Struts — Hello World Using Struts, Step 4

Read the file from the top.

Source: Struts — Package Configuration

Source: Struts — Action Configuration, Action Mappings

Source: Struts — Result Configuration, Result Elements

The Hello World tutorial adds three pieces: a model class that holds the message, an action class that creates the model and returns SUCCESS, and a JSP that displays the message. The Bookshelf version keeps the same structure, with different names and the package layout shown above.

Source: Struts — Hello World Using Struts, Step 1 — The Model Class

Source: Struts — Hello World Using Struts, Step 2 — The Action Class

The action extends org.apache.struts2.ActionSupport, which implements Action and supplies the constants SUCCESS, INPUT, ERROR, NONE and LOGIN, plus validation, localization and message support that later pages use. Note the package: in Struts 7 the classes of the old com.opensymphony.xwork2 package were moved into org.apache.struts2 (with a few sub-packages, such as org.apache.struts2.interceptor.parameter for @StrutsParameter), and code written for Struts 2.5 or 6 that imports com.opensymphony.xwork2.ActionSupport no longer compiles. The framework creates a new instance of the class for each request, calls execute, and reads the string it returns. The getMessageStore getter is how the view reaches the model: the JavaBean convention, a public getX method for property x, is the contract between action and JSP.

Source: Struts — Hello World Using Struts, Step 3 — The View

The taglib directive binds the prefix s to the Struts tag library, whose URI is /struts-tags. The tag s:property evaluates its value as an OGNL expression against the value stack, a stack of objects whose top is the action: messageStore.message calls getMessageStore() on the action and then getMessage() on the returned object. s:property escapes HTML by default.

Source: Struts — property tag

The second action shows request parameters, which is where Struts 7 differs most from what older tutorials show. It lists the catalogue and takes an optional author parameter.

Source: Struts — Hello World Using Struts, Step 1 (the model class)

The record carries explicit getX methods because the view reads it with bare names inside s:iterator (<s:property value="title"/>). A bare name is looked up on the value stack through JavaBean getters, and a record’s accessor title() is not one, so without the getters the list items would be empty; the allowlist entry alone does not change that. Qualified paths such as top.title would read the component without getters (Java Records in OGNL). A plain class with getters works identically.

Source: Struts Security — Defining and Annotating Your Action Parameters

Source: Struts — Struts Parameter Annotation

The params interceptor of the default stack copies request parameters onto the action by calling setters through OGNL. A parameter named author becomes setAuthor(...). That is exactly the surface through which remote-code-execution vulnerabilities reached Struts for years, so since Struts 6.4 (default in 7.0, struts.parameters.requireAnnotations=true) a setter that should receive request data must be annotated with @StrutsParameter; unannotated setters are not reachable from the request. The annotation has a depth element (default 0, a simple property) for nested objects and collections, which the page on parameter injection covers.

Source: Struts — iterator tag

s:iterator pushes each element onto the value stack in turn, so inside the loop title resolves against the current Book first and the action second. This is the stack at work, and the reason the element’s properties need no prefix. The tag s:url builds the URL of an action by name; the next section shows what it produces.

Source: Struts — Hello World Using Struts, Step 5 — Create The URL Action

Source: Struts — url tag

The page links to actions, not to JSP files. Linking to actions is the habit the Struts documentation recommends: the link does not know which page renders the answer, and the action can run before the page does. s:url takes the action name, adds the context path and the default extension, and, on the first request of a browser that has no session cookie yet, the container’s ;jsessionid suffix:

(The session identifier is the container’s URL rewriting, explained in Servlet Fundamentals, Sessions.)

Why the welcome file is /index: Struts serves index through the filter, and the index.jsp in the web application root is forwarded to by the action index, never requested directly. If the container’s welcome file is index.jsp, a request to the context root runs the JSP outside any action invocation, and s:url action='hello' fails there. On Struts 7.4.0 this was reproduced: a direct request to /index.jsp answers status 500 with JasperException and the root cause NullPointerException: Cannot invoke "org.apache.struts2.ActionInvocation.getProxy()" because "invocation" is null. The struts-examples projects avoid it with the welcome file /index (or index), which Tomcat maps to the action, and the tutorial text avoids it by telling the reader to open index.action. The tag also has a namespace attribute; with <s:url action='hello' namespace='/'/> a direct request to the JSP works.

Source: Struts — url tag, Attributes

Build the WAR with Maven and copy it to Tomcat’s webapps directory; Tomcat unpacks it and uses the file name, without the extension, as the context path (/bookshelf-struts).

Source: Tomcat 11 — Deployer How-To, Deploying on a running Tomcat server

Development mode stays off unless the environment of Tomcat’s JVM sets STRUTS_DEV_MODE=true, for example a local run started with STRUTS_DEV_MODE=true "$CATALINA_HOME/bin/catalina.sh" run; the variable is read when the configuration loads, so set it before Tomcat starts. Production simply does not set it. Other ways to deploy (the Tomcat Manager, Cargo, Docker) are in Deploying to Tomcat. The requests below are the ones the verification run answered. The first shows the action hello, the second the action books with the author filter. The verification run deployed the same WAR under another file name, so only the context path in the outputs differs from a deployment of bookshelf-struts.war.

Source: Struts — Hello World Using Struts, Step 6 — Build the WAR File and Run The Application

Without the author parameter the same action lists the three books. A browser also shows the Struts security headers that the 7.4.0 default stack adds to every action response: Cross-Origin-Embedder-Policy-Report-Only: require-corp, Cross-Origin-Opener-Policy: same-origin and Vary: Sec-Fetch-Dest,Sec-Fetch-Mode,Sec-Fetch-Site,Sec-Fetch-User (the interceptors coep, coop and fetchMetadata). The JSP’s default session="true" also makes the container send a JSESSIONID cookie with the first response, even though nothing stores anything in the session. The page on security headers explains the first three; the second is the page directive of Part I.

The tutorial closes with "How the Code Works". The version below is the same story with the 7.4.0 names, and with the lines that the DEBUG logging of this page produced for GET /hello.

Source: Struts — Hello World Using Struts, How the Code Works

The same sequence for the architecture, with the action mapper, the container and the configuration providers named, is the subject of the architecture and request lifecycle page of Part II; the mechanics of the dispatcher forward are the ones of Servlet Fundamentals, RequestDispatcher.

The default struts.action.extension is action,, in 7.4.0 (default.properties): the extension .action and the empty extension are both accepted. The old *.do extension of Struts 1 is not. The requests of this table were made against the verification application; /hello and /hello.action reach the same action.

Source: Struts — default.properties

Source: Struts — ActionMapper

Two rows deserve attention. The status 200 of the devMode problem page is a trap for monitoring tools that expect a 404 for an unknown URL, and the page exposes class names and stack traces; both are reasons to keep struts.devMode off outside development. The default-action-ref makes the application answer any URL with the home page, which can be convenient for a prototype and is a poor choice for a service that should return a 404; each package may have one default action, and only one default action per namespace is meaningful.

Source: Struts — Action Configuration, Action Default

struts.devMode is the single constant that most changes how a Struts application behaves while it is being written. The official page on development mode lists what true does, and it was confirmed against the verification application:

The default is false, "because it has a significant impact on performance, since the entire configuration will be reloaded on every request". The official page opens with the warning that the option must be turned off before deploying to production, because it can expose sensitive data. The constant may also be set in a legacy struts.properties file or as an init-param of the Struts filter in web.xml; default.properties is the framework’s own file inside the core jar, not an application file (Configuration: struts.xml & Constants). The struts.xml form used here is the one the documentation calls preferred. Part II has a page on debugging, development mode and logging.

Source: Struts — Development Mode

Source: Struts — Development Mode, What does it do?

The first tutorial notes that Struts can use an XML file, annotations, or both to relate a URL, a class and a view page. The XML route of this page is the one every other Struts source documents, and it is explicit: the whole mapping is in one file. The annotation route is the Convention plugin (struts2-convention-plugin, in the BOM), which scans the class path for actions, derives action names from class names and lets @Action and @Result override the defaults. It supersedes the Codebehind plugin (removed in 2.5) and the zero-configuration actionPackages of Struts 2.0. The same action of the Bookshelf, written with annotations, needs the plugin as a dependency:

and no entry in struts.xml:

With about.jsp containing <s:property value="version"/>, a request to /about answered <p>Bookshelf version 1.0.0</p> in the verification application, with no action element in struts.xml. The class is found because its package is ...action, one of the package names the plugin scans by default. The page on the Convention plugin and annotations in Part II covers the naming rules, @Namespace, @ParentPackage, @InterceptorRef, @ResultPath and the choice between the two approaches.

Source: Struts — Convention Plugin, Hello World

Source: Struts — Convention Plugin, Action Annotation

Any Maven-capable IDE opens the project. For IntelliJ IDEA the original Struts 2 plugin was donated by JetBrains to the Apache Software Foundation in 2024 and is maintained as part of the Struts project; it is installed from the JetBrains Marketplace (release notes and downloads of every version are published in the apache/struts-intellij-plugin repository). The Struts Getting Started index lists the plugin page next to the tutorials. Debugging a WAR from an IDE is outside this page; the Jetty plugin of the section Getting Started page and Tomcat’s remote-debug port are the portable choices, and the IDE guides of this site (issue #116) are the place for IDE-specific steps once they exist.

Source: Struts — IntelliJ IDEA plugin

Source: Struts — Development Mode, Page rendering is slow

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

Source: Struts — Version Notes 7.4.0

Source: Apache Struts — End of Life versions

The four reference books of the section were written for JSP 1.2 and Servlet 2.3 (the JSP and JSTL books), Struts 1.x (the Struts 1 book) and Struts 2.0 (the Struts 2 book). A reader who starts with them meets the following differences, all checked against the current documentation.

Source: Struts — web.xml

Source: Struts — 2.3 to 2.5 migration guide

Source: Struts — 2.5 to 6.0.0 migration guide

Where the official pages disagree with the verified behaviour, this page follows the behaviour. The inconsistencies found while writing it are the tutorial’s omission of the allowlist constant, the stale com.opensymphony.xwork2.ActionSupport named by the Action Configuration page, the "struts-core.jar" named by the web.xml page (the artifact is struts2-core), the Servlet API 2.5 baseline that the tutorial gives for Struts 6, and the DTD versions (6.0 on the site, 6.5 in the examples); they are collected in the migration and errata page of the section.

The tutorials continue with "Using Tags", "Coding Actions" and "Processing Forms". In this section the next pages of Part II are the architecture and request lifecycle (the filter, the action mapper, the proxy and the interceptors in detail), the configuration page with the table of the struts.* constants, the pages on packages and namespaces, actions, results and interceptors, and later the tag pages and the form-processing and validation pages that grow the Bookshelf into a CRUD application. Each reuses the bookshelf-struts project of this page.