Struts Architecture

1. Overview

 

In the diagram, an initial request goes to the Servlet container (such as Jetty or Resin) which is passed through a standard filter chain. The chain includes the (optional) ActionContextCleanUp filter, which is useful when integrating technologies such as SiteMesh Plugin. Next, the required FilterDispatcher is called, which in turn consults the ActionMapper to determine if the request should invoke an action.

 

If the ActionMapper determines that an Action should be invoked, the FilterDispatcher delegates control to the ActionProxy. The ActionProxy consults the framework Configuration Files manager (initialized from the struts.xml file). Next, the ActionProxy creates an ActionInvocation, which is responsible for the command pattern implementation. This includes invoking any Interceptors (the before clause) in advance of invoking the Action itself.

Once the Action returns, the ActionInvocation is responsible for looking up the proper result associated with the Action result code mapped in struts.xml. The result is then executed, which often (but not always, as is the case for Action Chaining) involves a template written in JSP or FreeMarker to be rendered. While rendering, the templates can use the Struts Tags provided by the framework. Some of those components will work with the ActionMapper to render proper URLs for additional requests.

 

All objects in this architecture (Actions, Results, Interceptors, and so forth) are created by an ObjectFactory. This ObjectFactory is pluggable. We can provide our own ObjectFactory for any reason that requires knowing when objects in the framework are created. A popular ObjectFactory implementation uses Spring as provided by the Spring Plugin.

Interceptors are executed again (in reverse order, calling the after clause). Finally, the response returns through the filters configured in the web.xml. If the ActionContextCleanUp filter is present, the FilterDispatcher will not clean up the ThreadLocal ActionContext. If the ActionContextCleanUp filter is not present, the FilterDispatcher will cleanup all ThreadLocals.

 

 

All objects created by the framework are instantiated by the ObjectFactory. The ObjectFactory provides the means of integrating the framework with IoC containers like Spring, Pico, Plexus, and so forth.

 

2. ObjectFactory

Customized ObjectFactory must extend ObjectFactory or any of its descendants and have a default, no-argument constructor.

To register a customized ObjectFactory, add or edit an entry in struts.properties

 struts.objectFactory=foo.bar.MyCustomObjectFactory

where foo.bar.MyCustomObjectFactory is the custom object factory.

public class MyObjectFactory extends ObjectFactory {    .....}

3. ActionMapper

The ActionMapper interface provides a mapping between HTTP requests and action invocation requests and vice-versa.

When given an HttpServletRequest, the ActionMapper may return null if no action invocation request matches, or it may return an ActionMapping that describes an action invocation for the framework to try.

The ActionMapper is not required to guarantee that the ActionMapping returned be a real action or otherwise ensure a valid request. Accordingly, most ActionMappers do not need to consult the Struts configuration just to determine if a request should be mapped.

Just as requests can be mapped from HTTP to an action invocation, the opposite is true as well. However, because HTTP requests (when shown in HTTP responses) must be in String form, a String is returned rather than an actual request object.

DefaultActionMapper

By default, the DefaultActionMapper is used:

Default action mapper implementation, using the standard *.[ext] (where ext usually "action") pattern. The extension is looked up from the Struts configuration key struts.action.extension.

 

To help with dealing with buttons and other related requirements, this mapper (and other ActionMappers, we hope) has the ability to name a button with some predefined prefix and have that button name alter the execution behaviour. The four prefixes are:

 

•  

   

• Method prefix - method:default

   

   

• Action prefix - action:dashboard

   

   

• Redirect prefix - redirect:cancel.jsp

   

   

• Redirect-action prefix - redirectAction:cancel

   

   

 

 

In addition to these four prefixes, this mapper also understands the action naming pattern of foo!bar in either the extension form (eg: foo!bar.action) or in the prefix form (eg: action:foo!bar). This syntax tells this mapper to map to the action named foo and the method bar.

In Struts 2.1.6 and earlier the Redirect Action prefix is "redirect-action", it was changed to "redirectAction" after the release of Struts 2.1.6

Method prefix

With method-prefix, instead of calling baz action's execute() method (by default if it isn't overriden in struts.xml to be something else), the baz action's anotherMethod() will be called. A very elegant way determine which button is clicked. Alternatively, one would have submit button set a particular value on the action when clicked, and the execute() method decides on what to do with the setted value depending on which button is clicked.

<s:form action="baz">    <s:textfield label="Enter your name" name="person.name"/>    <s:submit value="Create person"/>    <s:submit name="method:anotherMethod" value="Cancel"/></s:form>

Action prefix

With action-prefix, instead of executing baz action's execute() method (by default if it isn't overriden in struts.xml to be something else), the anotherAction action's execute() method (assuming again if it isn't overriden with something else in struts.xml) will be executed.

<s:form action="baz">    <s:textfield label="Enter your name" name="person.name"/>    <s:submit value="Create person"/>    <s:submit name="action:anotherAction" value="Cancel"/></s:form>

Redirect prefix

With redirect-prefix, instead of executing baz action's execute() method (by default it isn't overriden in struts.xml to be something else), it will get redirected to, in this case to www.google.com. Internally it uses ServletRedirectResult to do the task.

<s:form action="baz">    <s:textfield label="Enter your name" name="person.name"/>    <s:submit value="Create person"/>    <s:submit name="redirect:www.google.com" value="Cancel"/></s:form>

Redirect-action prefix

With redirect-action-prefix, instead of executing baz action's execute() method (by default it isn't overriden in struts.xml to be something else), it will get redirected to, in this case 'dashboard.action'. Internally it uses ServletRedirectResult to do the task and read off the extension from the struts.properties.

<s:form action="baz">    <s:textfield label="Enter your name" name="person.name"/>    <s:submit value="Create person"/>    <s:submit name="redirectAction:dashboard" value="Cancel"/></s:form>

In Struts 2.1.6 and earlier the Redirect Action prefix is "redirect-action", it was changed to "redirectAction" after the release of Struts 2.1.6

Custom ActionMapper

You can define your own ActionMapper by implementing org.apache.struts2.dispatcher.mapper.ActionMapper then configuring Struts 2 to use the new class in struts.xml

<bean type="org.apache.struts2.dispatcher.mapper.ActionMapper" name="mymapper" class="com.mycompany.myapp.MyActionMapper" /><constant name="struts.mapper.class" value="mymapper" />

Possible uses of the ActionMapper include defining your own, cleaner namespaces, such as URLs like /person/1, which would be similar to a request to /getPerson.action?personID=1 using the DefaultActionMapper.

CompositeActionMapper

A composite action mapper that is capable of delegating to a series of ActionMapper if the former failed to obtained a valid ActionMapping or uri.

It is configured through struts.properties.

For example, with the following entries in struts.properties

 

<bean type="org.apache.struts2.dispatcher.mapper.ActionMapper" name="struts"       class="org.apache.struts2.dispatcher.mapper.CompositeActionMapper" /><constant name="struts.mapper.composite"       value="org.apache.struts2.dispatcher.mapper.DefaultActionMapper,org.apache.struts2.dispatcher.mapper.RestfulActionMapper,org.apache.struts2.dispatcher.mapper.Restful2ActionMapper" />

When {@link CompositeActionMapper#getMapping(HttpServletRequest, ConfigurationManager)} or CompositeActionMapper#getUriFromActionMapping(ActionMapping) is invoked, CompositeActionMapper would go through these ActionMappers in sequence starting from ActionMapper identified by 'struts.mapper.composite.1', followed by 'struts.mapper.composite.2' and finally 'struts.mapper.composite.3' (in this case) until either one of the ActionMapper return a valid result (not null) or it runs out of ActionMapper in which case it will just return null for both {@link CompositeActionMapper#getMapping(HttpServletRequest, ConfigurationManager)} and CompositeActionMapper#getUriFromActionMapping(ActionMapping) methods.

 

For example with the following in struts-*.xml :-

   <bean type="org.apache.struts2.dispatcher.mapper.ActionMapper" name="struts"

       class="org.apache.struts2.dispatcher.mapper.CompositeActionMapper" />   

<constant name="struts.mapper.composite"

       value="org.apache.struts2.dispatcher.mapper.DefaultActionMapper,

foo.bar.MyActionMapper,foo.bar.MyAnotherActionMapper" />

CompositeActionMapper will be configured with 3 ActionMapper, namely "DefaultActionMapper", "MyActionMapper" and "MyAnotherActionMapper". CompositeActionMapper would consult each of them in order described above.

ActionMapper and ActionMapping objets

The ActionMapper fetches the ActionMapping object corresponding to a given request. Essentially, the ActionMapping is a data transfer object that collects together details such as the Action class and method to execute. The mapping is utilized by the Dispatcher and various user interface components. It is customizable through struts.mapper.class entry in struts.properties or struts.xml. Note that the value of this constant is the name of the bean of the new mapper.

Customize

Custom ActionMapper must implement ActionMapper interface and have a default constructor.

<bean type="org.apache.struts2.dispatcher.mapper.ActionMapper" name="mymapper" class="com.mycompany.myapp.MyActionMapper" />

<constant name="struts.mapper.class" value="mymapper" />

public class MyCustomActionMapper implements ActionMapper {  

public ActionMapping getMapping(HttpServletRequest request, 

                                  ConfigurationManager configManager) {    ....  }

   public String getUriFromActionMapping(ActionMapping mapping) {     ....  }}

See also: RestfulActionMapper

 

 

4. Action Proxy & ActionProxy Factory

 

The ActionProxy obtains the Action class and calls the appropriate method. By default, Actions are obtained through local instantiation, but an Action could also be obtained remotely if an alternative ActionProxy were provided.

An alternative ActionProxy can be configured through ActionProxyFactory. Typically, an ActionProxy will utilize the ActionInvocation to encapsulate the execution of a particular request.

The ActionInvocation determines how an Action is handled: Is it being intercepted, is there a PreResultListener acting on it.

Essentially, ActionProxy encapsulates how an Action can be obtained. ActionInvocation encapsulates how the Action is executed when a request is invoked.

Customization

ActionProxyFactory

 ActionProxyFactory.setFactory(new MyActionProxyFactory() {    ..... });

ActionProxy

 ActionProxyFactory.getFactory(new MyActionProxyFactory() {    

....  public ActionProxy createActionProxy(Configuration config,        

String namespace, String actionName, Map extraContext)            

throws Exception { 

       createActionProxy(config, namespace, actionName, extraContext, true);    }    

public ActionProxy createActionProxy(Configuration config,           

 String namespace, String actionName, Map extraContext,            

boolean executeResult, boolean cleanupContext)            

throws Exception {        ....   }   .... });

ActionInvocation

 ActionProxyFactory.getFactory(new MyActionProxyFactory() {    

...    

    public ActionInvocation createActionInvocation(ActionProxy actionProxy)                             

throws Exception {

          createActionInvocation(actionProxy, new LinkedHashMap());    }    

public ActionInvocation createActionInvocation(ActionProxy actionProxy, 

                            Map extraContext) throws Exception {

          createActionInvocation(actionProxy, extraContext, true);    

}    

public ActionInvocation createActionInvocation(ActionProxy actionProxy,

                             Map extraContext, boolean pushAction)

                             throws Exception {

          // do implementation of ActionInvocation herer

          .....    }

    ... });

5. Configuration Provider & Configuration

 

 

The ConfigurationProvider interface describes the framework's configuration. By default, the framework loads its configurations via an xml document by using the StrutsXmlConfigurationProvider. The provider can be configured through a Dispatcher's DispatcherListener.

Example

 static {   Dispatcher.addDispatcherListener(new DispatcherListener() {

     ....

     public void dispatcherInitialized(Dispatcher du) {

         ConfigurationManager confManager = du.getConfigurationManager();

         confManager.addConfigurationProvider( ... );     }     ....   }); 

}