Type Conversion

Boolean conversion is Boolean.valueOf of the string: only the text true, in any letter case, is true (observed with Struts 7.4.0, where the converter’s doConvertToBoolean does exactly that). Everything else, including the on that browsers send for a checkbox without a value attribute, is false and is not an error:

Source: Core Developer Guide — Type Conversion, Built in Type Conversion Support

The consequence for forms is the classic checkbox problem: an unchecked checkbox sends nothing, so the property is never touched and keeps its previous (possibly true) value. The checkbox interceptor of defaultStack handles it: a hidden companion field named __checkbox_featured sets the property to false when the checkbox itself is absent. With the companion field present and the checkbox absent, the observed result is featured = false; with both present and set to true, featured = true. The <s:checkbox> tag renders the companion field for you; the tags page of this section covers it.

Blank values need a separate rule, because a browser submits an empty text field as name=:

Source: Core Developer Guide — Type Conversion, Null and Blank Values

The guide’s "Null and Blank Values" section says that "a blank string also cannot be set on a BigDecimal or BigInteger". That is not the behaviour of 7.4.0 (see Inconsistencies in the Official Documentation). The other half of the advice stands: a primitive cannot be null, so an action that must tell "not entered" from "zero" declares the wrapper type and uses validation to demand a value.

NumberConverter converts with java.text.NumberFormat for the locale of the request: the locale chosen by the i18n interceptor (from request_locale, the session or the browser’s Accept-Language). That makes the decimal and grouping separators locale dependent, in two different ways for two kinds of target:

Source: Struts Javadoc — NumberConverter

Source: Struts 7.4.0 source — NumberConverter

Three things to remember. A decimal comma typed by a visitor whose locale is en-US is not an error: it is dropped as a grouping separator and 1,5 becomes fifteen. The primitive int and long go through the plain DefaultTypeConverter (no grouping), whereas the wrapper types and BigDecimal use NumberFormat. And the locale is the one the framework resolved, which is why a form and its action must agree on how the locale is chosen (the page Localization and i18n covers the i18n interceptor). For prices the safest design is a BigDecimal property, an explicit NumberFormat-aware validation rule, and the same locale for rendering and parsing.

The Core Developer Guide says dates use "the SHORT format for the Locale associated with the current request". In 7.4.0 DateConverter is more generous: for a java.util.Date property it tries a list of DateFormat instances in order and uses the first that parses. If a global format is defined through the struts.date.format text key it goes first; then the formats are:

Source: Struts 7.4.0 source — DateConverter

Source: Struts Javadoc — DateConverter

The results on published (a java.util.Date, JVM locale en-US, time zone Central Europe):

Source: Struts 7.4.0 source — DateConverter

Two behaviours deserve a warning. The year-first yyyy-MM-dd format reads only the leading part of the text, so 2026-10-02 10:15:30 (with a space) silently becomes midnight, while the T form keeps its time. And the result of a numeric short date depends on the locale of the request, as the same value 02/10/2026 is 2 October for a visitor on en-GB and 10 February for en-US (the SHORT pattern decides which field is the month). For forms that matter, define one format and use it for input and output: a text key struts.date.format in the global resource bundle puts that format first, or a custom converter (see below) owns the format completely.

The java.time types are handled separately: LocalDateTime, LocalDate and LocalTime are parsed with ISO_LOCAL_DATE_TIME, ISO_LOCAL_DATE and ISO_LOCAL_TIME (preceded by the global format when one is defined), and OffsetDateTime with ISO_OFFSET_DATE_TIME. That is why added=2026-10-02 works and added=02/10/2026 fails with a conversion error (observed). The guide does not mention java.time at all.

For an array or a collection property the converter converts each submitted value to the element type and builds the container: an array of the property’s type, a HashSet for Set, a TreeSet for SortedSet and an XWorkList (a framework ArrayList subclass) for List and Collection (read from CollectionConverter in the 7.4.0 source). When the element type cannot be determined the guide says elements are treated as String. The Set<String> genres of CollectionAction collapses duplicates:

Source: Core Developer Guide — Type Conversion, Built in Type Conversion Support

A property of type String receives the raw parameter; an Object or Number property that already holds a compatible value is left alone. The framework also converts to Class (by Class.forName) and to Calendar; both are rarely useful for request input and Class conversion from request text is a reason to keep the allowlist of the OGNL layer switched on (the page Security Hardening covers it).

A file named ActionClassName-conversion.properties in the same classpath directory as the action class maps a property name to a converter class. The Bookshelf’s CustomAction has a range property:

Source: Core Developer Guide — Type Conversion, Applying a Type Converter to an Action

The file is found by the class name of the action, so it belongs in the resources directory of the same package as the class (org/example/bookshelf/ here). The key can be a nested property, person.phoneNumber=com.acme.PhoneNumberConverter.

