Portlet MVC框架

缺省的处理器是一个非常简单的 Controller接口，它提供了两个方法：

这个框架包含了许多相同的控制器实现层次，比如， AbstractController， SimpleFormController等。它在数据绑定、命令对象使用、 模型处理和视图解析等方面和Servlet框架相同。

这个框架利用了一个特殊的桥Servlet ViewRendererServlet来使用Servlet框架里的视图显示 功能，这样，Portlet请求就被转化为Servlet请求，Portlet视图能够以通常的 Servlet底层代码来显示。这意味着，在Portlet里仍能使用当前所有的显示方法， 如JSP、Velocity等。

Spring Portlet MVC支持Web Bean，这些Bean的生命周期在于当前的HTTP请求 或HTTP Session(一般的和全局的)里，这不是 框架自身的特性，而是由使用的容器的 WebApplicationContext提供的。 Section 3.4.3, “其他作用域”详细地描述了这些Bean的作用范围。

	Tip
	??? Spring发布包带有完整的Spring Portlet MVC示例， 这个应用演示了所有Spring Portlet MVC框架的功能和特色。 你可以在samples/petportal目录下找到这个’petportal’应用。

当然，仅一个Controller 是不够的。为了提供基本的功能，所有的Spring Portlet Controller从 AbstractController继承，后者可以访问Spring 的ApplicationContext和控制缓存。

requireSession和 cacheSeconds属性是在 AbstractController的父类 PortletContentGenerator里声明的。为了完整性， 把它们列在这里。

在你自己的控制器里继承AbstractController时 (不推荐这样做，因为已经有许多现成的控制器，它们可能有你需要的功能)，仅需要覆盖 handleActionRequestInternal(ActionRequest, ActionResponse)方法或 handleRenderRequestInternal(RenderRequest, RenderResponse)方法(或两者都覆盖)，实现逻辑， 并返回 ModelAndView 对象 (如果是 handleRenderRequestInternal方法)。

handleActionRequestInternal(..)和 handleRenderRequestInternal(..)方法的缺省实现都会 抛出 PortletException，这和JSR-168规范API里的 GenericPortlet的行为是一致的。所以只要覆盖你的控制器 需要处理的方法。

下面简短的例子包含了一个类和一个在web应用context里的声明。

package samples;

import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;

import org.springframework.web.portlet.mvc.AbstractController;
import org.springframework.web.portlet.ModelAndView;

public class SampleController extends AbstractController {

    public ModelAndView handleRenderRequestInternal(
        RenderRequest request,
        RenderResponse response) throws Exception {

        ModelAndView mav = new ModelAndView("foo");
        mav.addObject("message", "Hello World!");
        return mav;
    }
}

<bean id="sampleController" class="samples.SampleController">
    <property name="cacheSeconds" value="120"/>
</bean>

为了使得一个简单的控制器工作，你只需要类似上面的类和在web应用context里的声明， 并且再设置一下处理器映射 (见 Section 16.5, “处理器映射”)。

尽管你能够继承AbstractController， Spring Portlet MVC提供了不少具体的实现，它们提供了许多在简单MVC应用里 常用的功能。

ParameterizableViewController基本上 和上面的例子类似，除了你能指定web应用context返回的视图的名字。 (不需要写死视图名)。

PortletModeNameViewController把当前的 Portlet的状态作为视图名，如果Portlet在View模式 (比如：PortletMode.VIEW)，那“View”就是视图名。

Spring Portlet MVC提供了和Spring Web MVC完全一致的 command controllers层次结构，提供方法来与数据对象交互 并且动态地把参数从PortletRequest 绑定到数据对象上。数据对象不需要实现框架相关的接口，因而你可以 直接操作这些持久化对象。下面让我们查看Command控制器提供的功能， 来了解它们的使用：

这些command控制器是非常强大的，为了有效地使用，需要对它们的原理有 细致的理解。在你开始使用它们前，务必仔细阅读它们层次结构的javadoc以及示例。

