ModelDriven, Preparable & CRUD

The WAR is the Struts Bookshelf of the Getting Started page of this section (the Struts BOM org.apache.struts:struts2-bom:7.4.0 imported in dependencyManagement, struts2-core, the Servlet and Pages APIs with scope provided, StrutsPrepareAndExecuteFilter mapped to /*, the constant struts.allowlist.packageNames set to org.example.bookshelf so that OGNL may read the example classes) with extra actions for the experiments. It is deployed under the context path /g9modeldriven, and every URL uses the default extension .action. Imports and package lines are left out of the listings; the package is org.example.bookshelf.

By default the parameters of a request are copied into the action, and the action is what the view reads. That mixes two roles in one class: a controller that decides what happens and a bean that holds the form data. ModelDriven separates them. An action that implements org.apache.struts2.ModelDriven<T> has one extra method, T getModel(), and the modelDriven interceptor, which belongs to defaultStack, calls it when the action is about to run. The Core Developer Guide describes the result in three sentences: Struts populates the fields of the returned object with the request parameters, the object is put on top of the value stack when the action executes, and validation is also performed on the model instead of the action.

Source: Core Developer Guide — Model Driven

Source: Struts Javadoc — ModelDriven

The interceptor is short. It is the 7.4.0 code, reduced to the lines that matter (threadAllowlist is the OGNL allowlist of the 7.x series, which the interceptor extends with the model’s class so that its properties can be evaluated):

Source: Struts 7.4.0 source — ModelDrivenInterceptor.intercept

Three facts follow from these lines, and each is demonstrated below. The model is pushed only when it is not null, so a null model is silently ignored. getModel() is called once by the interceptor, and the object it returned then stays on the stack for the rest of the request, whatever later calls return. The model is pushed above the action, so a property that exists on both is read, and written, on the model.

Since Struts 7.0.0 the params interceptor requires @StrutsParameter on a setter (or on a getter, with a depth, to reach into an object) before it copies a request parameter there; the constant struts.parameters.requireAnnotations defaults to true in 7.4.0. A ModelDriven action is the exception, and the exception is written into the interface’s contract: returning an object from getModel() designates that object as the request surface. The Core Developer Guide states the rule in detail:

The run above is the 7.4.0 behavior: note was not bound. The guide’s practical advice follows from the rule. Because the whole model is bindable, shape it as a request DTO that carries only the fields the action means to accept, never a domain or persistence entity; where member-level control is needed, use annotated action properties instead of ModelDriven.

Source: Core Developer Guide — Struts Parameter Annotation, The action’s own members are not exempt

Source: Struts Security Guide — Defining and annotating your action parameters

The interceptor calls getModel() and uses the return value for the rest of the request. Four behaviors of that call are worth knowing, and each has a Bookshelf action.

The rule is that getModel() must return the same instance every time it is called during a request, unless the action deliberately replaces it and refreshModelBeforeResult is on. The parameter is the only configuration of the interceptor: when it is true a PreResultListener runs after the action and before the result, calls getModel() again, and if the instance is not already on the stack removes the old model and pushes the new one. That is useful when the action loads the model from the data layer inside the action method. The Javadoc states the cost: getModel() is called at least twice.

Source: Core Developer Guide — Model Driven Interceptor, Parameters

The simplest way to avoid every problem in the table is to create the model once, in a field or lazily, and return it: the CRUD action below uses if (form == null) { form = new BookForm(); }.

The second half of the pair solves a different problem. Often a form shows data that comes from a lookup, such as the list of authors in a drop-down. The lookup is done by the action method that displays the form (input). When the user submits the form and the validation fails, the validation and workflow interceptors return input and the framework renders the input view, but the input method is not run again, so the lookup result is missing and the page is rendered without its drop-down. The Getting Started tutorial on the Preparable interface describes exactly this problem and its remedy: put the statements that must run whatever method is called, and also when validation fails, in a prepare() method.

Source: Core Developer Guide — Prepare Interceptor

Source: Getting Started — Preparable Interface

The interceptor, in the 7.4.0 source, decides the order in four lines of code, which is why the observed order below is not the order that people expect on first reading:

Source: Struts 7.4.0 source — PrepareInterceptor.doIntercept

(The 7.4.0 source wraps the prefixed call in a try block that unwraps InvocationTargetException, so an exception that a prepare method throws reaches the exception interceptor as itself; that part is left out.) PrefixMethodInvocationUtil looks up the method name from the action proxy (execute when none is configured), tries each prefix in order and invokes only the first method that exists.

The second use of Preparable in the Prepare Interceptor page is the one that gives the stack its name: load an object from the database so that request parameters can be set on the loaded object. The difficulty is the order. In defaultStack of 7.4.0 the prepare interceptor is at position 7 and params at position 17, so prepare() runs before any request parameter has been bound. A prepare() that wants the id of the book finds the field empty. The sample stack paramsPrepareParamsStack of struts-default.xml fixes this by running params twice: once before prepare and once after modelDriven.

The figure is the order of paramsPrepareParamsStack in the 7.4.0 jar, ignoring the first three entries (exception, alias, i18n) and checkbox, datetime and multiselect. Two details matter. The first params runs while the value stack holds only the action, so only parameters that name an action property are applied, and in 7.x only those with @StrutsParameter (the id below; the rule is the topic of Parameter Injection and @StrutsParameter); every other parameter, such as title, finds no property and is ignored on this pass. The second params runs when the model is on the stack, so the same request values now reach the model, which prepare may have replaced. The model interceptor comes after prepare in both stacks: that is what allows prepare to create or load the model and getModel() to return it afterwards.

The Bookshelf’s administration screen has five operations on the book resource: a list, a form for a new book, a form for an existing book, a save that creates or updates, and a delete. One action class serves them all, each operation being one method selected through the wildcard book-*. The model is the DTO BookForm; the entity Book never meets the request.

The pattern is post, redirect, get: after a successful save or delete the result is a redirectAction to the list, so a browser refresh of the list does not repeat the POST. A failed validation returns input and re-renders the form in the same request, with the field errors and the values the user typed.

Source: Core Developer Guide — Prepare Interceptor

The class has these parts, in the order in which a request reaches them. setId is annotated because the first params pass needs it. prepare() fills authors for every method, including after a failed validation, which is the whole point of the interface. prepareEdit() loads the stored book into a fresh BookForm. prepareSave() does the same, so that a failed validation redisplays the stored values for the fields that were not submitted, with the submitted values written over them by the second params. getModel() creates the form lazily so that the input page for a new book has an empty one. validateSave() is the per-method validation hook that ActionSupport offers (see the actions page): it runs before save() and not before the other methods. The action method save() copies the DTO into the entity field by field, which is the only place where the entity is written, and its list is explicit: a field added to the entity later is not bindable until someone adds it here. The notfound result code handles an unknown id with a 404.

A model that lives longer than a request is the Struts answer to the Struts 1 ActionForm with scope="session": a multi-page wizard, where each step fills part of the same object. The tool is ScopedModelDriven, an extension of ModelDriven that adds three methods, and the scopedModelDriven interceptor. The interceptor acts only on actions that implement the interface and only when their getModel() returns null; it then loads the model from the scope (building it with the object factory when the scope has none), hands it to the action with setModel, and tells the action the key it used with setScopeKey. The actual pushing on the stack is still done by modelDriven, which follows it in defaultStack.

Source: Core Developer Guide — Scoped Model Driven Interceptor, Parameters

Source: Struts Javadoc — ScopedModelDriven

getModel() returns the field, null at first, which is what makes the interceptor act; the three step methods do nothing because the framework does the work. Two mappings point to the class, one with the interceptor parameters of the session scope and one with the defaults:

Source: Core Developer Guide — Scoped Model Driven Interceptor, Examples

Three requests of one browser session (cookie kept) to the session mapping, and two separate requests to the default one:

In the session scope the second step still sees the title from the first and the third step sees both, because the same BookForm instance is stored in the HttpSession under bookWizard; in the request scope each request gets a new model, and the key defaults to the class name. The 7.4.0 source of resolveModel shows where the models live: the session scope is the HttpSession map of the ActionContext, and the request scope is the ActionContext context map, that is, a map that lives for the request and is not the servlet request’s attributes.

Source: Struts 7.4.0 source — ScopedModelDrivenInterceptor.resolveModel

Remember that a session scoped model is shared by every browser tab of the session: two tabs that run the wizard overwrite each other’s fields, and nothing removes the model when the wizard is finished. A real wizard ends with a save method that removes the key from the session map (for instance through SessionAware or ActionContext.getSession()). The session and scope interceptors, and the chain result, are on the Action Chaining, Sessions and Scopes page of this section.

Source: Core Developer Guide — Prepare Interceptor, the 7.2.0 note

Source: Core Developer Guide — Struts Parameter Annotation, ModelDriven actions

The books of the section explain the idea correctly: a model object separate from the action, a prepare step before the parameters, and a stack that loads parameters twice. The details changed.

The Struts 1 ActionForm concepts map as follows: the form bean is the model (or the action’s own properties), reset() is the constructor of a fresh model, validate() is validate() or XML validation on the model, the scope attribute of the mapping is scopedModelDriven.scope, and the form acting as a "firewall" between the request and the business objects is the DTO.

Source: Core Developer Guide — Scoped Model Driven Interceptor

Collected while verifying this page against the 7.4.0 jar: