Other Plugins

The plugin index lists 30 entries. Whether an entry can be used with Struts 7.4.0 is a different question from whether it is listed: the index keeps the removed and the deprecated plugins, and the struts2-bom 7.4.0 still has entries for artifacts that do not exist at 7.4.0. The table below was built by reading the index, the BOM and the maven-metadata.xml of every struts2-*-plugin artifact on Maven Central. A plugin whose latest Central version is not 7.4.0 cannot be used with Struts 7.4.0 as it stands.

Source: Apache Struts — Plugins

Source: struts2-bom 7.4.0 on Maven Central

Source: Apache Struts — Plugin Dependencies (Maven site)

All plugin versions are managed by the BOM, so a dependency is written without a version once the BOM is imported (the pom.xml of the first page of this part shows the import). A dependency on a BOM entry that has no 7.4.0 artifact (the embedded JSP, GXP, OSGi and Plexus plugins) fails to resolve; that is the first sign that a plugin is no longer maintained.

All examples below are classes and mappings of one scratch application, built as a Maven reactor and deployed as g11other.war on Tomcat 11.0.26, Java 21, Struts 7.4.0 (BOM). It has three modules: bookshelf-badge-api (two interfaces), bookshelf-badge-plugin (a Struts plugin jar written in the section on writing a plugin) and bookshelf-app (the WAR). The WAR holds a Book bean with title, author and year, and an action BookListAction that exposes three books and the shelf name:

Source: Apache Struts — How To Create A Struts Web Application

The dependencies of the WAR, without versions (the BOM manages the Struts ones), are the seven plugins this page uses plus the two libraries that two of them need:

Source: Apache Struts — JasperReports 7 Plugin, Installation

A Struts plugin is an ordinary jar. The framework looks for jars on the class path that contain a struts-plugin.xml at their root, loads that file with the same parser and format as struts.xml, and may also find a struts-deferred.xml. The official page names what the two files make possible: a plugin can define new packages with results, interceptors and actions, override framework constants, and introduce implementations of extension points. The order matters, and the page of this part on configuration files and constants shows it with a measured table; in short, the framework loads its own defaults, then every struts-plugin.xml found, then the application’s struts.xml, then every struts-deferred.xml.

Source: Apache Struts — Plugins Architecture

Two behaviours of that order were verified on the scratch application. The plugin of the next section sets a constant to bracket in its struts-plugin.xml, and the application’s struts.xml sets the same constant to angle; the application’s value won (the output of the request is shown in the next section), which is the rule that the application has the last word. And a bean-selection declared in the plugin’s struts-deferred.xml saw the application’s value, because it ran after struts.xml. The bundled plugins are good examples of what a plugin contains. This is the content of the Config Browser and XSLT plugin descriptors of 7.4.0 (abbreviated, with the license comments removed), which show the two extremes: a plugin made only of actions, and a plugin made of a single package and one result type.

Source: Apache Struts — Plugins Architecture, Plugin Examples

The recurring pattern is a package that extends struts-default and registers a result type. A plugin does not appear in the application’s own configuration: the application’s package extends the plugin’s package (extends="xslt-default") to get the result type, or names the type directly in a result-type element. The descriptors of all the 7.4.0 plugins still declare the Struts 6.0 DTD (struts-6.0.dtd), because a 7.0 DTD was never published (the page on configuration files records that the URL answers 404); the descriptors you write should do the same. The plugin can also ship static files: everything under /static in the jar is served at /static/... by the framework’s static content loader, and the example below shows it.

The official tutorial on extending an application with custom plugins shows the idea in four steps: an interface in a jar that both the application and the plugin see, a plugin jar with an implementation registered as a bean, an action that asks the container for all beans of that interface, and a JSP that lists them. The tutorial’s code has typos and old package names (see Where the Official Pages and the Older Books Are Outdated), so this section does the same job with the current API on the Bookshelf: a badge for a book ("classic", "new").