除了开发新的控制器，我们可以重用现有的portlet并且在 DispatcherPortlet 把请求映射指向它们。通过 PortletWrappingController，你能实例化一个 现有的Portlet来作 Controller，如下所示：

<bean id="wrappingController"
      class="org.springframework.web.portlet.mvc.PortletWrappingController">
    <property name="portletClass" value="sample.MyPortlet"/>
    <property name="portletName" value="my-portlet"/>
    <property name="initParameters">
        <value>
            config=/WEB-INF/my-portlet-config.xml
        </value>
    </property>
</bean>

这会很有价值，因为可以使用拦截器来对送向这些portlet的请求进行预处理和后处理。 而且也很方便，因为JSR-168没有提供对过滤机制的支持。比如，可以在一个MyFaces JSR Portlet外面加上Hibernate的 OpenSessionInViewInterceptor。

这是一个简单的处理器映射，它是基于当前的portlet模式(比如：’view’, ‘edit’, ‘help’). 如下：

<bean id="portletModeHandlerMapping"
      class="org.springframework.web.portlet.handler.PortletModeHandlerMapping">
    <property name="portletModeMap">
	    <map>
            <entry key="view" value-ref="viewHandler"/>
            <entry key="edit" value-ref="editHandler"/>
            <entry key="help" value-ref="helpHandler"/>
        </map>
    </property>
</bean>

如果需要在不改变portlet模式的情况下而在多个控制器间切换， 最简单的方法是把一个请求参数作为key来控制映射。

ParameterHandlerMapping使用一个特定的请求参数来控制映射。 这个参数的缺省名是'action'，可以通过'parameterName'属性来改变。

这个映射的bean设置会是这样：

<bean id="parameterHandlerMapping"
class="org.springframework.web.portlet.handler.ParameterHandlerMapping"/>
    <property name="parameterMap">
        <map>
            <entry key="add" value-ref="addItemHandler"/>
            <entry key="edit" value-ref="editItemHandler"/>
            <entry key="delete" value-ref="deleteItemHandler"/>
        </map>
    </property>
</bean>

最强大的内置处理映射 PortletModeParameterHandlerMapping结合了前两者的功能， 能够在每种portlet模式下进行不同的切换。

同样，参数的缺省名是”action”，但可以通过parameterName来修改。

缺省情况下，同样的参数值不能在两个不同的portlet模式下使用， 因为如果portlet自己改变了portlet模式，那么请求在映射中将不在有效。 把allowDupParameters属性设为true可以改变这种行为，但这种做法是不推荐的。

这个映射的bean设置会是这样：

<bean id="portletModeParameterHandlerMapping"
      class="org.springframework.web.portlet.handler.PortletModeParameterHandlerMapping">
    <property name="portletModeParameterMap">
        <map>
            <entry key="view"> 
				<!-- 'view' portlet模式 -->
                <map>
                    <entry key="add" value-ref="addItemHandler"/>
                    <entry key="edit" value-ref="editItemHandler"/>
                    <entry key="delete" value-ref="deleteItemHandler"/>
                </map>
            </entry>
            <entry key="edit"> 
				<!-- 'edit' portlet模式 -->
                <map>
                    <entry key="prefs" value-ref="prefsHandler"/>
                    <entry key="resetPrefs" value-ref="resetPrefsHandler"/>
                </map>
            </entry>
        </map>
    </property>
</bean>

这个映射可以在处理链中放在 PortletModeHandlerMapping前面，它可以为每个模式以及全局提供 缺省的映射。

Spring的处理器映射机制里有处理器拦截器的概念，在希望对于特定的请求 应用不同的功能时，它是非常有用。比如，检查用户名(principal)。同样，Spring Portlet MVC以Web MVC相同的方式实现了这些概念。

在处理器映射里的拦截器必须实现org.springframework.web.portlet 里的HandlerInterceptor接口。 和servlet的版本一样，这个接口定义了三个方法：一个在实际的处理器执行前被调用 (preHandle)，一个在执行后被调用(postHandle) 还有一个是在请求完全结束时被调用(afterCompletion)。 这三个方法应该可以为各种前置和后置处理提供足够的灵活。

