Stripes 快速入门指南[翻译]

说明:这是Stripes文档中的一篇叫Quick Start Guide的文章,看着顺眼,就翻译过来给大家看一下啦。
译者：lighter, 转载注明出于：http://lighter.iteye.com

Stripes 快速入门指南
tfenne于2006年八月27号作最后编辑

介绍:
这一篇指南编写的目的是为了让你尽可能地以最快的速度把Stripes运行起来.这里面包含了一些关于Stripes有开发Web应用程序时的配置说明,同时也让你快速地搭建第一个Stripes应用程序.

开发环境:
Stripes充分利用了Java1.5中一些非常重要的特征,比如Annotations,还有泛型。同样它也很依赖一些Servlet2.4/JSP2.0的特征。所以你需要一个1.5版本的JDK(现在适用于大多数的平台),和一个可以支持Servlet2.4的Servlet容器,例如免费的Tomcat5.x和Caucho最新版本的、非常出色的Resin(对非商业用户免费提供)
这里希望读者有一定的JSP的开发经验，而且能理解一些常用的EL表达式,虽然没有必要去了解过于深入.

Stripes配置：
Stripes被设计成尽可能地只需要最少的配置文件。为了让其运行，你只需要在web应用程序的web.xml上简单地配置Stripes过滤器和Stripes Dispatcher。一个非常标准的配置文件如下所示：
web.xml

<?xml version="1.0" encoding="UTF-8"?>  
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"  
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee   
         http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"   
         version="2.4">  
  
    <filter>  
        <display-name>Stripes Filter</display-name>  
        <filter-name>StripesFilter</filter-name>  
        <filter-class>net.sourceforge.stripes.controller.StripesFilter</filter-class>  
    </filter>  
       
    <filter-mapping>  
        <filter-name>StripesFilter</filter-name>  
        <url-pattern>*.jsp</url-pattern>  
        <dispatcher>REQUEST</dispatcher>  
    </filter-mapping>  
       
    <filter-mapping>  
        <filter-name>StripesFilter</filter-name>  
        <servlet-name>StripesDispatcher</servlet-name>  
        <dispatcher>REQUEST</dispatcher>  
    </filter-mapping>  
       
    <servlet>  
        <servlet-name>StripesDispatcher</servlet-name>  
        <servlet-class>net.sourceforge.stripes.controller.DispatcherServlet
       </servlet-class>  
        <load-on-startup>1</load-on-startup>  
    </servlet>  
       
    <servlet-mapping>  
        <servlet-name>StripesDispatcher</servlet-name>  
        <url-pattern>*.action</url-pattern>  
    </servlet-mapping>  
</web-app>  

    下一步你必须把stripes.jar放进classpath路径中去，通常放在/WEB-INF/lib目录下。在编译的时候必须依赖Stripes的开发包，在发布和运行的时候，同样也需要复制下面的lib文件放到你的classpath路径中去.

1、commons-logging.jar (1.1) - Apache Commons Logging通常被用来提供一个日志接口,
2、cos.jar - 是com.oreilly.servlets包,Jason Hunter的免费礼物，通常作为form提交、用来实现文件的上传功能。

    上面的lib文件已全部在Stripes的分发包里提供好，而且都经过了Stripes的测试。用越新版本的lib包或许也会工作正常,但这可能偏离我们想达到的目的。

     另外，可以看到Stripes的日志输出,这一点对我们非常有帮助。为了达到目的,你须提供一个给Log4J的工作环境，或者对其他的日志公用包供给一个适用环境。Log4J的jar文件,log4j-1.2.9.jar,是Stripes是一个分发包。一个Commons Logging样本和Log4J配置文件如下所示：
     commons-logging.properties

org.apache.commons.logging.Log=org.apache.commons.logging.impl.Log4JLogger  

    log4j.properties