The interface lives in its own jar so the application and the plugin do not depend on each other. It is the only thing both sides compile against:

Source: Apache Struts — Extending an Application with Custom Plugins, The Plugin

The plugin jar has two implementations, a Struts action that lists them, a FreeMarker template, a static file and the descriptor. The class of the action asks the container for every bean of the interface by name; the container is the Struts dependency injection container that the page on configuration files describes, and its package in 7.4.0 is org.apache.struts2.inject, not the com.opensymphony.xwork2.inject of the older documentation:

Source: Apache Struts — Extending an Application with Custom Plugins, The Action

The descriptor registers the beans by type and unique name, defines one constant, a package in its own namespace and a result that uses a template inside the jar (the FreeMarker result loads templates from the class path too):

Source: Apache Struts — Configuration Files

The template badges/list.ftl and a stylesheet static/badge.css are in the same jar. After dropping the jars into the WAR, the plugin’s action and its static file answered without a line in the application’s struts.xml:

Source: Apache Struts — Plugins Architecture, Static Resources

The formatter is the second kind of extension: a plugin-defined extension point. The next section explains how it is wired.

An extension point is a name (a constant) that locates a bean by name and injects it where the framework or a plugin asks for it. The official page puts it as a bridge between an interface and its final implementation, which "is not a bean" and cannot be injected by itself. The core defines its own in StrutsBeanSelectionProvider: the 7.4.0 source has more than 60 alias calls, each tying a class to a constant such as struts.objectFactory, struts.mapper.class, struts.multipart.parser or struts.date.formatter. The application selects an implementation by registering a bean and pointing the constant at its name, as the plugins page shows:

Source: Apache Struts — Plugins Architecture, Extension Point Provided by the Core

The table lists a selection of the extension points of 7.4.0 with the class they are declared against. The official page has the same table, but every type in it from the XWork days is out of date; the current packages were read from the imports of StrutsBeanSelectionProvider in the 7.4.0 sources jar.

Source: Apache Struts — Plugins Architecture, Extension Points

A plugin can define its own extension point, and the Bookshelf plugin does. It declares an interface (BadgeFormatter), a bean-selection provider that ties a constant name to it, and an entry in struts-deferred.xml. The provider extends AbstractBeanSelectionProvider and has a no-argument constructor, as the official page says; alias uses the constant’s value as the bean name and makes that bean the default instance of the type:

Source: Apache Struts — Plugins Architecture, Plugin-defined Extension Points

The same arrangement is in the Velocity plugin of 7.4.0: its struts-deferred.xml holds <bean-selection name="velocityBeans" class="org.apache.struts2.views.velocity.VelocityBeanSelectionProvider"/>, as the official page shows it. The application now replaces the plugin’s formatter by registering a bean of the interface and pointing the constant at it; the plugin’s own default (bracket) is overridden because struts.xml is loaded after struts-plugin.xml:

Source: Apache Struts — Plugins Architecture, Developing New Extension Point

The angle brackets are escaped because the FreeMarker result of 7.4.0 escapes HTML by default (see FreeMarker and Velocity Views). One mistake cost me a failed first run and is worth remembering: the injection point of a bean that stands behind an extension point is injected without a name. I first wrote @Inject("struts.badge.formatter"), which asks the container for a bean called struts.badge.formatter, found none (the parameter is optional) and printed the badges without brackets; a plain @Inject(required = false) receives the bean the constant selected. A plugin written like this can also be controlled by the same constants as the framework: any constant its struts-plugin.xml defines is overridden by the application’s struts.xml.

The config browser is a read-only view of the configuration the framework loaded, served by actions in the /config-browser namespace. Its official page says it should be used only during development and that access to it "should be strictly restricted". Installing it is a dependency and nothing else; the descriptor above shows the package. In the scratch application http://localhost:18080/g11other/config-browser/index redirects to actionNames and shows the namespaces and the actions of each one:

Source: Apache Struts — Config Browser Plugin, Usage