preHandle返回一个布尔值。可以使用这个方法来中断或者继续执行链的处理。 当返回true时，处理执行链会继续，当返回false时， DispatcherPortlet 假设这个拦截器已经处理请求(比如，显示了合适的视图)并且不需要继续执行其它的 拦截器和在执行链中实际的处理器。

postHandle只会在RenderRequest 中被调用。ActionRequest和RenderRequest 都会调用preHandle和afterCompletion方法。 如果希望只在其中的一种请求中执行你的代码，务必在处理前检查请求的类型。

和servlet包类似，portlet包里也有一个HandlerInterceptor的具体实现 – HandlerInterceptorAdapter。这个类所有方法都是空的， 所以可以继承它，实现一个或两个你所需要的方法。

Portlet包也带一个名为ParameterMappingInterceptor 的具体拦截器，它可以和ParameterHandlerMapping 以及PortletModeParameterHandlerMapping一起使用。 这个拦截器可以把用来控制映射的参数从ActionRequest 带到随后的RenderRequest，这能够确保 RenderRequest映射到和ActionRequest相同的处理器。这些都是在 preHandle方法里完成的，所以在你的处理器里仍然可以改变决定 RenderRequest映射的参数值。

注意这个拦截器会调用ActionResponse 的setRenderParameter方法，这意味着在使用它的时候， 不能在处理器里调用sendRedirect。如果确实需要重定向， 可以手工地把映射参数向前传，或者另写一个拦截器来处理。

下面的例子介绍了 CommonsPortletMultipartResolver的使用：

<bean id="portletMultipartResolver"
    class="org.springframework.web.portlet.multipart.CommonsPortletMultipartResolver">

    <!-- 一个属性；以byte为单位的最大文件长度 -->
    <property name="maxUploadSize" value="100000"/>
</bean>

当然为了使multipart解析器能够工作，必须把合适的jar放到类路径里。对于 CommonsMultipartResolver来说，需要 commons-fileupload.jar。注意，必须使用至少1.1 版本的Commons FileUpload，因为以前的版本不支持JSR-168应用。

现在你已经看到如何设置Portlet MVC来处理multipart请求，接下来我们 讨论它的使用。当DispatcherPortlet检测到 multipart时，它会激活在context里声明的解析器，并把请求交给它。然后解析器 把当前的ActionRequest放到支持文件上传的MultipartActionRequest中。通过 MultipartActionRequest，可以得到 请求包含的multipart信息，并且在控制器里访问multipart文件。

注意，不能从RenderRequest接收到multipart 文件，而只能从ActionRequest里。

在 PortletMultipartResolver处理完后， 请求会继续被处理。你需要创建一个带有上传字段的表单来使用它(见下面)，Spring会 把文件绑定在你的表单上(支持对象)。为了让用户上传文件，必须创建一个 (JSP/HTML)的表单：

<h1>Please upload a file</h1>
<form method="post" action="<portlet:actionURL/>" enctype="multipart/form-data">
    <input type="file" name="file"/>
    <input type="submit"/>
</form>

如你所见，我们在bean的属性后面创建名为“File”的字段 用来容纳byte[]。加上了编码属性(enctype="multipart/form-data")， 让浏览器知道怎样来编码multipart字段(不要忘记！)。

和其它那些不会自动转化为字符串或原始类型的属性一样，为了把二进制数据放到对象 里，必须注册一个使用PortletRequestDataBinder 的自定义的编辑器。现成有好几个编辑器可以用来处理文件并把结果放到对象上。 StringMultipartFileEditor能够把文件转换成字符串 (使用用户定义的字符集)，ByteArrayMultipartFileEditor 能够把文件转换成字节数据。他们的功能和 CustomDateEditor一样。

所以，为了能够使用表单来上传文件，需要声明解析器，映射到处理这个bean的控制器的 映射以及控制器。