When the property belongs to a bean (a model object, a class in a dependency that cannot be modified), the rule file is named after the bean class and sits next to it on the classpath: ClassName-conversion.properties. The guide’s example is a Measurement class from a dependency, used through ModelDriven<Measurement>, so that the action cannot hold the rule: create the same package directory in your own resources and put the file there. In the Bookshelf the Book has a shelf property of type ShelfCode:

Source: Core Developer Guide — Type Conversion, Applying a Type Converter to a bean or model

The key of an application-wide rule is a type, not a property: the rule applies to every property of that type in every action and bean. The file is struts-conversion.properties in the root of the classpath (WEB-INF/classes); the old name xwork-conversion.properties is still read but is marked deprecated in the guide.

Source: Core Developer Guide — Type Conversion, Applying a Type Converter for an application

The guide adds that since Struts 7.2.0, when the Spring plugin is active, the converter value can be the name of a Spring bean (java.math.BigDecimal = myBigDecimalConverter) instead of a class name, so a converter can use injected services. That sentence is taken from the guide and was not run on the scratch WAR, which has no Spring plugin. The core jar itself ships one application-wide rule in struts-default-conversion.properties: java.io.File is converted by org.apache.struts2.conversion.UploadedFileConverter, which is how uploaded files reach File properties (the file upload page of this section covers it).

The three scopes together, with every converter used and one request:

Source: Core Developer Guide — Type Conversion, A Simple Example

Source: Core Developer Guide — Type Conversion, A Simple Example

Note the three details in the second response: all three conversions failed, so all three properties stayed null; the nested failure is named book.shelf; and the Book object was created (it is printed with its fields null), because creating the target is separate from converting its values. The message Bookshelf: invalid value for isbn is the xwork.default.invalid.fieldvalue key overridden in the application’s bundle (see below).

The guide says a converter throws TypeConversionException (or XWorkException) "to allow Struts to recognize that a conversion error has occurred". The scratch app also has a converter that throws a plain IllegalStateException, wired to a boom property through CustomAction-conversion.properties; the request is answered like any other conversion error and nothing leaks to the container:

Source: Struts Javadoc — TypeConversionException

So the safe reading of the contract is that a converter signals a bad value by throwing, and that the framework treats any RuntimeException the same way, but a converter that wants a clean log and a precise exception type should throw TypeConversionException (or its subclasses) itself.

With generics the rule files are not needed at all, because the type arguments say what to build. CollectionAction is the test bed:

Source: Core Developer Guide — Type Conversion, Collection and Map Support

Source: Core Developer Guide — Type Conversion, Relationship to Parameter Names

What the output shows. A List<Book> is addressed with books[0], books[1], and the missing elements are created and converted from the generic argument. A Map<String,Book> accepts both shelves['top'] and the shorter shelves.low; the key 7 of Map<Long,String> was converted to a Long by the same mechanism. A Set has no index; repeated values are collapsed. If a list index skips ahead the gaps are filled with null: submitting only books[255].title=ok yields a list of 256 elements of which the first 255 are null (observed, see the growth limit below), so templates must tolerate null elements. Elements that failed to convert are reported by their full name: books[0].pages=zz gives the field error books[0].pages.

Where generics are not available, or where the collection is addressed by something other than its position, the rules go into ActionClassName-conversion.properties (or the conversion file of whatever bean holds the property):

Source: Core Developer Guide — Type Conversion, Collection and Map Support

The Bookshelf uses catalogue, a Collection<Book> that is edited by book id:

Source: Core Developer Guide — Type Conversion, An advanced example for indexed Lists and Maps

Source: Core Developer Guide — Type Conversion, Indexing a collection by a property of that collection

The () notation (parentheses, not brackets: "Notice the () notation! Do not use [] notation, which is for Maps only", in the words of the guide’s example) says "the element whose id is 5". The value in the parentheses is converted to the type of the key property (Long here), and the element is looked up, or created when CreateIfNull is on, with the key property set to it. The book with id=6 came into existence although only its title was submitted, because the key in the name set its id. The guide stresses the practical gain: a row of a table stays tied to its identifier, so a form can edit items in any order, or after another user deleted one, without the index shift that books[2] suffers. The page of the guide uses an iterator:

Source: Core Developer Guide — Type Conversion, An advanced example for indexed Lists and Maps

Rendered by the scratch app for the request that set books 5 and 6, the page contains one input per element, named by id:

The guide’s version of that listing writes id="bean", <stextfield and the name beanList(%{bean.id}).name; the typo and the retired id attribute (replaced by var since 2.1.x) are listed under the inconsistencies.

Source: Tag Developers Guide — iterator Tag

An element addressed by key is not created when it does not exist, unless CreateIfNull is on: fooCollection(22) that is missing is simply absent, "to avoid OutOfMemoryErrors". For adding new elements the guide offers the notation fooCollection.makeNew[0], fooCollection.makeNew[1]. On the Bookshelf:

Source: Core Developer Guide — Type Conversion, Indexing a collection by a property of that collection

The guide’s caveat applies to a Set: equals and hashCode of the element must not rest only on the id, or two new elements, both with a null id, collapse into one.