The reason for the warning is plain: everything on those pages is information that an attacker would otherwise have to guess, including the effective security constants and the version of every library. The plugin does not check struts.devMode (it worked with the default false) and has no authentication of its own, so the application has to keep it out of production. There are two ways. The simplest is a Maven profile that adds the dependency only for development builds, so the jar is not in the WAR that is deployed. The second is a standard security constraint in web.xml that requires a role nobody holds in production, or one that only an operations realm grants; with this constraint in the scratch application every configuration browser URL answered 403:

Source: Apache Struts — Config Browser Plugin, Description

For debugging during development the plugin is a convenient look at "why does this URL not map" and "which constant won", and the debugging page of this part discusses it next to struts.devMode and the debugging interceptor. The pages show their age (a footer that reads "2003 - 2015" and a menu entry about Maven 2), but they worked on Struts 7.4.0 and Tomcat 11.

The xslt result serialises the action into an XML document and runs a stylesheet over it. It was part of the core up to 6.1.x (the 6.1.2 jar holds org.apache.struts2.views.xslt.XSLTResult and struts-default.xml registers the type); since 6.2.0 (WW-5264) it is the struts2-xslt-plugin, with the package org.apache.struts2.result.xslt and the package xslt-default that registers the type. Without the plugin on the class path, type="xslt" is an unknown result type; with the plugin, the application’s package extends xslt-default. That is the only change needed to port an older application, apart from the stylesheet, which is untouched.

The first thing to see is what the stylesheet receives. An identity transform shows the document built from the Bookshelf action: the root element is always result, every property the action exposes (including the inherited ones: actionErrors, actionMessages, fieldErrors, locale, texts) becomes an element, in alphabetical order, and a list becomes a sequence of item elements (not elements named after the class):

Source: Apache Struts — XSL Result, Description

With that document in mind a real stylesheet is short. The next one turns the shelf into a small XML catalogue; the first version of it that I wrote used books/book, which matched nothing and produced an empty element, because the elements are called item:

Source: Apache Struts — XSL Result, Examples

The parameters of the result were checked against the setXxx methods of XSLTResult in the 7.4.0 sources, and each one was tried. The table compares them with the official page, which has three differences:

Source: Apache Struts — XSL Result, Parameters

The page on results shows the xslt result in its overview of result types; its example with a matchingPattern parameter produces the same output with or without the parameter in 7.4.0 (see Where the Official Pages and the Older Books Are Outdated). Two more notes on the XSLT result. It uses the XSLT engine of the JDK (XSLTC), not Apache Xalan, so the long explanation on the official page of how Xalan walks the object graph and the loop eliminator is background; the plugin has no Xalan dependency. And the result exposes every public property of the action, so a stylesheet is a view of the action’s data, not of a DTO: a property you would not put in a page (a password, an internal id) is in the XML too. For an API that needs a stable document, expose a purpose-built object with exposedValue, or use the JSON or REST plugin.

JasperReports is an LGPL reporting library that turns a compiled report (.jasper) and a data source into PDF, HTML, CSV, XLSX and other formats. Struts has two plugins for it, and they are independent: struts2-jasperreports-plugin (package jasperreports-default, result type jasper, class JasperReportsResult) targets the JasperReports 6.x line and is built against 6.21.5, and struts2-jasperreports7-plugin (package jasperreports7-default, result type jasperReport7, class JasperReport7Result) was added for the 7.x line and first appears on Maven Central as 7.1.1. The official page says plainly that the two are not meant to be used together. Neither plugin ships the JasperReports library: it is LGPL licensed and cannot be distributed in an Apache release. The reporting itself (the page layout, the PDF engines, fonts, signatures and forms) is outside this documentation set’s Struts pages; the PDF Generation section of this site covers JasperReports and iText (see PDF Export Configuration for the exporter side), and this page only shows how the Struts side of an integration works.

