提供HTTP请求和Action调用映射

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.

当有一个HttpServletRequest的化，有配置的action，就返回一个ActionMapping，否则就返回null。

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.exection.

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 - redirect-action: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.

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.

<a:form action="baz">
    <a:textfield label="Enter your name" name="person.name"/>
    <a:submit value="Create person"/>
    <a:submit name="method:anotherMethod" value="Cancel"/>
</a: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.

<a:form action="baz">
    <a:textfield label="Enter your name" name="person.name"/>
    <a:submit value="Create person"/>
    <a:submit name="action:anotherAction" value="Cancel"/>
</a: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.

<a:form action="baz">
    <a:textfield label="Enter your name" name="person.name"/>
    <a:submit value="Create person"/>
    <a:submit name="redirect:www.google.com" value="Cancel"/>
</a: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.

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

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="struts" class="com.mycompany.myapp.MyActionMapper" />

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.

如果前面的在获得一个有效的ActionMapper或Uri失败，一个复合的映射器能委托一系列的ActionMapper。

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.RestfulActionMapperorg.apache.struts2.dispatcher.mapper.Restful2ActionMapper" />

When 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  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.

Customize

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

struts.mapper.class=foo.bar.MyCustomActionMapper

public class MyCustomActionMapper implements ActionMapper {
  public ActionMapping getMapping(HttpServletRequest request, 
                                  ConfigurationManager configManager) {
    ....
  }

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

See also: RestfulActionMapper

框架创建的所有对象都是有ObjectFactory实例化的。ObjectFactory提供了和其他IoC框架整合的方法。

Customize

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

Samuel说：在struts.xml中可以指定objectfactory="spring"

struts.objectFactory=foo.bar.MyCustomObjectFactory

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

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

In the diagram, an initial request goes to the Servlet container (such as Jetty or Resin) which is passed through a standard filter chain.

这个图中，初始需求到了Servlet容器，通过了标准的filter链。

The chain includes the (optional) ActionContextCleanUp filter, which is useful when integrating technologies such as SiteMesh Plugin.

这个链包括ActionContextClean的filter，它在整合技术方面例如：SiteMesh插件非常有用。

Next, the required FilterDispatcher is called, which in turn consults the ActionMapper to determine if the request should invoke an action.

接着，FilterDispatcher被调用，它查询ActionMapper决定请求应该调用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.

如果ActionMapper决定Action应该被调用，FilterDispatcher把控制委托给ActionProxy。ActionProxy咨询配置文件管理器（从struts.xml文件初始化）。接着，ActionProxy创建一个ActionInvocation，它负责命令格式实现，包括在调用Action自己前面调用任何Interceptors。

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.

一旦Action返回，ActionInvocation负责查询在struts.xml中映射的关于Action Result code相关的合适的result，它一般调用JSP或FreeMarker模板做渲染。在渲染的时候，模板可以用Struts标签。部分组建将和ActionMapper工作来渲染合适的URL给请求。

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).

Interceptor以相反的顺序在执行一遍。

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.

最后通过在Web.xml中配置的filter返回响应。如果ActionContextCleanUp过滤器也用了，那么FilterDispatcher不清理ActionContext本地线程。否则FilterDispatcher清理所有的本地线程。

http://www.ognl.org/

OGNL是对象图形定位语言.这里将设计一个OGNL和框架并存的例子。

The framework uses a standard naming context to evaluate OGNL expressions. The top level object dealing with OGNL is a Map (usually referred as a context map or context). OGNL has a notion of there being a root (or default) object within the context. In expression, the properties of the root object can be referenced without any special "marker" notion. References to other objects are marked with a pound sign (#).

框架用一个标准命名上下文来计算OGNL表达式。处理OGNL的高层对象是Map。OGNL在上下文内有个根的概念。在表达式里，不需要任何“标志”关联到根对象的属性。关联到其他对象得用#标识。

The framework sets the OGNL context to be our ActionContext, and the value stack to be the OGNL root object. (The value stack is a set of several objects, but to OGNL it appears to be a single object.) Along with the value stack, the framework places other objects in the ActionContext, including Maps representing the application, session, and request contexts. These objects coexist in the ActionContext, alongside the value stack (our OGNL root).

框架设置OGNLcontext为我们的 ActionContext, value stack 是OGNL根对象。（value stack是一系列的值，但对OGNL，它表现为一个对象）连同value stack，框架放置其他对象到ActionContext,包括展示application,session和request上下文。这些对象与value stack一起共存在ActionContext。

                     |
                     |--application
                     |
                     |--session
       context map---|
                     |--value stack(root)
                     |
                     |--request
                     |
                     |--parameters
                     |

There are other objects in the context map. The diagram is for example only.

The Action instance is always pushed onto the value stack. Because the Action is on the stack, and the stack is the OGNL root, references to Action properties can omit the # marker. But, to access other objects in the ActionContext, we must use the # notation so OGNL knows not to look in the root object, but for some other object in the ActionContext.

Action 实例被推入value stack。因为Action在stack里，并且statck是OGNL的根，和Action关联的属性忽略#标记。但访问ActionContext的其他对象，我们必须用#标识，OGNL知道不应该区根对象查找，而是到ActionCopntext的其他对象里查找。

<s:property value="postalCode"/>

Other (non-root) objects in the ActionContext can be rendered use the # notation.

<s:property value="#session.mySessionPropKey"/> or
<s:property value="#session["mySessionPropKey"]"/> or
<s:property value="#request["mySessionPropKey"]/>

The ActionContext is also exposed to Action classes via a static method.

ActionContext也通过静态方法被暴露给Action类

ActionContext.getContext().getSession().put("mySessionPropKey", mySessionObject);

Collections (Maps, Lists, Sets)

Dealing with Collections (Maps, Lists, and Sets) in the framework comes often, so here are a few examples using the select tag.

声明集合在框架中经常用到，所以这里是用select标签的例子。

Syntax for list: {e1,e2,e3}. This idiom creates a List containing the String "name1", "name2" and "name3". It also selects "name2" as the default value.

list语法:{e1,e2,e3}.这个习惯创建一个包括“name1”，“name2”和“name3”。它也选择“name2”作为默认值。

<s:select label="label" name="name" list="{'name1','name2','name3'}" value="%{'name2'}" />

Syntax for map: #{key1:value1,key2:value2}. This idiom creates a map that maps the string "foo" to the string "foovalue" and "bar" to the string "barvalue":

map语法：#{key1:value1,key2:value2}.这个创建map，把字符传“foo”到字符串"foovalue",“bar”到字符串"barvalue".

<s:select label="label" name="name" list="#{'foo':'foovalue', 'bar':'barvalue'}" />

To determine if an element exists in a Collection, use the operations in and not in.

用in 和 not in 检验元素是否在一个集合里面

<s:if test="'foo' in {'foo','bar'}">
   muhahaha
</s:if>
<s:else>
   boo
</s:else>

<s:if test="'foo' not in {'foo','bar'}">
   muhahaha
</s:if>
<s:else>
   boo
</s:else>

To select a subset of a collection (called projection), use a wildcard within the collection.

• ? - All elements matching the selection logic
• ^ - Only the first element matching the selection logic
• $ - Only the last element matching the selection logic

To obtain a subset of just male relatives from the object person:

person.relatives.{? #this.gender == 'male'}

OGNL supports basic lamba expression syntax enabling you to write simple functions.

(Dedicated to all you math majors who didn't think you would ever see this one again.)

Fibonacci: if n==0 return 0; elseif n==1 return 1; else return fib(n-2)+fib(n-1);
fib(0) = 0
fib(1) = 1
fib(11) = 89

How the expression works The lambda expression is everything inside the brackets. The #this variable holds the argument to the expression, which is initially starts at 11.

<s:property value="#fib =:[#this==0 ? 0 : #this==1 ? 1 : #fib(#this-2)+#fib(#this-1)], #fib(11)" />

JSP 2.1

Under JSP 2.1 the # character is now used by the JSP EL.

This may cause problems with some applications that use the OGNL # operator.

One quick-fix is to disable the JSP EL in a JSP 2.1 container (like GlassFish) by adding a jsp-config element to the web.xml

和JSP2.1的兼容问题处理

<jsp-config>
    <jsp-property-group>
      <url-pattern>*.jsp</url-pattern>
      <el-ignored>true</el-ignored>
    </jsp-property-group>
  </jsp-config>

最通用的方式是：给Action类添加一个方法来格式化？

That approach however suffers from a number of flaws. For example, it is not i18n aware. The date format specified is rigid, and will not adapt to different locales easily (assuming you're not using a default formatter that is). It also clutters up your actions with code that has nothing to do with the action itself.

指出添加Action中format方法的缺点n多

Instead, the recommended approach is to use Java's built-in date formatting features via use of the s:text tag.

所以，用s:text标签才是王道

The s:text tag should be used for all i18n values. It will look up the properties file for your action, and from that select the value for the key that you specify. This is best illustrated in an example:

<!-- display the number of items in a cart -->
<s:text name="'cart.items'" value0="cartItems" />

The above tag will work as follows. value0 will result in a call to getCartItems() on your action class. The cart.items name is escaped, so it is treated as a literal key into the actions' properties file. Your MyAction.properties file will contain the following:

cart.items=You have {0} items in your cart.

Normal Java MessageFormat behaviour will correctly substitute {0} with the value obtained from getCartItems.

Needless to say, this can get a lot more elaborate, with the ability to specify both date and number formatting. Let us consider another example. The goal here is to display a greeting to the user, as well as the date of their last visit.

<s:text name="'last.visit'" value0="userName" value1="lastVisit(userName)" />

MyAction.java contains:

public String getUserName() { ... };
public Date getLastVisit(String userName) { ... };

Your MyAction.properties file will then contain:

last.visit=Welcome back {0}, your last visit was at {1,date,HH:mm dd-MM-yyyy}

As you can see, this is a very powerful mechanism and allows you to easily display numbers and dates using any formatting rules that Java allows.

正如你看到的，这是一个非常强大的机制，允许你容易第展示数字和日期，而且用特定的格式化方式.
Samuel说：在Struts2里，每个Action都可以对应一个资源文件，用s:text也是不错地。就是教条了点，比如设定数字是money方式显示的话在中国自然用￥,在美国自然是$,但这里，必须显式地写两份资源文件里：一份美国：format.money = {0,number,$##0.00}，另一份中国：format.money = {0,number,￥##0.00}

value0 interface deprecated The examples above pass in the values as: <s:text name="'text.message'" value0="userName"/> These values should now (>2.1.7?) be passed as params: <s:text name="'text.message'"> <s:param value="'userName'"/> </s:text>

Some message format examples Here are some examples of formatting in the properties file: format.date = {0,date,MM/dd/yy} format.time = {0,date,MM/dd/yy ha} format.percent = {0,number,##0.00'%'} format.money = {0,number,$##0.00}

任何ognl能被计算的值，在jsp中用s标签都可以获得application,session和request对象。

<s:property value="#application\['foo'\]"/>
<s:property value="#session\['baz'\]"/>

Conversely, if you would like to make Struts 2 objects available to a JSP/JSTL scope, the s:set tag may be used like this:

相反，如果你项是的Struts2对象能在JSP/JSTL范围内获得，s:set标签可能这样用：

<s:set name="jobz" value="jobs" scope="request" />
<c:forEach items="${jobz} var="job">
...
</c:forEach>

"Auto-exposure" In Struts 2 OGNL values are automagically exposed to JSP/JSTL; using <s:set.../> as described above may not be necessary. 在Struts2 OGNL的值被自动暴露给JSP/JSTL;上面例子中<s:set .../>可能不需要。

疑问啊：Struts2 OGNL和OGNL难道是两回事？

Generic 标签用来控制页面渲染是的执行流程，还用来允许获取某个地方（不是action和value stack）的数据，例如：Loaclization，JavaBean，和 including additional URLs or action executions.

• Control Tags provide control flow, such as if, else, and iterator.

• Data Tags allow for data manipulation or creation, such as bean, push, and i18n.

The types of tags can be broken in to two types: generic and UI. Besides function and responsibility, the biggest difference between the two is that the HTML tags support templates and themes. In addition to the general tag reference, we also provide examples for using these generic tags in each of the support languages.

Tag类型能被分成两种：Generic和UI。除了功能和指责，他们之间的最大不同在预HTML标签支持模板和主题。除了通用的标签参考之外，我们提供了例子。

Be sure to read the Tag Syntax document to learn how tag attribute syntax works.

The tags are designed to display dynamic data. To create a input field that displays the property "postalCode", we'd pass the String "postalCode" to the textfield tag.

标签被设计用来展示动态数据。

<s:textfield name="postalCode"/>

If there is a "postalCode" property on the value stack, its value will be set to the input field. When the field is submitted back to the framework, the value of the control will be set back to the "postalCode" property.

Sometimes, we want to pass the dynamic data to a tag. For example, we might want to display a label with the input field, and we might want to obtain the label from the application's messages resources. Accordingly, the framework will parse expressions found in the tag attributes, so that we can merge dynamic data into the tag attributes at runtime. The expression escape sequence is "%{ ... }". Any text embedded in the escape sequence is evalulated as an expression.

有时，我们象传递动态数据到tag。例如，我们象显示Label和input在一起，我们从系统的资源文件获取Lable，框架将解析表达式，所以我们能把动态数据整合到标签属性上。表达式样子是“%{}”.在大括弧里的表达式将被计算。

<s:textfield key="postalCode.label" name="postalCode"/>

The expression language (OGNL) lets us call methods and evaluate properties. The method getText is provided by ActionSupport, which is the base class for most Actions. Since the Action is on the stack, we can call any of its methods from an expression, including getText.

Non-String Attributes

The HTTP protocol is text-based, but some tags have non-String attribute types, like bool or int. To make using non-String attributes intuitative, the framework evaulates all non-String attributes as an expression. In this case, you do not need to use the escape notation. (But, if you do anyway , the framework will just strip it off.)

<s:select key="state.label" name="state" multiple="true"/>

Since the attribute multiple maps to a boolean property, the framework does not interpret the value as a String. The value is evaluated as an expression and automtically converted to a boolean.

Since it's easy to forget which attributes are String and which are non-String, you can still use the escape notation.

<s:select key="state.label" name="state" multiple="%{true}"/>

<s:select key="state.label" name="state" multiple="allowMultiple"/>

<s:select key="state.label" name="state" multiple="%{allowMultiple}"/>

value is an Object!

Most often, the value attribute is set automatically, since name attribute usually tells the framework which property to call to set the value. But, if there is a reason to set the value directly, be advised that value is an Object NOT a String.

Since value is not a String, whatever is passed to value is evaluated as an expression - NOT a String literal.

<s:textfield key="state.label" name="state" value="CA"/>

If a textfield is passed the value attribute "CA", the framework will look for a property named getCa. Generally, this is not what we mean. What we mean to do is pass a literal String. In the expression language, literals are placed within quotes

<s:textfield key="state.label" name="state" value="%{'CA'}" />

Another approach would be to use the idiom value="'CA'", but, in this case, using the expression notation is recommended.

Boiled down, the tag attributes are evaluated using three rules.

1. All String attribute types are parsed for the "%{ ... }" notation.
2. All non-String attribute types are not parsed, but evaluated directly as an expression
3. The exception to rule #2 is that if the non-String attribute uses the escape notion "{%{}", the notation is ignored as redundant, and the content evaluated.

Expression Language Notations

<p>Username: ${user.username}</p>

<s:textfield name="username"/>

<s:url id="es" action="Hello">
  <s:param name="request_locale">
    es
  </s:param>
</s:url>
<s:a href="%{es}">Espanol</s:a>

<s:property
  name="#session.user.username" />

<s:select
  label="FooBar" name="foo"
  list="#{'username':'trillian',
    'username':'zaphod'}" />

• Reference an Action for the image src attribute

• Provide a helper method on the Action to return an array of bytes

• Provide a Result Type that renders the array to the response

MyAction.jsp

<img src="/myWebAppContext/myAction.do" />

Provide Helper Methods

public class MyAction extends ActionSupport {
  public String doDefault() {
    return "myImageResult";
  }

  public byte[] getMyImageInBytes() { .... }

  public String getMyContentType() { ... }
  public String getMyContentDisposition() { ... }
  public int getMyContentLength() { .... }
  public int getMyBufferSize() { ... }

}

Provide a Custom Result Type

<struts>

    ...
    <result-types>
        <result-type name="myBytesResult" class="MyBytesResult" />
    </result-types>
    ...
    <action name="myAction" class="MyAction">
        <result name="myImageResult" type="myBytesResult">
            <param name="contentType">${myContentType}</param>
            <param name="contentDisposition">${myContentDisposition}</param>
            <param name="contentLength">${myContentLength}</param>
            <param name="bufferSize">${myBufferSize}</param>
        <result>
    </action>
    ...

</struts>

public class MyBytesResult implements Result {

	public void execute(ActionInvocation invocation) throws Exception {

		MyAction action = (MyAction) invocation.getAction();
		HttpServletResponse response = ServletActionContext.getResponse();

                response.setContentType(action.getContentType());
		response.setContentLength(action.getContentLength());

		response.getOutputStream().write(action.getImageInBytes());
		response.getOutputStream().flush();
	}

}

package org.petsoar.actions.inventory;

import com.mockobjects.constraint.IsEqual;
import com.mockobjects.dynamic.C;
import com.mockobjects.dynamic.Mock;
import com.opensymphony.xwork.Action;
import junit.framework.TestCase;
import org.petsoar.pets.Pet;
import org.petsoar.pets.PetStore;

public class TestViewPet extends TestCase {
    private Mock mockPetStore;
    private ViewPet action;

    protected void setUp() throws Exception {
        mockPetStore = new Mock(PetStore.class);
        PetStore petStore = (PetStore) mockPetStore.proxy();

        action = new ViewPet();
        action.setPetStore(petStore);
    }

    public void testViewPet() throws Exception {
        Pet existingPet = new Pet();
        existingPet.setName("harry");
        existingPet.setId(1);

        Pet expectedPet = new Pet();
        expectedPet.setName("harry");
        expectedPet.setId(1);

        mockPetStore.expectAndReturn("getPet", C.args(new IsEqual(new Long(1))), existingPet);
        action.setId(1);

        String result = action.execute();

        assertEquals(Action.SUCCESS, result);
        assertEquals(expectedPet, existingPet);
        mockPetStore.verify();
    }

    public void testViewPetNoId() throws Exception {
        mockPetStore.expectAndReturn("getPet", C.ANY_ARGS, null);

        String result = action.execute();

        assertEquals(Action.ERROR, result);
        assertEquals(1, action.getActionErrors().size());
        assertEquals("Invalid pet selected.", action.getActionErrors().iterator().next());
        assertNull(action.getPet());
        mockPetStore.verify();
    }

    public void testViewPetInvalidId() throws Exception {
        action.setId(-1);
        testViewPetNoId();
    }
}

public void testDoesNotAllowMethodInvocations() {
    Map params = new HashMap();
    params.put("@java.lang.System@exit(1).dummy", "dumb value");

    HashMap extraContext = new HashMap();
    extraContext.put(ActionContext.PARAMETERS, params);

    try {
        ActionProxy proxy = ActionProxyFactory.getFactory().
               createActionProxy("", MockConfigurationProvider.MODEL_DRIVEN_PARAM_TEST, extraContext);
        assertEquals(Action.SUCCESS, proxy.execute());

        ModelDrivenAction action = (ModelDrivenAction) proxy.getAction();
        TestBean model = (TestBean) action.getModel();

        String property = System.getProperty("action.security.test");
        assertNull(property);
    } catch (Exception e) {
        e.printStackTrace();
        fail();
    }
}

MultipartRequestWrapper multipartRequest = ((MultipartRequestWrapper)ServletActionContext.getRequest())

<form name="myForm" enctype="multipart/form-data">
     <input type="file" name="myDoc" value="Browse ..." />
     <input type="submit" />
  </form>

public void setMyDoc(File myDoc)
public void setMyDocContentType(String contentType)
public void setMyDocFileName(String filename)

public File getMyDoc()
public ContentType getMyDocContentType()
public String getMyDocFileName()

<form name="myForm" enctype="multipart/form-data">
      <input type="file" name="myDoc" value="Browse File A ..." />
      <input type="file" name="myDoc" value="Browse File B ..." />
      <input type="file" name="myDoc" value="Browse File C ..." />
      <input type="submit" />
   </form>

public void setMyDoc(File[] myDocs)
public void setMyDocContentType(String[] contentTypes)
public void setMyDocFileName(String[] fileNames)

<struts>
....
   <package name="somePackage" namespace="/myNamespace" extends="struts-default">
      <action name="myAction" class="com.project.MyAction">
         <result name="success" type="redirect-action">otherAction?id=${id}</result>
         <result name="back" type="redirect">${redirectURL}</result>
      </action>

      <action name="otherAction" class="com.project.MyOtherAction">
         ...
      </action>      
   </package>
....
</struts>

public class MyAction extends ActionSupport {
   private int id;
   private String redirectURL;
   ...


   public String execute() {
       ...
      if (someCondition) {
         this.redirectURL = "/the/target/page.action";
         return "back";
      }

      this.id = 123;
      return SUCCESS; 
   }

   public int getId() { return this.id; }
   public void setId(int id) { this.id = id; }
   public String getRedirectURL() { return this.redirectURL; }
   public void setRedirectURL(String redirectURL) { this.redirectURL= redirectURL; }
   ...
}

You can obtain the request parameters by asking the ActionContext or implementing ParameterAware. Implementing ParameterAware is preferred.

你可以通过访问ActionContext或者实现ParameterAware获取请求参数。实现ParameterAware是首选的。

Ask the ActionContext

The request parameters are available on the ActionContext instance, which is made available via ThreadLocal.

Map parameters = ActionContext.getContext().getParameters();

Implement ParameterAware

Preferred

• Ensure that servlet-config Interceptor is included in the Action's stack.
  • The default stack already includes servlet-config.
• Edit the Action so that it implements the ParameterAware interface.
  • The ParameterAware interface expects a setParameters method. You may wish to include a companion getParameters method.
• At runtime, call getParameters to obtain a Map representing the request parameters.

Map parameters = this.getParameters();

When the servlet-config Interceptor sees that an Action implements ParameterAware, it passes a Map of the request parameters to the Action's setParameters method.

To unit test a ParameterAware Action, create your own Map with the pertinent request parameters and call setParameters as part of the test's setUp method.

@see struts-default.xml
@see org.apache.struts.action2.interceptor.ParameterAware
@see org.apache.struts.action2.interceptor.Servlet Config Interceptor

HttpServletRequest request = ServletActionContext.getRequest();
String authType = request.getAuthType();         // http or https
String user = request.getRemoteUser();           // the user principal (in string)
Principalprincipal = request.getUserPrincipal(); // get a Principal object
bool isAuth = request.isUserInRole("patrick");

About JSTL The JavaServer Pages Standard Tag Library (JSTL) encapsulates as simple tags the core functionality common to many Web applications. JSTL has support for common, structural tasks such as iteration and conditionals, tags for manipulating XML documents, internationalization tags, and SQL tags.

JSTL integration is built into the framework - there are no steps required to enable it. Simply refer to your JSTL expressions just as you would with a normal SAF JSP tag, such as the property tag.

JSTL被整合到框架里面，不需要做任何工作。GOOD！

Javadoc: (org.apache.struts.action2.dispatcher.StrutsRequestWrapper) All Struts requests are wrapped with this class, which provides simple JSTL accessibility. This is because JSTL works with request attributes, so this class delegates to the value stack except for a few cases where required to prevent infinite loops. Namely, we don't let any attribute name with "#" in it delegate out to the value stack, as it could potentially cause an infinite loop. For example, an infinite loop would take place if you called: request.getAttribute("#attr.foo").

Many Actions share common concerns. Some Actions need input validated. Other Actions may need a file upload to be pre-processed. Another Action might need protection from a double submit. Many Actions need drop-down lists and other controls pre-populated before the page displays.

很多Action共享通用的装置。一些Action需要输入验证，其他Action可能需要文件上传被预处理。另外一些Action可能需要防止两次提交。很多Action需要在页面显示之前，dropdownlist和其他控件被预前渲染。

The Struts Action Framework makes it easy to share solutions to these concerns using an "Interceptor" strategy. When you request a resource that maps to an "action", the framework invokes the Action object. But, before the Action is executed, the invocation can be intercepted by another object. After the Action executes, the invocation could be intercepted again. Unsurprisingly, we call these objects "Interceptors."

Interceptor在一个Action前后工作。

Understanding Interceptors

Interceptors can execute code before and after an Action is invoked. Most of the framework's core functionality is implemented as Interceptors. Features like double-submit guards, type conversion, object population, validation, file upload, page preparation, and more, are all implemented with the help of Interceptors. Each and every Interceptor is pluggable, so you can decide exactly which features an Action needs to support.

Interceptors can be configured on a per-action basis. Your own custom Interceptors can be mixed-and-matched with the Interceptors bundled with the framework. Interceptors "set the stage" for the Action classes, doing much of the "heavy lifting" before the Action executes.

ion Lifecyle
Action Lifecyle

In some cases, an Interceptor might keep an Action from firing, because of a double-submit or because validation failed. Interceptors can also change the state of an Action before it executes.

The Interceptors are defined in a stack that specifies the execution order. In some cases, the order of the Interceptors on the stack can be very important.

Configuring Interceptors

<package name="default" extends="struts-default">
   <interceptors>
       <interceptor name="timer" class=".."/>
       <interceptor name="logger" class=".."/>
   </interceptors>

   <action name="login"
      class="tutorial.Login">
        <interceptor-ref name="timer"/>
        <interceptor-ref name="logger"/>
         <result name="input">login.jsp</result>
         <result name="success"
            type="redirect-action">/secure/home</result>
   </action>
</package>

Stacking Interceptors

With most web applications, we find ourselves wanting to apply the same set of Interceptors over and over again. Rather than reiterate the same list of Interceptors, we can bundle these Interceptors together using an Interceptor Stack.

<package name="default" extends="struts-default">
   <interceptors>
        <interceptor name="timer" class=".."/>
        <interceptor name="logger" class=".."/>
        <interceptor-stack name="myStack">
           <interceptor-ref name="timer"/>
           <interceptor-ref name="logger"/>
        </interceptor-stack>
    </interceptors>

<action name="login"
     class="tutuorial.Login">
         <interceptor-ref name="myStack"/>
         <result name="input">login.jsp</result>
         <result name="success"
             type="redirect-action">/secure/home</result>
</action>
</package>

Looking inside struts-default.xml, we can see how it's done.

The Default Configuration

<!DOCTYPE struts PUBLIC
    "-//Apache Software Foundation//DTD Struts Configuration 2.0//EN"
    "http://struts.apache.org/dtds/struts-2.0.dtd">

<!-- // START SNIPPET: struts-default -->
<struts>
    <package name="struts-default">
        <result-types>
            <result-type name="chain" class="com.opensymphony.xwork.ActionChainResult"/>
            <result-type name="dispatcher" class="org.apache.struts2.dispatcher.ServletDispatcherResult"
                         default="true"/>
            <result-type name="freemarker" class="org.apache.struts2.views.freemarker.FreemarkerResult"/>
            <result-type name="httpheader" class="org.apache.struts2.dispatcher.HttpHeaderResult"/>
            <result-type name="jasper" class="org.apache.struts2.views.jasperreports.JasperReportsResult"/>
            <result-type name="redirect" class="org.apache.struts2.dispatcher.ServletRedirectResult"/>
            <result-type name="redirect-action"
                         class="org.apache.struts2.dispatcher.ServletActionRedirectResult"/>
            <result-type name="stream" class="org.apache.struts2.dispatcher.StreamResult"/>
            <result-type name="velocity" class="org.apache.struts2.dispatcher.VelocityResult"/>
            <result-type name="xslt" class="org.apache.struts2.views.xslt.XSLTResult"/>
        </result-types>

        <interceptors>
            <interceptor name="alias" class="com.opensymphony.xwork.interceptor.AliasInterceptor"/>
            <interceptor name="autowiring"
                         class="com.opensymphony.xwork.spring.interceptor.ActionAutowiringInterceptor"/>
            <interceptor name="chain" class="com.opensymphony.xwork.interceptor.ChainingInterceptor"/>
            <interceptor name="component" class="com.opensymphony.xwork.interceptor.component.ComponentInterceptor"/>
            <interceptor name="conversionError"
                         class="org.apache.struts2.interceptor.WebWorkConversionErrorInterceptor"/>
            <interceptor name="external-ref" class="com.opensymphony.xwork.interceptor.ExternalReferencesInterceptor"/>
            <interceptor name="execAndWait" class="corg.apache.struts2.interceptor.ExecuteAndWaitInterceptor"/>
            <interceptor name="exception" class="com.opensymphony.xwork.interceptor.ExceptionMappingInterceptor"/>
            <interceptor name="fileUpload" class="com.opensymphony.webwork.interceptor.FileUploadInterceptor"/>
            <interceptor name="i18n" class="com.opensymphony.xwork.interceptor.I18nInterceptor"/>
            <interceptor name="logger" class="com.opensymphony.xwork.interceptor.LoggingInterceptor"/>
            <interceptor name="model-driven" class="com.opensymphony.xwork.interceptor.ModelDrivenInterceptor"/>
            <interceptor name="params" class="com.opensymphony.xwork.interceptor.ParametersInterceptor"/>
            <interceptor name="prepare" class="com.opensymphony.xwork.interceptor.PrepareInterceptor"/>
            <interceptor name="static-params" class="com.opensymphony.xwork.interceptor.StaticParametersInterceptor"/>
            <interceptor name="servlet-config" class="org.apache.struts.action2.interceptor.ServletConfigInterceptor"/>
            <interceptor name="sessionAutowiring"
                         class="org.apache.struts2.spring.interceptor.SessionContextAutowiringInterceptor"/>
            <interceptor name="timer" class="com.opensymphony.xwork.interceptor.TimerInterceptor"/>
            <interceptor name="token" class="com.opensymphony.webwork.interceptor.TokenInterceptor"/>
            <interceptor name="token-session"
                         class="com.opensymphony.webwork.interceptor.TokenSessionStoreInterceptor"/>
            <interceptor name="validation" class="com.opensymphony.xwork.validator.ValidationInterceptor"/>
            <interceptor name="workflow" class="com.opensymphony.xwork.interceptor.DefaultWorkflowInterceptor"/>

            <!-- Basic stack -->
            <interceptor-stack name="basicStack">
                <interceptor-ref name="exception"/>
                <interceptor-ref name="servlet-config"/>
                <interceptor-ref name="prepare"/>
                <interceptor-ref name="static-params"/>
                <interceptor-ref name="params"/>
                <interceptor-ref name="conversionError"/>
            </interceptor-stack>

            <!-- Sample validation and workflow stack -->
            <interceptor-stack name="validationWorkflowStack">
                <interceptor-ref name="basicStack"/>
                <interceptor-ref name="validation"/>
                <interceptor-ref name="workflow"/>
            </interceptor-stack>

            <!-- Sample file upload stack -->
            <interceptor-stack name="fileUploadStack">
                <interceptor-ref name="fileUpload"/>
                <interceptor-ref name="basicStack"/>
            </interceptor-stack>

            <!-- Sample model-driven stack  -->
            <interceptor-stack name="modelDrivenStack">
                <interceptor-ref name="model-driven"/>
                <interceptor-ref name="basicStack"/>
            </interceptor-stack>

            <!-- Sample action chaining stack -->
            <interceptor-stack name="chainStack">
                <interceptor-ref name="chain"/>
                <interceptor-ref name="basicStack"/>
            </interceptor-stack>

            <!-- Sample i18n stack -->
            <interceptor-stack name="chainStack">
                <interceptor-ref name="i18n"/>
                <interceptor-ref name="basicStack"/>
            </interceptor-stack>

            <!-- Sample execute and wait stack.
                 Note: execAndWait should always be the *last* interceptor. -->
            <interceptor-stack name="executeAndWaitStack">
                <interceptor-ref name="basicStack"/>
                <interceptor-ref name="execAndWait"/>
            </interceptor-stack>

            <!-- A complete stack with all the common interceptors in place.
                 Generally, this stack should be the one you use, though it
                 may process additional stuff you don't need, which could
                 lead to some performance problems. Also, the ordering can be
                 switched around (ex: if you wish to have your components
                 before prepare() is called, you'd need to move the component
                 interceptor up -->
            <interceptor-stack name="defaultStack">
                <interceptor-ref name="exception"/>
                <interceptor-ref name="alias"/>
                <interceptor-ref name="prepare"/>
                <interceptor-ref name="servlet-config"/>
                <interceptor-ref name="i18n"/>
                <interceptor-ref name="chain"/>
                <interceptor-ref name="model-driven"/>
                <interceptor-ref name="fileUpload"/>
                <interceptor-ref name="static-params"/>
                <interceptor-ref name="params"/>
                <interceptor-ref name="conversionError"/>
                <interceptor-ref name="validation"/>
                <interceptor-ref name="workflow"/>
            </interceptor-stack>

            <!-- The completeStack is here for backwards compatibility for
                 applications that still refer to the defaultStack by the
                 old name -->
            <interceptor-stack name="completeStack">
                <interceptor-ref name="defaultStack"/>
            </interceptor-stack>
        </interceptors>

        <default-interceptor-ref name="defaultStack"/>
    </package>
</struts>
<!-- // END SNIPPET: struts-default -->

Since the struts-default.xml is included in the application's configuration by default, all of the predefined interceptors and stacks are available "out of the box".

Framework Interceptors

Interceptor classes are also defined using a key-value pair specified in the Struts configuration file. The names specified below come specified in struts-default.xml. If you extend the struts-default package, then you can use the names below. Otherwise, they must be defined in your package with a name-class pair specified in the <interceptors> tag.

Method Filtering

An abstract Interceptor that is applied to selectively according to specified included/excluded method lists.

Setable parameters are as follows:

• excludeMethods - methods name to be excluded
• includeMethods - methods name to be included

NOTE: If method name are available in both includeMethods and excludeMethods, it will still be considered as an included method. In short includeMethods takes precedence over excludeMethods.

Interceptors that extends this capability would be :-

• TokenInterceptor
• TokenSessionStoreInterceptor
• DefaultWorkflowInterceptor
• ValidationInterceptor

Interceptor Parameter Overriding

Interceptor's parameter could be overriden through the following ways :-

Method 1:

<action name="myAction" class="myActionClass">
  <interceptor-ref name="exception"/>
    <interceptor-ref name="alias"/>
    <interceptor-ref name="params"/>
    <interceptor-ref name="servlet-config"/>
    <interceptor-ref name="prepare"/>
    <interceptor-ref name="i18n"/>
    <interceptor-ref name="chain"/>
    <interceptor-ref name="model-driven"/>
    <interceptor-ref name="fileUpload"/>
    <interceptor-ref name="static-params"/>
    <interceptor-ref name="params"/>
    <interceptor-ref name="conversionError"/>
    <interceptor-ref name="validation">
      <param name="excludeMethods">myValidationExcudeMethod</param>
    </interceptor-ref>
    <interceptor-ref name="workflow">
      <param name="excludeMethods">myWorkflowExcludeMethod</param>
    </interceptor-ref>
</action>

Method 2:

<action name="myAction" class="myActionClass">
  <interceptor-ref name="defaultStack">
    <param name="validation.excludeMethods">myValidationExcludeMethod</param>
    <param name="workflow.excludeMethods">myWorkflowExcludeMethod</param>
  </interceptor-ref>
</action>

In the first method, the whole default stack is copied and the parameter then changed accordingly.

In the second method, the refer to an existing interceptor-stack, namely default-stack in this example, and override the validator and workflow interceptor excludeMethods typically in this case. Note that in the tag, the name attribute contains a dot (.) the word before the dot(.) specifies the interceptor name whose parameter is to be overriden and the word after the dot (.) specifies the parameter itself. Essetially it is as follows :-

   <interceptor-name>.<parameter-name>

Note also that in this case the name attribute is used to indicate an interceptor stack which makes sense as if it is refering to the interceptor itself it would be just using Method 1 describe above.

Order of Interceptor Execution

Interceptors provide an excellent means to wrap before/after processing. The concept reduces code duplication (think AOP).

<interceptor-stack name="xaStack">
  <interceptor-ref name="thisWillRunFirstInterceptor"/>
  <interceptor-ref name="thisWillRunNextInterceptor"/>
  <interceptor-ref name="followedByThisInterceptor"/>
  <interceptor-ref name="thisWillRunLastInterceptor"/>
</interceptor-stack>

Note that some Interceptors will interrupt the stack/chain/flow ... so the order is very important.

Interceptors implementing com.opensymphony.xwork.interceptor.PreResultListener will run after the Action executes but before the Result executes.

thisWillRunFirstInterceptor
  thisWillRunNextInterceptor
    followedByThisInterceptor
      thisWillRunLastInterceptor
        MyAction1
        MyAction2 (chain)
        MyPreResultListener
        MyResult (result)
      thisWillRunLastInterceptor
    followedByThisInterceptor
  thisWillRunNextInterceptor
thisWillRunFirstInterceptor

常规转换在框架里是透明的，通常，所有你需要做的就是保证HTML inputs有名字，使得这些名字能在OGNL表达式中使用。

A Simple Example

Type conversion is great for situations where you need to turn a String in to a more complex object. Because the web is type-agnostic (everything is a string in HTTP), WebWork's type conversion features are very useful. For instance, if you were prompting a user to enter in coordinates in the form of a string (such as "3, 22"), you could have WebWork do the conversion both from String to Point and from Point to String.

在你需要转换String到复杂对象的情况下，类型转换式非常重要的。因为web是一个不懂类型的东西，Webwork类型的转换是非常有用的。例如，你让用户输入一个string（例如：“3,22”）,你能让WebWork做从String到Point，以及Point到String的转换。

Using this "point" example, if your action (or another compound object in which you are setting properties on) has a corresponding ClassName-conversion.properties file, WebWork will use the configured type converters for conversion to and from strings. So turning "3, 22" in to new Point(3, 22) is done by merely adding the following entry to ClassName-conversion.properties (Note that the PointConverter should impl the ognl.TypeConverter interface):

point = com.acme.PointConverter

Your type converter should be sure to check what class type it is being requested to convert. Because it is used for both to and from strings, you will need to split the conversion method in to two parts: one that turns Strings in to Points, and one that turns Points in to Strings.

After this is done, you can now reference your point (using <ww:property value="post"/> in JSP or ${point} in FreeMarker) and it will be printed as "3, 22" again. As such, if you submit this back to an action, it will be converted back to a Point once again.

In some situations you may wish to apply a type converter globally. This can be done by editing the file xwork-conversion.properties in the root of your class path (typically WEB-INF/classes) and providing a property in the form of the class name of the object you wish to convert on the left hand side and the class name of the type converter on the right hand side. For example, providing a type converter for all Point objects would mean adding the following entry:

com.acme.Point = com.acme.PointConverter

Type conversion should not be used as a substitute for i18n. It is not recommended to use this feature to print out properly formatted dates. Rather, you should use the i18n features of WebWork (and consult the JavaDocs for JDK's MessageFormat object) to see how a properly formatted date should be displayed.

The framework ships with a base helper class that simplifies converting to and from Strings, org.apache.struts.action2.util.StrutsTypeConverter. The helper class makes it easy to write type converters that handle converting objects to Strings as well as from Strings.

From the JavaDocs:

Base class for type converters used in Struts. This class provides two abstract methods that are used to convert both to and from strings – the critical functionality that is core to Struts's type coversion system.

Type converters do not have to use this class. It is merely a helper base class, although it is recommended that you use this class as it provides the common type conversion contract required for all web-based type conversion.

There's a hook (fall back method) called performFallbackConversion of which could be used to perform some fallback conversion if convertValue method of this failed. By default it just ask its super class (Ognl's DefaultTypeConverter) to do the conversion.

To allow the framework to recognize that a conversion error has occurred, throw an XWorkException or preferable a TypeConversionException.

Built in Type Conversion Support

XWork will automatically handle the most common type conversion for you. This includes support for converting to and from Strings for each of the following:

• String
• boolean / Boolean
• char / Character
• int / Integer, float / Float, long / Long, double / Double
• dates - uses the SHORT format for the Locale associated with the current request
• arrays - assuming the individual strings can be coverted to the individual items
• collections - if not object type can be determined, it is assumed to be a String and a new ArrayList is created

Note that with arrays the type conversion will defer to the type of the array elements and try to convert each item individually. As with any other type conversion, if the conversion can't be performed the standard type conversion error reporting is used to indicate a problem occured while processing the type conversion.

Relationship to Parameter Names

The best way to take advantage of the framework's type conversion is to utilize complete objects (ideally your domain objects directly). There is no need to capture form values using intermediate Strings and primitives and then convert those values to full objects in an Action method.

Here are some tips for leveraging the framework's type conversion capabilties:

• Use complex OGNL expressions - the framework will automatically take care of creating the actual objects for you.
• Use JavaBeans! The framework can only create objects if the objects obey the JavaBean specification and provide no-arg constructions, as well as getters and setters where appropriate.
• Remember that person.name will call getPerson().setName(), but if in order for the framework to create the Person object for you, a setPerson must also exist.
• For lists and maps, use index notation, such as people[0].name or friends['patrick'].name. Often these HTML form elements are being rendered inside a loop. For JSP Tags, use the iterator tag's status attribute. For FreeMarker Tags, use the special property ${foo_index}[].
• For multiple select boxes, it isn't possible to use index notation to name each individual item. Instead, name your element people.name and the framework will understand that it should create a new Person object for each selected item and set its name accordingly.

Creating a Type Converter

To create a type converter one would need to extends StrutsTypeConverter.

public class MyConverter extends StrutsTypeConverter {
    public Object convertFromString(Map context, String[] values, Class toClass) {
       .....
    }

    public String convertToString(Map context, Object o) {
       .....
    }
 }

To allow Struts to recognize that a conversion error has occurred, the converter class need to throw XWorkException or preferably TypeConversionException.

Advanced Type Conversion

The framework also handles advanced type conversion cases, like null property handling and converting values in Maps and Collections, and type conversion error handling.

Null Property Handling

Null property handling will automatically create objects where null references are found.

Provided that the key #CREATE_NULL_OBJECTS is in the action context with a value of true (this key is set only during the execution of the com.opensymphony.xwork2.interceptor.ParametersInterceptor), OGNL expressions that have caused a NullPointerException will be temporarily stopped for evaluation while the system automatically tries to solve the null references by automatically creating the object.

The following rules are used when handling null references:

• If the property is declared exactly as a Collection or List, then an ArrayList shall be returned and assigned to the null references.
• If the property is declared as a Map, then a HashMap will be returned and assigned to the null references.
• If the null property is a simple bean with a no-arg constructor, it will simply be created using the {@link ObjectFactory#buildBean(java.lang.Class, java.util.Map)} method.

For example, if a form element has a text field named person.name and the expression person evaluates to null, then this class will be invoked. Because the person expression evaluates to a Person class, a new Person is created and assigned to the null reference. Finally, the name is set on that object and the overall effect is that the system automatically created a Person object for you, set it by calling setUsers() and then finally called getUsers().setName() as you would typically expect.

Collection and Map Support

Collection and Map support provides intelligent null handling and type conversion for Java Collections.

The framework supports ways to discover the object type for elements in a collection. The discover is made via an ObjectTypeDeterminer. A default implementation is provided with the framework. The Javadocs explain how Map and Collection support is discovered in the DefaultObjectTypeDeterminer.

This ObjectTypeDeterminer looks at the Class-conversion.properties for entries that indicated what objects are contained within Maps and Collections. For Collections, such as Lists, the element is specified using the pattern Element_xxx, where xxx is the field name of the collection property in your action or object. For Maps, both the key and the value may be specified by using the pattern Key_xxx and Element_xxx, respectively.

From WebWork 2.1.x, the Collection_xxx format is still supported and honored, although it is deprecated and will be removed eventually.

Additionally, you can create your own custom ObjectTypeDeterminer by implementing the ObjectTypeDeterminer interface. There is also an optional ObjectTypeDeterminer that utilizes Java 5 generics. See the Annotations page for more information.

Indexing a collection by a property of that collection

It is also possible to obtain a unique element of a collection by passing the value of a given property of that element. By default, the property of the element of the collection is determined in Class-conversion.properties using KeyProperty_xxx=yyy, where xxx is the property of the bean Class that returns the collection and yyy is the property of the collection element that we want to index on.

For an example, see the following two classes:

/**
 * @return a Collection of Foo objects
 */
public Collection getFooCollection()
{
    return foo;
}

/**
 * @return a unique identifier
 */
public Long getId()
{
    return id;
}

To enable type conversion, put the instruction KeyProperty_fooCollection=id in the MyAction-conversion.properties file. This technique allows use of the idiom fooCollection(someIdValue) to obtain the Foo object with value someIdValue in the Set fooCollection. For example, fooCollection(22) would return the Foo object in the fooCollection Collection whose id property value was 22.

This technique is useful, because it ties a collection element directly to its unique identifier. You are not forced to use an index. You can edit the elements of a collection associated to a bean without any additional coding. For example, parameter name fooCollection(22).name and value Phil would set name the Foo Object in the fooCollection Collection whose id property value was 22 to be Phil.

The framework automatically converts the type of the parameter sent in to the type of the key property using type conversion.

Unlike Map and List element properties, if fooCollection(22) does not exist, it will not be created. If you would like it created, use the notation fooCollection.makeNew[index] where index is an integer 0, 1, and so on. Thus, parameter value pairs fooCollection.makeNew[0]=Phil and fooCollection.makeNew[1]=John would add two new Foo Objects to fooCollection -- one with name property value Phil and the other with name property value Bar. However, in the case of a Set, the equals and hashCode methods should be defined such that they don't only include the id property. Otherwise, one element of the null id properties Foos to be removed from the Set.

An advanced example for indexed Lists and Maps

Here is the model bean used within the list. The KeyProperty for this bean is the id attribute.

public class MyBean implements Serializable {

    private Long id;
    private String name;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }


    public String toString() {
        return "MyBean{" +
                "id=" + id +
                ", name='" + name + '\'' +
                '}';
    }
}

The Action has a beanList attribute initialized with an empty ArrayList.

public class MyBeanAction implements Action {

    private List beanList = new ArrayList();
    private Map beanMap = new HashMap();

    public List getBeanList() {
        return beanList;
    }

    public void setBeanList(List beanList) {
        this.beanList = beanList;
    }

    public Map getBeanMap() {
        return beanMap;
    }

    public void setBeanMap(Map beanMap) {
        this.beanMap = beanMap;
    }

    public String execute() throws Exception {
        return SUCCESS;
    }
}

These conversion.properties tell the TypeConverter to use MyBean instances as elements of the List.

KeyProperty_beanList=id
Element_beanList=MyBean
CreateIfNull_beanList=true

• When submitting this via a form, the id value is used as KeyProperty for the MyBean instances in the beanList.

• Notice the () notation! Do not use [] notation, which is for Maps only!

• The value for name will be set to the MyBean instance with this special id.

• The List does not have null values added for unavailable id values. This approach avoids the risk of OutOfMemoryErrors!

<ww:iterator value="beanList" id="bean">
  <ww:textfield name="beanList(%{bean.id}).name" />
</ww:iterator>

Type Conversion Error Handling

Type conversion error handling provides a simple way to distinguish between an input validation problem and an input type conversion problem.

Any error that occurs during type conversion may or may not wish to be reported. For example, reporting that the input "abc" could not be converted to a number might be important. On the other hand, reporting that an empty string, "", cannot be converted to a number might not be important - especially in a web environment where it is hard to distinguish between a user not entering a value vs. entering a blank value.

By default, all conversion errors are reported using the generic i18n key xwork.default.invalid.fieldvalue, which you can override (the default text is Invalid field value for field "xxx", where xxx is the field name) in your global i18n resource bundle.

However, sometimes you may wish to override this message on a per-field basis. You can do this by adding an i18n key associated with just your action (Action.properties) using the pattern invalid.fieldvalue.xxx, where xxx is the field name.

It is important to know that none of these errors are actually reported directly. Rather, they are added to a map called conversionErrors in the ActionContext. There are several ways this map can then be accessed and the errors can be reported accordingly.

There are two ways the error reporting can occur:

1. Globally, using the Conversion Error Interceptor
2. On a per-field basis, using the conversion validator

By default, the conversion interceptor is included in struts-default.xml in the default stack. To keep conversion errors from reporting globally, change the interceptor stack, and add additional validation rules.

AJAX-based client side validation improves upon Pure JavaScript Client Side Validation by using a combination of JavaScript, DOM manipulation, and remote server communication via DWR. Unlike the pure client side implementation, AJAX-based validation communicates with the server. This means all your validation rules that worked when submitting a form will still work within the browser.

AJAX基础上的客户端验证改进了Pure Javascript 客户端验证。它依赖于整合了Javascript，DOM操作，以及通过DWR和原断的server交互。不象纯javascript，AJAX－base的验证与服务器端交互。这意味着提交form后所有验证规则仍然在浏览器里工作。

The validation occurs on each onblur event for each form element. As each user types in some values and moves to the next form element, the value (and all other values previously entered) will be sent to the server for validation. The entire validation stack is run, including visitor validators and your action's validate() method.

Validation在每个元素的onblur事件后发生。当用户输入一些值，然后跳到下一个元素是，先输入的值将被送到服务端验证。整个验证栈正在运行，包括visitor validators和你的action的validate()方法。

If there is an error, like the pure implementation, the HTML and DOM will be updated immediately.

For an example of this, see AJAX Validation.

Description

Ajax Validation requires DWR servlet being setup, Dojo and the Ajax theme being used.      Ajax Validation需要建立DWR Servlet，使用Dojo和Ajax主题。 In the Ajax theme, DWR is used for normal validation while Dojo handles everything else (widgets, XHR, browser JS events etc.)      在Ajax 主题里，DWR是用作常规的验证，而Dojo处理其他事情（...） In order for validation to function properly it is advised to used standard Struts Tags.      为了使验证工作正常进行，建议使用标准的Struts Tags。

Setup DWR

DWR could be setup by having the following dwr configuration (dwr.xml) at /WEB-INF/ directory. If it needs to be in other places, refer to http://getahead.ltd.uk/dwr/ for more information.

DWR通过防止drw.xml到/WEB-INF/ 目录来建立。

<!DOCTYPE dwr PUBLIC 
	"-//GetAhead Limited//DTD Direct Web Remoting 1.0//EN" 
	"http://www.getahead.ltd.uk/dwr/dwr10.dtd">

<dwr>
    <allow>
        <create creator="new" javascript="validator">
            <param name="class" value="org.apache.struts2.validators.DWRValidator"/>
        </create>
        <convert converter="bean" match="com.opensymphony.xwork2.ValidationAwareSupport"/>
    </allow>

    <signatures>
        <![CDATA[
        import java.util.Map;
        import org.apache.struts2.validators.DWRValidator;

        DWRValidator.doPost(String, String, Map<String, String>);
        ]]>
    </signatures>
</dwr>

A DWRServlet need to be registered with the web application as well. The following shows a typical web.xml with DWRSerlvet.

DWRServlet需要注册给web应用，下面展示了如何在web.xml中注册DWRServlet

<servlet>
       <servlet-name>dwr</servlet-name>
       <servlet-class>uk.ltd.getahead.dwr.DWRServlet</servlet-class>
       <init-param>
           <param-name>debug</param-name>
           <param-value>true</param-value>
       </init-param>
   </servlet>

<!-- JavaServer Faces Servlet Configuration, not used directly -->
 	<servlet>
   	<servlet-name>faces</servlet-name>
    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
   	<load-on-startup>1</load-on-startup>
 	</servlet>

 	<!-- JavaServer Faces Servlet Mapping, not called directly -->
   	<servlet-mapping>
       <servlet-name>faces</servlet-name>
       <url-pattern>*.action</url-pattern>
 	</servlet-mapping>

   <servlet-mapping>
       <servlet-name>dwr</servlet-name>
       <url-pattern>/dwr/*</url-pattern>
   </servlet-mapping>

Step 1

Create the jsp page. Note the <ww:head ...> tag is used to set the theme which will put in necesary dojo sripts etc. See ajax's theme head.ftl for more information.

创建jsp页面。注意<s:head...>标签用来获取放置需要dojoscript等的主题。

<html>
<head>
    <title>Validation - Basic</title>
    <s:head theme="ajax"/>
</head>

<body>

<s:form method="post" validate="true" theme="ajax">
    <s:textfield label="Name" name="name"/>
    <s:textfield label="Age" name="age"/>
    <s:textfield label="Favorite color" name="answer"/>
    <s:submit/>
</s:form>

</body>
</html>

Step 2

Create the action class

public class QuizAction extends ActionSupport {

    private static final long serialVersionUID = -7505437345373234225L;

    String name;
    int age;
    String answer;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    public String getAnswer() {
        return answer;
    }

    public void setAnswer(String answer) {
        this.answer = answer;
    }
}

Step 3

Create the validation.xml

Pure JavaScript client side validation is the simplest but least feature-rich type of Client Side Validation. This type of validation uses 100% client-side JavaScript code to try to validate the values entered by the user. Because the validation logic is actually repeated in the JavaScript code, it is important to understand that some values will be considered acceptable by the JavaScript code but will be marked as unacceptable by the server-side Validation.

纯Javascript客户端验证是最简单的，但是只功能有限的客户端验证。这种类型的验证用100％的客户端javascript代码验证用户录入的值。因为验证逻辑是javascript代码，所以理解－－一些值javascript代码认为通过了，而服务器端的验证可能不通过－－是非常重要的。

Only the following validators are supported:

• required validator
• requiredstring validator
• stringlength validator
• regex validator
• email validator
• url validator
• int validator
• double validator

Error reporting

Because client side validation does not talk to the server, the theme (xhtml theme or css_xhtml theme) is responsible for properly manipulating the HTML DOM to display the error message inline. The JavaScript that is responsible for doing this logic is validation.js and can be found in each theme.

因为客户端的验证不与服务器端交互，主题（....）负责操纵HTML DOM来显示再现错误消息。负责这个逻辑的javascript是validation.js，能在各自的主题里找到。

Errors are reported using the default validation message, not the internationalized version that the server-side might be aware of. This is a known issue. You may want to try the AJAX Client Side Validation for messages that are fully internationalized. 用验证消息显示错误报告不能被国际化。你可能想用Ajax Client Side validation来是消息完全国际化。

Additional Validator Support

If you wish to add additional validator support beyond those listed, you may override the xhtml theme teamplte form-close-validate.ftl. This file contains the JavaScript that tries to validate each user-entered value from within the browswer. The css_xhtml theme extends the xhtml theme and therefore doesn't have it's own form-close-validate.ftl template.

Struts Action 2 依赖于一个XWork提供的validation框架，它能够在执行Action之前，遵循一些输入验证规则。本节进京提供最小的能够让你开始和关注于对XWork validator扩展来支持客户端的验证。

There is also an option for Client Side (Javascript and/or AJAX) based validation, please see Client Side Validation for more information.

Using Annotations

Annotations can be used as an alternative to XML for validation.

Annotations 方式的验证是一个相对于XML更好的选择。

Examples

1. Basic Validation
2. Client Validation
3. AJAX Validation
4. Using Field Validators
5. Using Non Field Validators
6. Using Visitor Field Validator

Bundled Validators

Note When using a Field Validator, Field Validator Syntax is ALWAYS preferable than using the Plain Validator Syntax as it facilitates grouping of field-validators according to fields. This is very handy especially if a field needs to have many field-validators which is almost always the case. Examples: validatortypes

1. required validator
2. requiredstring validator
3. int validator
4. date validator
5. expression validator
6. fieldexpression validator
7. email validator
8. url validator
9. visitor validator
10. conversion validator
11. stringlength validator
12. regex validator

Registering Validators

Validation rules are handled by validators, which must be registered with the ValidatorFactory (using the registerValidator method). The simplest way to do so is to add a file name validators.xml in the root of the classpath (/WEB-INF/classes) that declares all the validators you intend to use.

This list declares all the validators that comes with the framework.

<validators>
    <validator name="required" class="com.opensymphony.xwork2.validator.validators.RequiredFieldValidator"/>
    <validator name="requiredstring" class="com.opensymphony.xwork2.validator.validators.RequiredStringValidator"/>
    <validator name="int" class="com.opensymphony.xwork2.validator.validators.IntRangeFieldValidator"/>
    <validator name="double" class="com.opensymphony.xwork2.validator.validators.DoubleRangeFieldValidator"/>
    <validator name="date" class="com.opensymphony.xwork2.validator.validators.DateRangeFieldValidator"/>
    <validator name="expression" class="com.opensymphony.xwork2.validator.validators.ExpressionValidator"/>
    <validator name="fieldexpression" class="com.opensymphony.xwork2.validator.validators.FieldExpressionValidator"/>
    <validator name="email" class="com.opensymphony.xwork2.validator.validators.EmailValidator"/>
    <validator name="url" class="com.opensymphony.xwork2.validator.validators.URLValidator"/>
    <validator name="visitor" class="com.opensymphony.xwork2.validator.validators.VisitorFieldValidator"/>
    <validator name="conversion" class="com.opensymphony.xwork2.validator.validators.ConversionErrorFieldValidator"/>
    <validator name="stringlength" class="com.opensymphony.xwork2.validator.validators.StringLengthFieldValidator"/>
    <validator name="regex" class="com.opensymphony.xwork2.validator.validators.RegexFieldValidator"/>
</validators>

Note validators.xml if being defined should be available in the classpath. However this is not necessary, if no custom validator is needed. Predefined sets of validators will automatically be picked up when defined in com/opensymphony/xwork2/validator/validators/default.xml packaged in in the xwork jar file. See ValidatorFactory static block for details.

Warning If custom validator is being defined and a validators.xml is created and place in the classpath, do remember to copy all the other pre-defined validators that is needed into the validators.xml as if not they will not be registered. Once a validators.xml is detected in the classpath, the default one (com/opensymphony/xwork2/validator/validators/default.xml) will not be loaded. It is only loaded when a custom validators.xml cannot be found in the classpath. Be careful. 自己的validator.xml和default.xml是二选一。

Turning on Validation

The default validationWorkflowStack already includes this.
All that is required to enable validation for an Action is to put the ValidationInterceptor in the interceptor refs of the action (see xwork.xml) like so:

<interceptor name="validator" class="com.opensymphony.xwork2.validator.ValidationInterceptor"/>

Note: The default validationWorkflowStack already includes this.

You can turn off validation for a specific method by using the @SkipValidation annotation above your action method.

你可以关闭对某个方法的验证，使用@SkipValidation annotation在你的action 方法上面。

Validator Scopes

Field validators, as the name indicate, act on single fields accessible through an action. A validator, in contrast, is more generic and can do validations in the full action context, involving more than one field (or even no field at all) in validation rule. Most validations can be defined on per field basis. This should be preferred over non-field validation whereever possible, as field validator messages are bound to the related field and will be presented next to the corresponding input element in the respecting view.

Non-field validators only add action level messages. Non-field validators are mostly domain specific and therefore often custom implementations. The most important standard non-field validator provided by XWork is ExpressionValidator.

上面提到两种Validator， Field Validator和Non-field validator.

Notes

Non-field validators takes precedence over field validators regardless of the order they are defined in *-validation.xml. If a non-field validator is short-circuited, it will causes its non-field validator to not being executed. See validation framework documentation for more info.

Defining Validation Rules

Validation rules can be specified:

1. Per Action class: in a file named ActionName-validation.xml
2. Per Action alias: in a file named ActionName-alias-validation.xml
3. Inheritance hierarchy and interfaces implemented by Action class: XWork searches up the inheritance tree of the action to find default validations for parent classes of the Action and interfaces implemented

<!DOCTYPE validators PUBLIC "-//OpenSymphony Group//XWork Validator 1.0.2//EN"
       "http://www.opensymphony.com/xwork/xwork-validator-1.0.2.dtd">
<validators>
  <field name="bar">
      <field-validator type="required">
          <message>You must enter a value for bar.</message>
      </field-validator>
      <field-validator type="int">
          <param name="min">6</param>
          <param name="max">10</param>
          <message>bar must be between ${min} and ${max}, current value is ${bar}.</message>
      </field-validator>
  </field>
  <field name="bar2">
      <field-validator type="regex">
          <param name="regex">[0-9],[0-9]</param>
          <message>The value of bar2 must be in the format "x, y", where x and y are between 0 and 9</message>
     </field-validator>
  </field>
  <field name="date">
      <field-validator type="date">
          <param name="min">12/22/2002</param>
          <param name="max">12/25/2002</param>
          <message>The date must be between 12-22-2002 and 12-25-2002.</message>
      </field-validator>
  </field>
  <field name="foo">
      <field-validator type="int">
          <param name="min">0</param>
          <param name="max">100</param>
          <message key="foo.range">Could not find foo.range!</message>
      </field-validator>
  </field>
  <validator type="expression">
      <param name="expression">foo lt bar </param>
      <message>Foo must be greater than Bar. Foo = ${foo}, Bar = ${bar}.</message>
  </validator>
</validators>

Here we can see the configuration of validators for the SimpleAction class. Validators (and field-validators) must have a type attribute, which refers to a name of an Validator registered with the ValidatorFactory as above. Validator elements may also have <param> elements with name and value attributes to set arbitrary parameters into the Validator instance. See below for discussion of the message element.

Each Validator or Field-Validator element must define one message element inside the validator element body. The message element has 1 attributes, key which is not required. The body of the message tag is taken as the default message which should be added to the Action if the validator fails.Key gives a message key to look up in the Action's ResourceBundles using getText() from LocaleAware if the Action implements that interface (as ActionSupport does). This provides for Localized messages based on the Locale of the user making the request (or whatever Locale you've set into the LocaleAware Action). After either retrieving the message from the ResourceBundle using the Key value, or using the Default message, the current Validator is pushed onto the ValueStack, then the message is parsed for \${...} sections which are replaced with the evaluated value of the string between the \${ and }. This allows you to parameterize your messages with values from the Validator, the Action, or both.

If the validator fails, the validator is pushed onto the ValueStack and the message� either the default or the locale-specific one if the key attribute is defined (and such a message exists)� is parsed for ${...} sections which are replaced with the evaluated value of the string between the ${ and }. This allows you to parameterize your messages with values from the validator, the Action, or both.

NOTE:Since validation rules are in an XML file, you must make sure you escape special characters. For example, notice that in the expression validator rule above we use ">" instead of ">". Consult a resource on XML for the full list of characters that must be escaped. The most commonly used characters that must be escaped are: & (use &), > (user >), and < (use <).

Here is an example of a parameterized message:

This will pull the min and max parameters from the IntRangeFieldValidator and the value of bar from the Action.

bar must be between ${min} and ${max}, current value is ${bar}.

Validation rules can be specified:

1. Per Action class: in a file named ActionName-validation.xml
2. Per Action alias: in a file named ActionName-alias-validation.xml
3. Inheritance hierarchy and interfaces implemented by Action class: XWork searches up the inheritance tree of the action to find default validations for parent classes of the Action and interfaces implemented

Validator Flavour

The validators supplied by the Xwork distribution (and any validators you might write yourself) come in two different flavors:

1. Plain Validators / Non-Field validators
2. FieldValidators

Plain Validators (such as the ExpressionValidator) perform validation checks that are not inherently tied to a single specified field. When you declare a plain Validator in your -validation.xml file you do not associate a fieldname attribute with it. (You should avoid using plain Validators within the syntax described below.)

FieldValidators (such as the EmailValidator) are designed to perform validation checks on a single field. They require that you specify a fieldname attribute in your -validation.xml file. There are two different (but equivalent) XML syntaxes you can use to declare FieldValidators (see " vs. syntax" below).

There are two places where the differences between the two validator flavors are important to keep in mind:

1. when choosing the xml syntax used for declaring a validator (either or )
2. when using the short-circuit capability

NOTE:Note that you do not declare what "flavor" of validator you are using in your -validation.xml file, you just declare the name of the validator to use and WebWork will know whether it's a "plain Validator" or a "FieldValidator" by looking at the validation class that the validator's programmer chose to implement.

Non-Field Validator Vs Field-Validator

There are two ways you can define validators in your -validation.xml file:

1. <validator>
2. <field-validator>

Keep the following in mind when using either syntax:

Non-Field-Validator The <validator> element allows you to declare both types of validators (either a plain Validator a field-specific FieldValidator).

<!-- Declaring a plain Validator using the <validator> syntax: -->

   <validator type="expression>
         <param name="expression">foo gt bar</param>
         <message>foo must be great than bar.</message>
   </validator>

<!-- Declaring a field validator using the <validator> syntax; -->

   <validator type="required">
        <param name="fieldName">bar</param>
        <message>You must enter a value for bar.</message>
   </validator>

field-validator The <field-validator> elements are basically the same as the <validator> elements except that they inherit the fieldName attribute from the enclosing <field> element. FieldValidators defined within a <field-validator> element will have their fieldName automatically filled with the value of the parent <field> element's fieldName attribute. The reason for this structure is to conveniently group the validators for a particular field under one element, otherwise the fieldName attribute would have to be repeated, over and over, for each individual <validator>.

HINT: It is always better to defined field-validator inside a <field> tag instead of using a <validator> tag and supplying fieldName as its param as the xml code itself is clearer (grouping of field is clearer)

NOTE: Note that you should only use FieldValidators (not plain Validators) within a block. A plain Validator inside a <field> will not be allowed and would generate error when parsing the xml, as it is not allowed in the defined dtd (xwork-validator-1.0.2.dtd)

Declaring a FieldValidator using the <field-validator> syntax:

<field name="email_address">
  <field-validator type="required">
      <message>You cannot leave the email address field empty.</message>
  </field-validator>
  <field-validator type="email">
      <message>The email address you entered is not valid.</message>
  </field-validator>
</field>

The choice is yours. It's perfectly legal to only use elements without the elements and set the fieldName attribute for each of them. The following are effectively equal:

有多个选择未必是好事情:)

<field name="email_address">
  <field-validator type="required">
      <message>You cannot leave the email address field empty.</message>
  </field-validator>
  <field-validator type="email">
      <message>The email address you entered is not valid.</message>
  </field-validator>
</field>


<validator type="required">
  <param name="fieldName">email_address</param>
  <message>You cannot leave the email address field empty.</message>
</validator>
<validator type="email">
  <param name="fieldName">email_address</param>
  <message>The email address you entered is not valid.</message>
</validator>

Short-Circuiting Validator

Beginning with XWork 1.0.1 (bundled with WebWork 2.1), it is possible to short-circuit a stack of validators. Here is another sample config file containing validation rules from the Xwork test cases: Notice that some of the <field-validator> and <validator> elements have the short-circuit attribute set to true.

<!DOCTYPE validators PUBLIC 
        "-//OpenSymphony Group//XWork Validator 1.0.2//EN" 
        "http://www.opensymphony.com/xwork/xwork-validator-1.0.2.dtd">
<validators>
  <!-- Field Validators for email field -->
  <field name="email">
      <field-validator type="required" short-circuit="true">
          <message>You must enter a value for email.</message>
      </field-validator>
      <field-validator type="email" short-circuit="true">
          <message>Not a valid e-mail.</message>
      </field-validator>
  </field>
  <!-- Field Validators for email2 field -->
  <field name="email2">
     <field-validator type="required">
          <message>You must enter a value for email2.</message>
      </field-validator>
     <field-validator type="email">
          <message>Not a valid e-mail2.</message>
      </field-validator>
  </field>
  <!-- Plain Validator 1 -->
  <validator type="expression">
      <param name="expression">email.equals(email2)</param>
      <message>Email not the same as email2</message>
  </validator>
  <!-- Plain Validator 2 -->
  <validator type="expression" short-circuit="true">
      <param name="expression">email.startsWith('mark')</param>
      <message>Email does not start with mark</message>
  </validator>
</validators>

short-circuiting and Validator flavors

Plain validator takes precedence over field-validator. They get validated first in the order they are defined and then the field-validator in the order they are defined. Failure of a particular validator marked as short-circuit will prevent the evaluation of subsequent validators and an error (action error or field error depending on the type of validator) will be added to the ValidationContext of the object being validated.

Plain validator 优先级高于field-validator.他们定义的顺序中，先获取plain validator，后获取field-validator.一个标注为short-circuit的validator将避免对接下来validator的评估，并且添加一个error到ValidationContext中。

In the example above, the actual execution of validator would be as follows:

1. Plain Validator 1
2. Plain Validator 2
3. Field Validators for email field
4. Field Validators for email2 field

Since Field Validator 2 is short-circuited, if its validation failed, it will causes Field validators for email field and Field validators for email2 field to not be validated as well.

既然Field validator 2是短路的，如果验证失败，email 字段会验证，email2字段不会被验证。

Usefull Information: More complecated validation should probably be done in the validate() method on the action itself (assuming the action implements Validatable interface which ActionSupport already does).

有用信息：更复杂的验证应该在Action类里的validate方法中实现。（假设action实现了validatable接口，这个validatable接口被actionSupport实现）

A plain Validator (non FieldValidator) that gets short-circuited will completely break out of the validation stack no other validators will be evaluated and plain validator takes precedence over field validator meaning that they get evaluated in the order they are defined before field validator gets a chance to be evaludated again according to their order defined.

Short cuircuiting and validator flavours

A FieldValidator that gets short-circuited will only prevent other FieldValidators for the same field from being evaluated. Note that this "same field" behavior applies regardless of whether the or syntax was used to declare the validation rule. By way of example, given this -validation.xml file:

<validator type="required" short-circuit="true">
  <param name="fieldName">bar</param>
  <message>You must enter a value for bar.</message>
</validator>

<validator type="expression">
  <param name="expression">foo gt bar</param>
  <message>foo must be great than bar.</message>
</validator>

both validators will be run, even if the "required" validator short-circuits. "required" validators are FieldValidator's and will not short-circuit the plain ExpressionValidator because FieldValidators only short-circuit other checks on that same field. Since the plain Validator is not field specific, it is not short-circuited.

两个validator都在运行，尽管“required”validator短路。“required”validators 是FieldValidator 不能短路掉plain Expression Validator。因为FieldValidator仅仅能短路掉自己字段的validator。既然palin validator不是field规格的，所以它不会被短路掉。

How Validators of an Action are Found

As mentioned above, the framework will also search up the inheritance tree of the action to find default validations for interfaces and parent classes of the Action. If you are using the short-circuit attribute and relying on default validators higher up in the inheritance tree, make sure you don't accidentally short-circuit things higher in the tree that you really want!

正如上面提到的，框架将搜索action的继承树，来查为接口和action父类的默认验证。如果你用short-circuit attribute  并且依赖继承树上高层的默认验证，确保你不要意外地短路掉高层继承树里那些你真正想要的东西。

Resources

WebWork Validation

Resource Bundle Search Order

Resource bundles are searched in the following order:

1. ActionClass.properties
2. BaseClass.properties (all the way to Object.properties)
3. Interface.properties (every interface and sub-interface)
4. ModelDriven's model (if implements ModelDriven), for the model object repeat from 1
5. package.properties (of the directory where class is located and every parent directory all the way to the root directory)
6. search up the i18n message key hierarchy itself
7. global resource properties

For more, see the LocalizedTextUtil class.

Package hierarchy To clarify #5, while traversing the package hierarchy, WW will look for a file package.properties: com/   acme/     package.properties     actions/       package.properties       FooAction.java       FooAction.properties If FooAction.properties does not exist, com/acme/action/package.properties will be searched for, if not found com/acme/package.properties, if not found com/package.properties, etc.

Examples

There are several ways to access the message resources, including getText, the text tag, and the i18n tag.

Using getText

To display i18n text, use a call to getText in the property tag, or any other tag, such as the UI tags. (The getText technique is especially useful for labels of UI tags.)

<s:property value="getText('some.key')" />

Using the text tag

The text tag retrieves a message from the default resource bundle.

<-- Fourth Example -->
<s:text name="some.key" />

<-- Fifth Example -->
<s:text name="some.invalid.key" >
   The Default Message That Will Be Displayed
</s:text>

Using the I18n tag

The i18n tag pushes an arbitrary resource bundle on to the value stack. Other tags within the scope of the i18n tag can display messages from that resource bundle.

<s:i18n name="some.package.bundle" >
     <s:text name="some.key" />
</s:i18n>

Internationalizing SiteMesh decorators is possible, but there are quirks. See SiteMesh Plugin for more.

I18n Interceptor

Essentially, the i18n Interceptor pushes a locale into the ActionContext map upon every request. The framework components that support localization all utilize the ActionContext locale. See I18n Interceptor for details.

Global Resources (struts.custom.i18n.resources) in struts.properties

A global resource bundle could be specified programatically, as well as the locale.

Comparison with Struts 1

Struts 1 users should be familiar with the application.properties resource bundle, where you can put all the messages in the application that are going to be translated. Struts 2, though, splits the resource bundles per action or model class, and you may end up with duplicated messages in those resource bundles. A quick fix for that is to create a file called StrutsActionSupport.properties in org/apache/struts2 and put it on your classpath. This will only work well if all your actions subclass StrutsActionSupport.

The best way to explain wildcards is to show an example and walk through how it works. This example modifies a conventional mapping to use wildcards to match all pages that start with /edit:

<!-- Generic edit* mapping -->
<action
    name="/edit*"
    class="org.apache.struts.webapp.example.Edit{1}Action">
    <result
        name="failure"
        path="/mainMenu.jsp"/>
    <result
        path="/\{1\}.jsp"/>
</action>

The "*" in the path attribute allows the mapping to match the request URIs /editSubscription, editRegistration, or any other URI that starts with /edit, however /editSubscription/add would not be matched. The part of the URI matched by the wildcard will then be substituted into various attributes of the action mapping and its action results replacing {1}. For the rest of the request, the framework will see the action mapping and its action results containing the new values.

Mappings are matched against the request in the order they appear in the framework's configuration file. If more than one pattern matches the last one wins, so less specific patterns must appear before more specific ones. However, if the request URL can be matched against a path without any wildcards in it, no wildcard matching is performed and order is not important.

Wildcard patterns can contain one or more of the following special tokens:
* Matches zero or more characters excluding the slash ('/') character.
** Matches zero or more characters including the slash ('/') character.
\character The backslash character is used as an escape sequence. Thus * matches the character asterisk ('*'), and
matches the character backslash ('
').

In the action mapping and action results, the wildcard-matched values can be accessed with the token {N} where N is a number from 1 to 9 indicating which wildcard-matched value to substitute. The whole request URI can be accessed with the {0} token.

Also, the action mapping properties (set using the <set-property key="foo" value="bar"> syntax) will accept wildcard-matched strings in their value attribute.

Like the action mapping, the action result properties (set using the <set-property key="foo" value="bar"> syntax) will accept wildcard-matched strings in their value attribute.

See also Wildcard Method

The table lists the files that you can use to configure the framework for your application. Some configuration files can be reloaded dynamically. Dynamic reloading makes interactive development possible. See Reloading configuration for more.

Static Content

Common static content that is needed by the framework (JavaScript and CSS files, etc.) is served automatically by the FilterDispatcher filter. Any request starting with "/struts/" denotes that static content is required, and then mapping the value after "/struts/" to common packages in the framework and, optionally in the application's class path.

By default, the following packages are searched:

• org.apache.struts2.static
• template

Additional packages can be specified by providing a comma separated list to the configuration parameter named "packages" (configured in web.xml for the FilterDispatcher filter). When specifying additional static content, you should be careful not to expose sensitive configuration information (such as the password to a database).

Exception 映射是一个强大的功能，用来处理Action类抛出一个Exception。核心是一个Exceptio你在Action期间异常被自动抓取，并且映射到预先定义好的结果。这个声明方式的策略对framework相当有用，例如Hibernate和Acegi，他们抛出RuntimeException。

As with many other parts of the framework, an Interceptor is needed to activate the exception mapping functionality. Below is a snippet from struts-default.xml which has the exception mapping already activated.

与框架其他部分类似，一个Interceptor用来激活exception mappingfunctionality.下面是struts-default.xml的代码片断，在它里面exception映射已经被激活。

...
<interceptors>
    ...
    <interceptor name="exception" class="com.opensymphony.xwork.interceptor.ExceptionMappingInterceptor"/>
    ...
</interceptors>

<interceptor-stack name="defaultStack">
    <interceptor-ref name="exception"/>
    <interceptor-ref name="alias"/>
    <interceptor-ref name="servlet-config"/>
    <interceptor-ref name="prepare"/>
    <interceptor-ref name="i18n"/>
    <interceptor-ref name="chain"/>
    <interceptor-ref name="debugging"/>
    <interceptor-ref name="profiling"/>
    <interceptor-ref name="scoped-model-driven"/>
    <interceptor-ref name="model-driven"/>
    <interceptor-ref name="fileUpload"/>
    <interceptor-ref name="checkbox"/>
    <interceptor-ref name="static-params"/>
    <interceptor-ref name="params"/>
    <interceptor-ref name="conversionError"/>
    <interceptor-ref name="validation">
        <param name="excludeMethods">input,back,cancel,browse</param>
    </interceptor-ref>
    <interceptor-ref name="workflow">
        <param name="excludeMethods">input,back,cancel,browse</param>
    </interceptor-ref>
</interceptor-stack>
...

To use exception mapping, we simply need to map Exceptions to specific Results. The framework provides two ways to declare an exception mapping <exception-mapping/> - globally or for a specific action mapping. The exception mapping element takes two attributes, exception and result.

用Exception映射，我们简单地需要映射Exception到特定的结果。框架提供两种方式申明一个Exception映射<exception-mapping>-全局或特定的Action映射。Exception映射元素使用两种属性，exception和result。

When declaring an exception mapping, the Interceptor will find the closest class inheritance match between the Exception thrown and the Exception declared. The Interceptor will examine all declared mappings applicable to the action mapping, first local and then global mappings. If a match is found, the Result is processed, just as if it had been returned by the Action.

当声明一个exception映射，Interceptor将寻找最近的类继承关系来在Exception throw和Exception声明之间匹配。首先找local，然后找全局。如果找到匹配，结果将会被处理，就像它被Action处理返回一样。

This process follows the same rules as a Result returned from an Action. It first looks for the Result in the local action mapping, and if not found, it looks for a global Result.

Below is an example of global and local exception mappings.

<struts>
    <package name="default">
        ...
        <global-results>
            <result name="login" type="redirect">/Login.action</result>
            <result name="Exception">/Exception.jsp</result>
        </global-results>

        <global-exception-mappings>
            <exception-mapping exception="java.sql.SQLException" result="SQLException"/>
            <exception-mapping exception="java.lang.Exception" result="Exception"/>
        </global-exception-mappings>
        ...
        <action name="DataAccess" class="com.company.DataAccess">
            <exception-mapping exception="com.company.SecurityException" result="login"/>
            <result name="SQLException" type="chain">SQLExceptionAction</result>
            <result>/DataAccess.jsp</result>
        </action>
        ...
    </package>
</xwork>

In the example above, here is what happens based upon each Exception:

• A java.sql.SQLException will chain to the SQLExceptionAction (action mapping not shown)
• A com.company.SecurityException will redirect to Login.action
• Any other exception that extends java.lang.Exception will return the /Exception.jsp page

Exception Values on the ValueStack

By default, the ExceptionMappingInterceptor adds the following values to the Value Stack:

Action映射是框架的最基本的工作单元，本质上，action映射一个id到处理类，当一个请求匹配action名称，框架用映射来决定怎样处理这个请求。

Action Mappings

The action mapping can specify a set of result types, a set of exception handlers, and an interceptor stack. But, only the name attribute is required. The other attributes can also be provided at package scope.

Action映射能够描述N多的result type，n多的Exception handle，和一个interceptor栈，但是，只有name属性是需要的，其他属性也能够在package级别提供。

<action name="Logon" class="tutorial.Logon">
  <result type="redirect-action">Menu</result>
  <result name="input">/tutorial/Logon.jsp</result>
</action>

Action Names

In a web application, the name attribute is matched a part of the location requested by a browser (or other HTTP client). The framework will drop the host and application name and the extension, and match what's in the middle. So, a request for http://www.planetstruts.org/struts2-mailreader/Welcome.do will map to the Welcome action.

在一个Web应用中，name属性匹配来自浏览器的一系列本地请求。框架能够去掉主机和应用名，以及扩展名，来比配中间的那个名称，所以请求.....将映射Welcome Action。

Within an application, the link to an action is usually generated by a Struts Tag. The tag can specify the action by name, and the framework will render the default extension and anything else that is needed.

在一个应用里面，action的link通常有StrutsTag产生，tag能够用名字描述，框架将渲染默认扩展和其他它需要的任何东西。

<s:form action="Hello">
    <s:textfield label="Please enter your name" name="name"/>
    <s:submit/>
</s:form>

Action Names With Slashes If your action names have slashes in them (for example, <action name="admin/home" class="tutorial.Admin"/>) you need to specifically enable that functionality via the struts.xml file by specifying <constant name="struts.enable.SlashesInActionNames" value="true"/>. See JIRA Issue WW-1383 for discussion as there are side effects to setting this property to true.

Action Methods

The default entry method to the handler class is defined by the Action interface.

Handler类的默认入口方法被定义在Action 接口里。

public interface Action {
    public String execute() throws Exception;
}

Implementing the Action interface is optional. If Action is not implemented, the framework will use reflection to look for an execute method.

实现Action接口是可选的，如果没有实现，框架自动用反射技术来搜寻execute方法。

Sometimes, developers like to create more than one entry point to an Action. For example, in the case of of a data-access Action, a developer might want separate entry-points for create, retrieve, update, and delete. A different entry point can be specified by the method attribute.

有时，在Action里，开发者喜欢创建多于一个入口，例如，在data-access Action案例中，一个developer可能象区分Create，retrieve，update和delete等各种入口点。一个不同的入口点可以被教书在method属性中。

<action name="delete" class="example.CrudAction" method="delete">

If there is no execute method, and no other method, specified in the configuration, the framework will throw an exception.

Wildcard Method

Many times, a set of action mappings will share a common pattern. For example, all your edit actions might start with the word "edit", and call the edit method on the Action class. The delete actions might use the same pattern, but call the delete method instead.

很多时候，一系列的action因设将给一个通用模式共用，例如，你的所有edit action可能用“edit”开头，调用Action里的ecit方法。Delete Action可能用同样的方式，调用所有delete方法。

Rather than code a separate mapping for each action class that uses this pattern, you can write it once as a wildcard mapping.

不用为每个action以同样的模式写映射，你可以以疲惫符的方式只写一遍。

<action name="*Crud" class="example.Crud" method="{1}">

Here, a reference to "editCrud" will call the edit method on an instance of the Crud Action class. Likewise, a reference to "deleteCrud" will call the delete method instead.

Another common approach is to postfix the method name and set it off with an exclamation point (aka "bang"), underscore, or other special character.

另一个通用的方式是使用前缀

• "action=Crud_input"
• "action=Crud_delete"

To use a postfix wildcard, just move the asterisk and add an underscore.

<action name="Crud_*" class="example.Crud" method="{1}">

From the framework's perspective, a wildcard mapping creates a new "virtual" mapping with all the same attributes as a conventional, static mapping. As a result, you can use the expanded wildcard name as the name of validation, type conversion, and localization files, just as if it were an Action name (which it is!).

• Crud_input-validation.xml
• Crud_delete-conversion.xml

The postfix "!" notation is also available in WebWork 2, but it is implemented differently. To use the old implementation, set struts.enable.DynamicMethodInvocation=TRUE in the struts.properties file. To use wildcards instead (preferred), set struts.enable.DynamicMethodInvocation=FALSE.

ActionSupport Default

If the class attribute in an action mapping is left blank, the com.opensymphony.xwork.ActionSupport class is used as a default.

如果不写class属性，com.opensymphony.xwork.actionSupport类默认被使用。

<action name="Hello">
   // ...
</action>

The ActionSupport class has execute and input methods that return "success".

ActionSupport类有execute和input方法，并且都返回"success".

To specify a different class as the default Action, set the  package attribute.

设置package的attribute，可以指定其他类为默认Action

For more about using wildcards, see Wildcard Mappings.

Post-Back Default

A good practice is to link to actions rather than pages. Linking to actions encapsulates which server page renders, and ensures that an Action class can fire before a page renders.

Another common workflow stategy is to first render a page using an alternate method, like input and then have it submit back to the default execute method.

Using these two strategies together creates an opportunity to use a "post-back" form that doesn't specify an action. The form simply submits back to the action that created it.

<s:form>
    <s:textfield label="Please enter your name" name="name"/>
    <s:submit/>
</s:form>

Action Default

Usually, if an action is requested, and the framework can't map the request to an action name, the result will be the usual "404 - Page not found" error. But, if you would prefer that an ominbus action handle any unmatched requests, you can specify a default action. If no other action matches, the default action is used instead.

通常，如果一个action被请求，而fromework不能映射那个请求到一个action名字，结果通常使一个“404－Page not found ”错误。但是，如果你更热衷于一个能处理任何不匹配请求的万能action，你能描述一个默认的action。如果没有其他action匹配，默认的action被使用。

<package name="Hello" extends="action-default">

<default-action-ref name="UnderConstruction">

<action name="UnderConstruction">
  <result>/UnderConstruction.jsp</result>
</action>

There are no special requirements for the default action. Each package can have its own default action, but there should only be one default action per namespace.

One to a Namespace The default action features should be setup so that there is only one default action per namespace. If you have multiple packages declaring a default action with the same namespace, there is no guarantee which action will be the default.

Wildcard Default

Using wildcards is another approach to default actions. A wildcard action at the end of the configuration can be used to catch unmatched references.

<action name="*" >
  <result>/{1}.jsp</result>
</action>

When a new action is needed, just add a stub page.

Namespace属性细分了action配置到逻辑模块，每个都有自己的唯一的前缀，Namespace避免了action之间名称的冲突，每个namespace能有他自己的“menu”或“help”action，每个有自己的实现。当前缀在浏览器URI中出现时，标签能够用namespace感知，所以namespace前缀不需要嵌套在Form和Link里。

Namespaces are the equivalent of Struts Action 1 modules.

Default Namespace

The default namespace is "" - an empty string. The default namespace is used as a "catch-all" namespace. If an action configuration is not found in a specified namespace, the default namespace is also be searched. The local/global strategy allows an application to have global action configurations outside of the action element "extends" hierarchy.

The namespace prefix can be registered with Java declarative security, to ensure only authorized users can access the actions in a given namespace.

namespace前缀能够被Java申明安全注册，来确保只有授权用户访问给定命名空间的action。

Root Namespace

A root namespace ("/") is also supported. The root is the namespace when a request directly under the context path is received. As with other namespace, it will fall back to the default ("") namespace if a local action is not found.

Namespace Example

<package name="default">
    <action name="foo" class="mypackage.simpleAction>
        <result name="success" type="dispatcher">greeting.jsp</result>
    </action>
    <action name="bar" class="mypackage.simpleAction">
        <result name="success" type="dispatcher">bar1.jsp</result>
    </action>
</package>

<package name="mypackage1" namespace="/">
    <action name="moo" class="mypackage.simpleAction">
        <result name="success" type="dispatcher">moo.jsp</result>
    </action>
</package>

<package name="mypackage2" namespace="/barspace">
    <action name="bar" class="mypackage.simpleAction">
        <result name="success" type="dispatcher">bar2.jsp</result>
    </action>
</package>

How the Code Works

If a request for /barspace/bar.action is made, /barspace namespace is searched and if it is found the bar action is executed, else it will fall back to the default namespace. In the Namespace Example, the bar action does exists in the barspace namespace. The barspace.bar action will be executed, and if "success" is returned, the request will be forwarded to bar2.jsp.

Falling Back to Foo If a request is made to /barspace/foo.action, the namespace /barspace will be checked for action foo. If a local action is not found, the default namespace is checked. In the Namespace Example, there is no action foo in the namespace /barspace, therefore the default will be checked and /foo.action will be executed.

In the Namespace Example, if a request for moo.action is made, the root namespace ('/') is searched for a moo action; if a root action is not found, the default namespace is checked. In this case, the moo action does exist and will be selected. Upon success, the request would be forwarded to bar2.jsp.

Getting to the Root If a request is made for /foo.action, the root / namespace will be checked. If foo is found, the root action will be selected. Otherwise, the framework will check the default namespace. In the Namespace Example, foo action does not exist in the root namespace, so the default namespace is checked, and the default foo action is selected.

Namespaces are not a path! Namespace are not hierarchical like a file system path. There is one namespace level. For example if the URL /barspace/myspace/bar.action is requested, the framework will first look for namespace /barspace/myspace. If the action does not exist at /barspace/myspace, the search will immediately fall back to the default namespace "". The framework will not parse the namespace into a series of "folders". In the Namespace Example, the bar