An index is an invitation to allocate memory, so the growth is limited. The constant struts.ognl.autoGrowthCollectionLimit (it replaced the deprecated xwork.autoGrowCollectionLimit) caps the highest index an indexed name can create. It is not set in the default properties file in 7.4.0; the documented default is 255, which means that 256 elements are allowed. The behaviour on the Bookshelf agrees with that:

Source: Core Developer Guide — Type Conversion, Auto growth collection limit

The limit exists to prevent a denial of service by a parameter named books[2000000000].title. A form that really needs more rows raises it in struts.xml: <constant name="struts.ognl.autoGrowthCollectionLimit" value="1024"/>. Note that going over the limit is silent: the data is lost without a conversion error or a log line at the default level, so an unexpectedly empty list is worth checking against this limit.

Source: Core Developer Guide — Type Conversion, Generics and Erasure

Source: Core Developer Guide — Type Conversion, Interfaces

Each failed conversion is stored in the map conversionErrors of the ActionContext, keyed by the property name, with the rejected value and the target class. Nothing is reported yet. The interceptor conversionError (class StrutsConversionErrorInterceptor in struts-default.xml, a subclass of ConversionErrorInterceptor) reads the map after params has run and, for each entry, if the action is ValidationAware:

The interceptor has no parameters of its own, extends MethodFilterInterceptor (so includeMethods and excludeMethods work) and is part of basicStack, defaultStack and paramsPrepareParamsStack. After it, validation can add more errors, and workflow returns input if there are any.

Source: Core Developer Guide — Conversion Error Interceptor

Source: Struts Javadoc — StrutsConversionErrorInterceptor

The edit mapping returns input to edit.jsp when conversion fails. The action has four properties with conversion rules (a primitive int, a Date, a BigDecimal and the Isbn of the application-wide converter), and two message keys: the global bundle global.properties, registered with the constant struts.custom.i18n.resources, overrides the generic message, and EditAction.properties overrides one field:

Source: Core Developer Guide — Type Conversion, Type Conversion Error Handling

Source: Core Developer Guide — Type Conversion, Type Conversion Error Handling

Source: Tag Developers Guide — fielderror Tag

Submitting four invalid values returns the form again, with the errors and with the invalid text in the inputs (the output of curl for pages=abc published=notadate listPrice=1.5x isbn=bad, whitespace shortened):

Source: Core Developer Guide — Conversion Error Interceptor

Four things to read from it. The override invalid.fieldvalue.pages won over the global message for that one field. The original texts abc, notadate and 1.5x are back in the inputs, although the properties themselves are 0 and null. The order of the messages is not the order of the fields (the errors come from a map), so a page must not depend on it. And the escaping is the standard one of the tags: the interceptor escapes the original value for OGNL (escapeJava), and the s:textfield tag escapes it for HTML.

The per-field message may use the message formatting of the localization system, with the field label as {0}. Both the generic key and the per-field key go in the usual resource bundles of the action (the page Localization and i18n covers the search order), so a different language is a matter of adding global_es.properties with the same keys.

Source: Core Developer Guide — Localization

The guide: "To keep conversion errors from reporting globally, change the interceptor stack, and add additional validation rules." The two routes are checked on StrictAction, which has an Integer pages and an int copies, mapped twice.

The first mapping, strict, uses the default stack but excludes execute from conversionError:

Source: Core Developer Guide — Interceptors, Interceptor Parameter Overriding

Source: Core Developer Guide — Conversion Error Interceptor

No error is raised, the invalid input is silently replaced by the default, and the action method runs with null and 0. That is the choice that "conversion errors are not an error" implies, and it is almost never what a form wants; the case for it is an action that does its own checking. The second mapping, lenient, keeps the default stack and adds a rule file with a conversion validator for one field:

Source: Core Developer Guide — conversion validator, Examples

Source: Core Developer Guide — conversion validator

With both the interceptor and the validator the field gets two messages: the generic one from conversionError and the validator’s own. The Struts constant struts.validators.skipValidatorsOnConversionError (default false in 7.4.0; the Version Notes of 7.3.0 list the ticket WW-2934, "conversion error should short-circuit all validators") skips the other validators of a field that failed to convert, to avoid a second message of a "required" or "range" rule for a value that never became a number; as the comment of default.properties says, the field’s own conversion validator still runs. The validator also takes the parameter repopulateField: set to true, it re-fills the stack with the original value for a form that does not use the conversionError interceptor. The validation page of this section describes the validator framework itself.

Source: Core Developer Guide — conversion validator, Repopulating Field upon conversion Error

Source: Core Developer Guide — default.properties

Because workflow returns input when there are field errors, a mapping without an input result (or with the action’s execution still reachable) fails in the way the page Exception Handling and Global Results shows: with a global java.lang.Exception mapping the failure to find the input result is swallowed into the polite error page with HTTP 200, which is a confusing way to learn that an id=abc was typed. Map input for every action that receives request parameters (see Exception Handling and Global Results).

Source: Core Developer Guide — Default Workflow Interceptor