The JFreeChart plugin returns a chart as an image. The package jfreechart-default registers the result type chart (org.apache.struts2.dispatcher.ChartResult) with default width 200 and height 150; the action only has to expose a JFreeChart. As with JasperReports, the charting library is LGPL and is not bundled: the application adds org.jfree:jfreechart itself (1.5.6 is the latest on Central, the version the example used). The Bookshelf action builds a bar chart of the publication years:

Source: Apache Struts — JFreeChart Plugin, Usage

Three details were checked in addition to the official example. A result with no parameters uses the defaults of the result type (<result type="chart"/> gave a PNG of 200 x 150). The result has more parameters than the page documents: type (png, the default, or jpeg/jpg, which gave Content-Type: image/jpg and a JPEG) and value, the name of the action property that holds the chart. The page’s "Future Work" section says the chart property is hard coded; with value set to yearChart the result read getYearChart(), so it is not. A chart is generated on every request, so for a page that is displayed often, render it once and cache it (the stream result of the results page serves a stored image). The chart is an image: for charts in a page, an img tag whose src is the chart action is the usual way to place it.

The async plugin promises asynchronous actions on top of the Servlet asynchronous processing: the action method returns a Callable<String> instead of a result code, Struts starts an asynchronous context, runs the callable on another thread and, when it completes, dispatches the request back to the container to execute the result. The plugin has existed since 6.0.0, its documentation is the page with three examples (a plain Callable, a callable with a timeout and a callable that returns another callable), and it is still in 7.4.0: AsyncAction (a Callable wrapper with constructors that take a timeout in milliseconds and an Executor), AsyncManager (the core interface) and DefaultAsyncManager, registered as a prototype bean in the plugin’s descriptor. The Bookshelf version of the example is a slow action:

Source: Apache Struts — Async Plugin, Simple usage

The Servlet side is mandatory: the filter or servlet that serves Struts must declare async-supported (as with any asynchronous servlet, see Asynchronous Processing in Brief), and the official page shows the StrutsServlet with the flag. The result was not what the page promises. I ran the same action in three configurations, with a counter in execute() and a log line per call; all three used Tomcat 11.0.26 and Struts 7.4.0:

Source: Apache Struts — Async Plugin, Simple usage

The cause is visible in the 7.4.0 sources. DefaultAsyncManager is a prototype bean, so every ActionInvocation gets its own instance, and the result of the callable is stored in that instance. After AsyncContext.dispatch() the container calls Struts again, the framework creates a new invocation with a new manager, hasAsyncActionResult() is false, the action method runs again and starts another asynchronous task, and so on until the application is stopped. I found nothing in the core that carries the first invocation over to the dispatched request, and I could not verify the plugin on any other configuration, so the honest summary is limited to this: on Struts 7.4.0 with Tomcat 11.0.26, the three configurations above did not complete a request, and the page’s own examples cannot be recommended. Do not use the async plugin in an application until this is fixed or documented. The alternatives that work today are the servlet’s own asynchronous API for one endpoint (the page on Servlet Fundamentals shows it), a normal executor with a polling page, and the execAndWait interceptor with its wait page, which is the Struts-native tool for long-running actions (see Execute and Wait).

The javatemplates plugin is a faster implementation of the tags of the simple theme: instead of rendering a FreeMarker template, a Java class writes the markup. It is switched on by two constants, which the plugin documentation lists, and the plugin’s descriptor registers a template engine called java and adds it to struts.templateEngines (ftl,jsp,vm,java):

Source: Apache Struts — Javatemplates Plugin, Installation

The same page rendered with the plugin and with the default templates (struts.ui.templateSuffix ftl), from the same JSP, shows that the markup is not identical byte for byte, although it is equivalent:

Source: Apache Struts — Javatemplates Plugin, Supported tags