### direct log messages to stdout ###   
log4j.appender.stdout=org.apache.log4j.ConsoleAppender   
log4j.appender.stdout.Target=System.out   
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout   
log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} %5p %c{1}:%L - %m%n     
### direct messages to file ###   
log4j.appender.file=org.apache.log4j.FileAppender   
log4j.appender.file.File=/tmp/stripes.log   
log4j.appender.file.layout=org.apache.log4j.PatternLayout   
log4j.appender.file.layout.ConversionPattern=%d{ABSOLUTE} %5p %c{1}:%L - %m%n   
### set log levels - for more verbose logging change 'info' to 'debug' ###   
log4j.rootLogger=INFO, stdout, file   
log4j.logger.net.sourceforge.stripes=DEBUG  

日志配置文件需要放在classpath路径中去，例如在/WEB-INF/classes

最后一件需要放置的是StripesResources.properties文件;你现在可以复制到/WEB-INF/classes中去。StripesResources.properties用来(默认)查找显示Stripes验证出错时提示的错误信息,同样这必须放在Classpath路径中。举一个例子的片段如下所如：
例如 StripesResources.properties

# Validation error messages used by Stripes' built in type converters   
converter.number.invalidNumber=The value ({1}) entered in field{0}must be a valid number   
converter.byte.outOfRange=The value ({1}) entered in field{0}was out of the range{2}to{3}   
converter.short.outOfRange=The value ({1}) entered in field {0}was out of the range{2}to{3}   
converter.integer.outOfRange=The value ({1}) entered in field {0}was out of the range{2}to{3}   
converter.float.outOfRange=The value ({1}) entered in field {0}was out of the range{2}to{3}   
converter.enum.notAnEnumeratedValue=The value "{1}" is not a valid value for field{0}   
converter.date.invalidDate=The value ({1}) entered in field {0 must be a valid date   
converter.email.invalidEmail=The value ({1})entered is not a valid email address   
...  

我的第一个Stripe:
   作为第一个应用程序,我们会建立一个简单的页面,用来计算两个数,把它们加起来,在后面的描述中,可能添加其他的一些操作。首先，建立一个JSP文件用来显示界面。如下所示是一个简单的JSP页面代码。在web应用程序的根目录中,把以下文件放进一个名叫"quickstart"的目录下。
    JSP文件:"index.jsp"

<%@ page contentType="text/html;charset=UTF-8" language="java" %>   
<%@ taglib prefix="stripes" uri="http://stripes.sourceforge.net/stripes.tld"%>   
  
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">   
<html>   
  <head><title>My First Stripe</title></head>   
  <body>   
    <h1>Stripes Calculator</h1>   
  
    Hi, I'm the Stripes Calculator. I can only do addition. Maybe, some day, a nice programmer   
    will come along and teach me how to do other things?   
  
    <stripes:form action="/examples/quickstart/Calculator.action" focus="">   
        <table>   
            <tr>   
                <td>Number 1:</td>   
                <td><stripes:text name="numberOne"/></td>   
            </tr>   
            <tr>   
                <td>Number 2:</td>   
                <td><stripes:text name="numberTwo"/></td>   
            </tr>   
            <tr>   
                <td colspan="2">   
                    <stripes:submit name="addition" value="Add"/>                       
                </td>   
            </tr>   
            <tr>   
                <td>Result:</td>   
                <td>${actionBean.result}</td>   
            </tr>   
        </table>   
    </stripes:form>   
  </body>   
</html>  

在上面的页面中,第一个感兴趣的事物在第二行(标签<%@ taglib ....导入在这一个页面所需要的Stripes Tag Library。然后，再往下面几行，有一行显示:

<stripes:form action="/examples/quickstart/Calculator.action" focus="">

展开讨论一下stripes:form标签。Stripes form标签在背地里地为我们做了一些事情、但在这里暂不深入讨论，它最终解析生成一组规则的html form标签。同时focus=""告诉Stripes自动地把焦点设置在第一个可见的域[field](或者在发生错误的时候指向第一个出错的域)

下一步，我们再看两个标签,如下所示

<stripes:text name="numberOne"/>

这一个标签等同于<input type="text"/>,但可以提供prepopulating,re-populating等功能,同时在验证出错的时候可以改变显示的信息。如果字段numberOne的名字与ActionBean里面的属性名相对应,ActionBean就会接受其请求。

为了替代<input type="submit">,我们可以用：

<stripes:submit name="addition" value="Add"/>

Stripes的submit标签有一个附加的实用功能就是在按钮上设置字符串的国际化显示,但我们可以做得更多，不止只有这一种需求,所以submit标签简单地运用了其值的属性。submit按钮的名字，addition，非常重要一点就是，当接受请求的时候会调用ActionBean里面的与之相绑定的方法。

最后，如果ActionBean里面存在result属性,这一条简单的EL表达式就把其结果打印出来

<td>${actionBean.result}</td>

我们现在准备演示一下页面!这时还不能提交页面, 因ActionBean还没有编写完毕(这不是简单地只用form标签做演示，我们现在也不会提交这一个表单)。

写完JSP文件后，看下面的Calculator例子的显示页面：
[img]http://lighter.iteye.com/upload/picture/pic/1629/ccd5db4b-b32c-4006-8562-e9b02a114586.png [/img]


ActionBean类: 
    ActionBean是一个接收请求提交数据的对象,处理用户的输入信息。它定义了表单form的属性,同时也进行逻辑处理。与Struts相比，ActionBean就像把ActionForm和Action结合在同一个类中。

    这里需要提出的一点就是不需要任何额外的配置就可以让Stripes知道关于ActionBean在应用程序里的执行情况,也不用把JSP页面与ActionBean绑定在一起。所有必要的信息都在ActionBean自身。现在就让我们看一下简单的接受计算请求AcionBean：

package net.sourceforge.stripes.examples.quickstart;   
  
import net.sourceforge.stripes.action.DefaultHandler;   
import net.sourceforge.stripes.action.Resolution;   
import net.sourceforge.stripes.action.ForwardResolution;   
import net.sourceforge.stripes.action.ActionBean;   
import net.sourceforge.stripes.action.ActionBeanContext;   
  
/**  
 * A very simple calculator action.  
 * @author Tim Fennell  
 */  
public class CalculatorActionBean implements ActionBean {   
    private ActionBeanContext context;   
    private double numberOne;   
    private double numberTwo;   
    private double result;   
  
    public ActionBeanContext getContext() { return context; }   
    public void setContext(ActionBeanContext context) { this.context = context; }   
  
    public double getNumberOne() { return numberOne; }   
    public void setNumberOne(double numberOne) { this.numberOne = numberOne; }   
  
    public double getNumberTwo() { return numberTwo; }   
    public void setNumberTwo(double numberTwo) { this.numberTwo = numberTwo; }   
  
    public double getResult() { return result; }   
    public void setResult(double result) { this.result = result; }   
  
    @DefaultHandler  
    public Resolution addition() {   
        result = getNumberOne() + getNumberTwo();   
        return new ForwardResolution("/quickstart/index.jsp");   
    }   
}  

    在这里最明显的疑问是，这一个类是怎样绑定到这个URL路径中的。Stripes默认的设置会检查ActionBeans，同时依赖于它们的类与包名决定其URL路径。Stripes可以改变类名到URL路径的映射:
    1、删除任何出现在包名路径中"web","www","stripes"和"action"之前的名称
     2、如果在包名路径出现有"Action"和"Bean"(或者"ActionBean")，则把其删除
     3、在包名的最后加上".action"

根据上面的规则，net.sourceforge.stripes.examples.quickstart.CalculatorActionBean包变成:
examples.quickstart.CalculatorActionBean
examples.quickstart.Calculator
/examples/quickstart/Calculator.action

从完整的类名中产生的URL路径与页面中的stripes:form标签特定的动作action相对应。这两种形式都与web应用程序根目录相关联的。你可以通过JavaDoc文档查找NameBasedActionResolver的相关资料,了解这是怎样处理的(和怎样改变其约定创建不同的URL路径)。

重新设置URL约定规则：
其URL路径是由Stripes默认产生的。重置ActionBean绑定设置的URL路径,你需要做的是在该类上用一个@UrlBinding元数据来注解说明。例如,我们可以这样写{{@UrlBinding("/qs/calc") public class CalculatorActionBean ... }}

下一步，该类声明的特征：

public class CalculatorActionBean implements ActionBean

ActionBean是一个接口，而不是一个基本类。因此，你创建的ActionBeans可以继承任何你喜欢的类。ActionBean接口定义两个方法,我们可以看到在该类中：

public ActionBeanContext getContext() { return context; }
public void setContext(ActionBeanContext context) { this.context = context; }

这些方法使得ActionBean有权访问使用ActionBeanContext,而ActionBeanContext提供了对HttpServletRequest和HttpServletResponse的访问使用－－当你需要它们的时候(希望不会太频繁)。同样，也可访问当前关于request请求的信息(例如,错误信息)。


那一些在ActionBean定义的关于属性的setter和getter方法，并不会令我们感兴趣,但在这应该指明一下的是他们是必须存在的(除非其properties被设置为public型的，但不鼓励这样做)。Stripes是通过标准的JavaBean的getter和setter方法来访问ActionBeans里的值的,如果他们不存在就会出现错误信息。在ActionBean的三个属性(和其成对getter/setter方法)与JSP页面的名称是相对应的。

看下一步，真正吸引目光的在：

@DefaultHandler
public Resolution addition() {
    result = numberOne + numberTwo;
    return new ForwardResolution("/quickstart/index.jsp");
}

因为这一个方法被设置为public型且返回一个Resoulution，Stripes 会默认地把它当作一个处理的方法。当用户点击提交其名字为"addition"的按钮或自定的图像按钮,同时就有请求发送到CalculatorActionBean,然后该方法就会被调用。就像上面的URL描述类似,可以用@HandlesEvent元数据来重置事件触发的时候该由哪一个方法来处理。

如果不清楚用户会点击其中的哪一个按钮(经常的情况是用户是直接敲回车键,而不是点击按钮),用@DefaultHandler元数据来告诉Stripes在默认的情况下该方法会被调用。

你可能已经意识到在ActionBean接口里面没有execute(),do()或者其他的泛型的方法。所有类似execute()方式可以执行的方法都是正规的推荐使用的java方法(public类型，非抽象方法，返回Resolution),或者其他已经被注解过可以让Stripes知道其存在的方法。Stripes把这一些方法当作处理的Hanlder方法，一旦它们在处理浏览器发送过来的事件,Handler方法通常就会返回一个Resolution,来用告诉Stripes下一步该怎样做(它们可能返回任何对象，但如果返回的不是一个 Resolution,Stripes就会忽略过去)。

我们上面写的方法是把两个数字相加求和，把结果储存在result属性当中，然后靠返回一个ForwardResolution跳转到进来时的JSP页面中去。这就是所做全部的事情。
现在,ActionBean类已经写好了，我们可以操作让两个数相加了:
[img]http://lighter.iteye.com/upload/picture/pic/1631/8ef27bea-401a-4eef-83ce-b79fca1c705d.png [/img]

简单的JSP代码，精悍的ActionBean类已经构成了一个可以正常运行的Stripes实例。但我们可以做更多的工作比如验证。


增加验证: 
像上面说的那样,我们乐意为页面增加一些验证。提示用户须输入两个有效的数字，然后把它们加起来,这是相当稳妥的。为了达到这一个目的，我们可以简单地在ActionBean的属性注释(annotate)声明。可以在任何一个属性的getter或setter方法上,指明其注释。这可能看起来有点混乱，所以还是建议你在ActionBeans统一地选择一种元素类型(在属性或getter方法或setter方法上)进行注释。例如(不要忘记导入Validate类):

增加必要的字段验证
@Validate(required=true) private double numberOne;
@Validate(required=true) private double numberTwo;

现在如果有用户忘记输入或者输入的值会产生一个或多个验证错误。为了把这一些错误的提示信息显示给用户查看，我们必须在JSP页面中增加一个标签。我们可以像下面这样做：
显示验证错误信息：

<stripes:form action="/quickstart/Calculator.action">
        <stripes:errors/>

假如存在验证错误信息,<stripes:errors/>标签会为form表单输出全部的验证错误信息。这是最常用的一个表达式,但我们在这里不会作深入的讨论。补充一点,表单的域显示的错误信息可以通过设置css的class属性使之高亮显示。所以假如我们增加如下的HTML的头部信息,当字段发生错误的时候就会把背景颜色设为黄色。

<style type="text/css">
    input.error { background-color: yellow; }
</style>

怎样验证其提供的值就是一个数字呢?事实上，Stripes已经为我们想到了。它知道numberOne和numberTwo两个属性是double类型的,同时通过验证来确定提供的数值是否适用于doubles类型。我们可以尝试着输入一组字符串,结果会显示如下:
在Action(Beans)验证:
[img]http://lighter.iteye.com/upload/picture/pic/1630/3e48d006-ccd8-4461-883d-6c1fd8793471.png [/img]


增加(譬如除法)其他操作:
上面就是我们所做的全部事情,但如果我们想要增加其他的一些操作呢?譬如除法?很好,这同样可以很简单地实现我们想要的。首先，我们可以快速地在JSP页面中增加：

<td colspan="2">
 <stripes:submit name="addition" value="Add"/>
 <stripes:submit name="division" value="Divide"/>
</td>

下一步，我们在ActionBean里新增一个处理方法:

public Resolution division() {
    result = numberOne / numberTwo;
    return new ForwardResolution("/quickstart/index.jsp"); 
}

当"division"事件触发的时候,我们自定义的一些验证应更早地执行,就像"addition"事件被触发一样。因此,当除法事件发生的时候,我们应尽可能地确保用户不能试着输入除数为0的数字来恶作剧系统。为了达到预期的目的,我们可以在division()方法之上编写验证代码,下面我们编写一个ValidationMethod的验证方法:

@ValidationMethod(on="division")
public void avoidDivideByZero(ValidationErrors errors) {
    if (this.numberTwo == 0) {
        errors.add("numberTwo", new SimpleError("Dividing by zero is not allowed."));
    }
}

被标识着@ ValidationMethod注释的方法，用来告知Stripes在执行处理操作的方法之前,须优先执行这一些验证方法。除非另外指定，Stripes对所有的事件触发会执行验证方法，在这一个例子，我们已经限制了该方法只能在division事件触发的时候运行。该方法传递一个引用给常常用来保存当前事件的验证错误信息的ValidationErrors对象。
这一个方法检查分母是否为零，如果是，创建一个SimpleError实例用来保存该错误信息。这可以正常地工作，也相当地快速,但也比较邪恶。一种更好的方法应该是使用LocalizableError,通过key来访问保存在StripesResources文件的信息。


资源：
这一个例子的源代码已经包含在Stripes的下载包中,同时,下载包中也包含了关于这个实例可以发布运行的WAR打包文件...
Bugzooky实例是一个更大一些的应用程序,里面演示了Stripes的一些更高级的特征。
Stripes的文档章节中包含了相关资料与实践指南。

后记：第一次翻译技术文章啊，其实前一星期就开始翻译这一篇文章啦，到现在才开现翻译好，只是自己懒了一些，所以翻译得比较慢,质量也不怎样，更没有什么润稿啦;大家大概地看就行啦，水平有限啊。
翻译这一篇Stripes快速入门指南的目的是让更多的人了解Stripes框架。我也是对Stripes框架了解不久，但比较感兴趣,就因它简单实用，少配置,容易测试。个人感觉，在java的前端开发方面，至少Stripes也很不错,从 Stripes身上看到RoR控制层，视图层的一些相近的理念,即使实用性方面可能比不上webwork,用户群方面更远远少于Struts的。