<bean id="portletMultipartResolver"
      class="org.springframework.web.portlet.multipart.CommonsPortletMultipartResolver"/>

<bean id="portletModeHandlerMapping"
      class="org.springframework.web.portlet.handler.PortletModeHandlerMapping">
    <property name="portletModeMap">
        <map>
            <entry key="view" value-ref="fileUploadController"/>
        </map>
    </property>
</bean>

<bean id="fileUploadController" class="examples.FileUploadController">
    <property name="commandClass" value="examples.FileUploadBean"/>
    <property name="formView" value="fileuploadform"/>
    <property name="successView" value="confirmation"/>
</bean>

接着，创建控制器以及实际容纳这个文件属性的类。

public class FileUploadController extends SimpleFormController {

    public void onSubmitAction(
        ActionRequest request,
        ActionResponse response,
        Object command,
        BindException errors)
        throws Exception {

        // 类型转换bean
        FileUploadBean bean = (FileUploadBean) command;

        // 是否有内容
        byte[] file = bean.getFile();
        if (file == null) {
            // 奇怪，用户什么都没有上传
        }

        // do something with the file here
    }

    protected void initBinder(
            PortletRequest request, PortletRequestDataBinder binder)
        throws Exception {
        // to actually be able to convert Multipart instance to byte[]
        // we have to register a custom editor
        binder.registerCustomEditor(byte[].class, new ByteArrayMultipartFileEditor());
        // 现在Spring知道如何来处理和转换multipart对象
    }
}

public class FileUploadBean {

    private byte[] file;

    public void setFile(byte[] file) {
        this.file = file;
    }

    public byte[] getFile() {
        return file;
    }
}

如你所见，FileUploadBean有一个类型是 byte[]的属性来容纳文件。控制器注册了一个自定义编辑器来 让Spring知道如何把解析器发现的multipart转换成指定的属性。在这个例子里， 没有对bean的byte[]属性进行任何操作，但实际上，你可以做任 何操作(把它存到数据库里，把它电邮出去，或其它)

下面是一个例子，文件直接绑定在的一个(表单支持)对象上的字符串类型属性上面：

public class FileUploadController extends SimpleFormController {

    public void onSubmitAction(
        ActionRequest request,
        ActionResponse response,
        Object command,
        BindException errors) throws Exception {

        // cast the bean
        FileUploadBean bean = (FileUploadBean) command;

        // let's see if there's content there
        String file = bean.getFile();
        if (file == null) {
            // hmm, that's strange, the user did not upload anything
        }

        // do something with the file here
    }

    protected void initBinder(
        PortletRequest request, PortletRequestDataBinder binder) throws Exception {

        // to actually be able to convert Multipart instance to a String
        // we have to register a custom editor
        binder.registerCustomEditor(String.class,
            new StringMultipartFileEditor());
        // now Spring knows how to handle multipart objects and convert
    }
}

public class FileUploadBean {

    private String file;

    public void setFile(String file) {
        this.file = file;
    }

    public String getFile() {
        return file;
    }
}

当然，最后的例子在上传文本文件时才有(逻辑上的)意义(在上传图像文件时， 它不会工作)。

第三个(也是最后一个)选项是，什么情况下需要直接绑定在(表单支持)对象的 MultipartFile属性上。在以下的情况， 不需要注册自定义的属性编辑器，因为不需要类型转换。

public class FileUploadController extends SimpleFormController {

    public void onSubmitAction(
        ActionRequest request,
        ActionResponse response,
        Object command,
        BindException errors) throws Exception {

        // cast the bean
        FileUploadBean bean = (FileUploadBean) command;

        // let's see if there's content there
        MultipartFile file = bean.getFile();
        if (file == null) {
            // hmm, that's strange, the user did not upload anything
        }

        // do something with the file here
    }
}

public class FileUploadBean {

    private MultipartFile file;

    public void setFile(MultipartFile file) {
        this.file = file;
    }

    public MultipartFile getFile() {
        return file;
    }
}