The differences are attribute order, a value="" that the FreeMarker template writes and the Java version leaves out, and <input></input> instead of self-closing elements; the last one is valid in HTML but not in XML. The plugin is a drop-in replacement for the 19 tags it supports (a, actionerror, actionmessage, checkbox, datetextfield, div, fielderror, file, form, head, hidden, label, password, select, reset, submit, textfield, textarea and token), only in the simple theme; the performance benchmark section of its page still reads "TODO", so there is no official number, and the performance tuning page of the Core Developer Guide only suggests it. The constant struts.ui.templateSuffix is global, so every tag that is not in the list is rendered by its own FreeMarker template, as before. The page on themes and templates explains the template engines, and the page on UI and form tags notes that s:datetextfield needs this plugin and has a quirk with the simple theme.

Source: Apache Struts — Performance Tuning

Both testing plugins are test-scoped dependencies, and neither belongs in WEB-INF/lib. The JUnit plugin offers base classes that start a full Struts instance and simulate a request: StrutsTestCase (JUnit 3 style), StrutsJUnit4TestCase, StrutsRestTestCase, StrutsSpringTestCase, StrutsSpringJUnit4TestCase and XWorkJUnit4TestCase, all in org.apache.struts2.junit; the TestNG plugin has TestNGStrutsTestCase and TestNGXWorkTestCase in org.apache.struts2.testng. The JUnit plugin brings Spring’s mock servlet classes (spring-test, spring-web) and JUnit 4.13.2 as transitive test dependencies, which was verified in the dependency tree of the scratch project. A test of the Bookshelf shelf, run with Maven, passed:

Source: Apache Struts — JUnit Plugin, Struts actions (without Spring)

The test extends a JUnit 4 base class, so on a project that uses JUnit Jupiter it needs the JUnit Vintage engine to run (it was run that way here). executeAction("/books") runs the full request including the result, but the JSP result is not rendered by the mock environment (the response body was empty), so rendered-page tests belong in an integration test against a real container. The TestNG plugin is declared the same way (struts2-testng-plugin, test scope) and subclassing TestNGStrutsTestCase; it was not run on this page. The Testing page of this part builds on both plugins.

Source: Apache Struts — TestNG Plugin, Usage

The plugin index is a historical list. This table separates what disappeared, with the version of removal read from the Version Notes, the 6 to 7 migration guide and the Maven Central metadata (the last published version of the artifact is the evidence for a plugin whose removal is not documented). If an application of an older version uses one of them, the migration notes below are where the replacement is.

Source: Apache Struts — Plugins

Source: Struts Wiki — 6.x.x to 7.x.x migration, Removed plugins

Source: Struts Wiki — Version Notes 7.0.0

Source: Apache Struts Examples — sitemesh3

The migration guide’s wording for the plugins removed in 7.0.0 is: the Portlet plugins, the Pell Multipart plugin, DWR and SiteMesh; "there is no straight replacement" for them, and SiteMesh is replaced by direct integration with SiteMesh 3. The page of this part on Tiles and Page Layouts shows how Tiles, a tag-file layout and SiteMesh 3 compare.

Source: Struts Wiki — Version Notes 7.4.0

Source: Struts Wiki — Version Notes 6.2.0

The older books on Struts 2 (the 2.0 generation) describe a plugin world that has changed in four ways. First, the plugin list: Codebehind, SiteMesh, Tiles 2, JFreeChart and the JasperReports result were the common ones; SiteMesh and Codebehind are gone, JasperReports has a new plugin for version 7 with a different template syntax, and the XSLT result moved from the core into a plugin. Second, the framework classes: every com.opensymphony.xwork2.* name in a book (ObjectFactory, ActionProxyFactory, Container, @Inject, ActionContext) is org.apache.struts2.* in 7.4.0. Third, the namespace: javax.servlet code of the book is jakarta.servlet. Fourth, the Struts 1 book’s PlugIn interface, configured with <plug-in> in struts-config.xml, has no counterpart in Struts 2; the equivalent is a servlet context listener or a bean with a startup method. The Struts 1 migration is on the page on Struts 1 Classic and Migration in this part.

The official pages have their own inconsistencies, found while verifying the examples of this page: