原文：http://www.onjava.com/pub/a/onjava/2005/07/13/jsfupload.html
作者：Andrei Cioroianu
翻译：di_feng_ro@hotmail.com

用户可以很方便使用浏览器上传文件，但是当前的Java Web标准（如servlets, JSP, and JSF）并没有提供任何上传的功能。幸好第三方框架，比如 Apache Commons File Upload, Apache MyFaces, and Oracle ADF Faces，提供了简单的API和客户标签，实现了这个功能。文章的前半部分将介绍上传组件是如何工作的，你将看到MyFaces and Commons File Upload 的部分源码（实际上，前者采用的是后者的代码）。了解这些源码的内在机制将使我们更有效的使用这些框架，并且可以根据需要修改他们！在文章的后半部分，介绍了一个让用户通过浏览器上传文件的例子。

基于WEB的文件上传

“上传”这个词的使用比较广泛。一个web管理员在他的主页发布了一个文件，他可以说他上传了一个文件；当一个网络工程师创建了一个HTML form和一些脚本使普通用户可以通过浏览器上传文件，他说他实现了上传的功能。

这两种方式之中有些共同的地方，因为一个web管理员可以通过一个基于web的接口来发布文件（页面，图像，脚本等等）。那些免费提供个人主页的公司，比如yahoo，实现了基于web的文件上传功能，因为客户需要上传页面。这样任何人只要接入网络，就可以通过浏览器发布他的个人站点。但是，还有许多更好的方式让你发布你的网页内容，比如FTP或secure FTP。在这种情况下，你就需要一个对应的应用程序，比如FTP客户端，而不是浏览器来发布你的网站。


这篇文章将从网络开发者的角度来讨论文件上传。一个基于web的mail应用程序，比如yahoo mail,实现了上传功能，这样用户才能发送信息和附件。另一个好的例子是一个job网站必须让你能够发送简历给招聘人员。在你的应用程序中，你可以对上传的文件作任何你想做的事情，比如把这些文件的内容储存到数据库中或者把他们当作附件发送出去。这篇文章的例子计算了上传文件的hash值。现在，让我们看看如何在一个web应用程序中是实现上传功能。


一个html表单包含一个或多个<input type="file"> 元素，这个元素将在页面上生成文件输入框，用户可以在这里填写文件路径。用户点击输入字段后面的浏览(browse)按钮后，会弹出一个对话框让用户选择路径：

当用户点击表单的Sumbit按钮，浏览器对表单数据进行编码，其中包括文件的内容，名字，路径以及其他的表单参数。然后，浏览器把编码过的数据传递给web服务器，服务器再把这些数据传递给相应的页面，比如<form>标签里的action属性值。如果是java网络应用程序，action属性值可能是个servlet或者是个jsp页面。

因为默认的表单编码和get方法不适合上传文件，所以一个包含文件输入框的表单必须定义编码为multipart/form-data ，并且在<form>标签里使用POST方法：

<form enctype="multipart/form-data" method="POST" action="...">
    ...
    <input type="file" name="...">
    ...
</form>

但是，事情并不象看起来那么简单，实现了servlet and JSP 标准的应用服务器并没有被要求处理 multipart/form-data编码。所以你需要一个解析器来处理请求的输入流,比如Apache Commons File Upload组件，它是个java包，能从已编码的数据中读取出上传文件的内容。这个包的API很灵活，允许你把小文件存在内存里而大文件储存在磁盘上一个临时文件夹里。你不但可以定义大文件和小文件的界限，还可以定义上传文件所占空间的最大值。

org.apache.commons.fileupload里有个DiskFileUpload类，它的parseRequest()函数获得一个HttpServletRequest，返回一个List，其中包含了org.apache.commons.fileupload.FileItem的实例。servlet请求的getInputStream()函数返回一个数据流，已编译的表单数据就是从这里读取出来的。FileItem很容易让人误解，因为这个接口的实例不仅包括上传文件,还有其他的请求参数。

Commons File Upload 包提供的API可以解析数据，但是servlet请求的getParameter()函数和getParameterValues()函数却不能工作。因为这两个函数被运行在常用的输入框, 复选框, 单选按钮, 和下拉列表后面的标准JSF组件调用，所以这个问题需要解决。Servlets API提供的两个功能(filters和request wrappers) 可以解决这个问题。下面的章节描述了在没有破坏原有JSF结构的情况下，Apache MyFaces 如何实现了一个filter功能，从而添加了更多需要的支持。另外，MyFaces提供的API可以创建javaBean，和生成<input type="file">元素的JSF组件相对应。

配置 JSF 和MyFaces Extensions

目前最主要的实现JSF规范的框架有JSF Reference Implementation (RI)以及Apache提供的MyFaces。虽然还有别的，但这两个是最流行的。很多开发者更倾向于JSF RI，因为这是来自于sun的官方产品。但MyFaces有一些有趣的扩展的功能，比如上传文件。如果你喜欢，你可以同时使用MyFaces的扩展功能和JSF RI。你只需要把myfaces-extensions.jar和JSF RI的jar文件以及 commons-fileupload-1.0.jar 放在web应用程序的WEB-INF/lib 目录下即可。下面是你需要的jar文件：

JSF 1.1 RI	jsf-api.jar jsf-impl.jar
JSTL 1.1 RI	jstl.jar standard.jar
MyFaces Extensions	myfaces-extensions.jar
Apache Commons (used by JSF and MyFaces Extensions)	commons-collections.jar commons-digester.jar commons-beanutils.jar commons-logging.jar commons-fileupload-1.0.jar

org.apache.myfaces.component.html.util包的MultipartRequestWrapper类创建了MyFaces和Commons File Upload连接的桥梁。这个类继承了HttpServletRequestWrapper，重写了getParameterMap(), getParameterNames(), getParameter(), 和getParameterValues() 函数，所以他们能正确处理multipart/form-data 编码数据。另外，MultipartRequestWrapper提供的两个函数，getFileItem() 和getFileItems(),使你可以通过org.apache.commons.fileupload.FileItem 接口访问上传文件。

MyFaces的 ExtensionsFilter 类在org.apache.myfaces.component.html.util 包里，当它发现multipart/form-data编码的时候，它会创建了 MultipartRequestWrapper 的实例。所以你不需理会他是如何解析表单数据的，但是知道它是如何开始解析对你想要修改上传文件的处理方式是有用的。在一个传统的应用程序中，你只需要在web.xml描述符中配置好ExtensionsFilter ，它就能在JSF的FacesServlet之前截获HTTP请求：

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE web-app PUBLIC
    "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>

    <context-param>
        <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
        <param-value>client</param-value>
    </context-param>

    <servlet>
        <servlet-name>FacesServlet</servlet-name>
        <servlet-class>
            javax.faces.webapp.FacesServlet
        </servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>FacesServlet</servlet-name>
        <url-pattern>/faces/*</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>FacesServlet</servlet-name>
        <url-pattern>*.faces</url-pattern>
    </servlet-mapping>

    <filter>
        <filter-name>ExtensionsFilter</filter-name>
        <filter-class>
            org.apache.myfaces.component.html.util.ExtensionsFilter
        </filter-class>
        <init-param>
            <param-name>uploadMaxFileSize</param-name>
            <param-value>10m</param-value>
        </init-param>
        <init-param>
            <param-name>uploadThresholdSize</param-name>
            <param-value>100k</param-value>
        </init-param>
    </filter>

    <filter-mapping>
        <filter-name>ExtensionsFilter</filter-name>
        <servlet-name>FacesServlet</servlet-name>
    </filter-mapping>

    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
    </welcome-file-list>

</web-app>

 前面例子中，filter的两个参数告诉MyFaces把小于100K的文件保存在内存中，而对于大于10M的文件则忽略。大小在uploadThresholdSize值和uploadMaxFileSize值之间的文件则作为临时文件存在硬盘上。如果你上传很大的文件，当前的MyFaces版本会忽略所有的表单数据，就好象你提交了一个空表单。如果你想把上传失败的消息告诉用户，你就得修改MyFaces中MultipartRequestWrapper类的源码。让我们找到捕获SizeLimitExceededException的地方，并使用FacesContext.getCurrentInstance().addMessage()来警告用户。

正如前面所说的，MyFaces Extensions 里有个能在JSF页面里使用的上传组件。下面的章节将说明如何使用。

为了在web页面里使用JSF和MyFaces，你必须使用<%@taglib%>指令声明他们的标签库。

<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
<%@ taglib uri="http://myfaces.apache.org/extensions" prefix="x"%>

JSF的<h:form>标签没有method属性，因为它只支持post方法，但他有enctype属性，当你想上传文件时，你可以用它来定义表单数据的编码类型：

<f:view>

    <h:form id="MyForm" enctype="multipart/form-data" >
        ...
        <x:inputFileUpload id="myFileId"
            value="#{myBean.myFile}"
            storage="file"
            required="true"/>
        ...
    </h:form>

</f:view>

 

MyFaces的<x:inputFileUpload> 标签让你定义UI组件的属性，它将在前台生成<input type="file"> 元素。包org.apache.myfaces.custom.fileupload 包含了控制UI结构的HtmlInputFileUpload类，它的renderer (HtmlFileUploadRenderer), 处理用户标签的类 (HtmlInputFileUploadTag),  UploadedFile 接口, 以及别的帮助类。 HtmlInputFileUpload 类 继承了标准的JSF HtmlInputText 组件 ，重写了几个函数。HtmlFileUploadRenderer负责创建 HTML 标签以及从MultipartRequestWrapper类返回FileItem(前面提过)。

MyFaces提供了自己的UploadedFile接口读取上传文件的内容，文件类型，名字以及大小，而不是让你直接访问由Commons File Upload组件创建的FileItem实例。你的JSF表单背后的bean必须有一个UploadedFile属性。下面的例子中，UI组件的值通过JSF表达式(#{myBean.myFile})绑定到一个bean属性中。JSF框架将取得HtmlInputFileUpload 组件的值，这是个UploadedFile实例，并把它传送到背后bean的属性中。

import org.apache.myfaces.custom.fileupload.UploadedFile;
...
public class MyBean {
    private UploadedFile myFile;

    public UploadedFile getMyFile() {
        return myFile;
    }

    public void setMyFile(UploadedFile myFile) {
        this.myFile = myFile;
    }
    ...
}

我们应该知道MyFaces有两个实现 UploadedFile接口的类:UploadedFileDefaultMemoryImpl和UploadedFileDefaultFileImpl。当<x:inputFileUpload>标签没有storage属性或这个属性值为memory时，使用前一个类。当storage属性值为file时用后一个。

类UploadedFileDefaultMemoryImp从一个FileItem实例中取得上传文件的内容以及它的名字，大小，文件类型，并把这些信息储存在一个私有属性里。所以即使Commons File Upload 把文件存在磁盘上，这个实现UploadedFile接口的类仍把上传文件的内容储存在内存里，浪费系统资源。

类UploadedFileDefaultFileImpl使用一个临时属性来保存一个对FileItem实例的引用。只有当getInputStream()被调用时，才通过这个引用读取上传文件的内容。这个类节省了内存空间，但它是序列化的，当其被反序列化后，你无法取得文件的内容。所以，上传文件表单背后的bean无法保存在session scope中，因为应用服务器在应用程序重起或服务器关闭时要对session bean序列化。(译者注：这一段不太明白，希望大家给予指导）。

如果你想让它们高效的工作，可以把背后的bean保存在request scope并且在<x:inputFileUpload>中定义 storage="file"节省内存资源。你可以在UploadedFileDefaultFileImpl添加一个序列化上传文件的函数writeObject()，这样可以解决序列化的问题。为了使这个类更有效率，相应的readObject() 应该创建临时文件而不是从内存中读取它的内容。

 应用程序例子

前面的章节中，我们描述了MyFaces如何使用Commons File Upload支持上传文件功能。现在让我们来看一个使用这个功能的例子。一个JSF表单(MyForm.jsp）让用户选择文件以及message-digest algorithm，背后的bean(MyBean.java)计算要在别的页面(MyResult.jsp)显示的hash值。这些页面以及背后的bean和一个JSF配置文件(faces-config.xml)相关联。

MyForm.jsp页面

这里的JSF表单使用MyFaces的<x:inputFileUpload>标签，以及一些标准JSF标签,这些JSF标签将在页面生成labels,messages,以及一个包含message-digest algorithms的下拉列表，还有一个使用了JSF表达式的命令按钮，这个按钮用来定义处理上传文件的action方法。

<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
<%@ taglib uri="http://myfaces.apache.org/extensions" prefix="x"%>

<f:view>

<h:form id="MyForm" enctype="multipart/form-data" >

    <h:messages globalOnly="true" styleClass="message"/>

    <h:panelGrid columns="3" border="0" cellspacing="5">

        <h:outputLabel for="myFileId" value="File: "/>
        <x:inputFileUpload id="myFileId"
            value="#{myBean.myFile}"
            storage="file"
            required="true"/>
        <h:message for="myFileId"/>

        <h:outputLabel for="myParamId" value="Param: "/>
        <h:selectOneMenu id="myParamId"
                value="#{myBean.myParam}"
                required="true">
            <f:selectItem itemLabel="" itemValue=""/>
            <f:selectItem itemLabel="MD5" itemValue="MD5"/>
            <f:selectItem itemLabel="SHA-1" itemValue="SHA-1"/>
            <f:selectItem itemLabel="SHA-256" itemValue="SHA-256"/>
            <f:selectItem itemLabel="SHA-384" itemValue="SHA-384"/>
            <f:selectItem itemLabel="SHA-512" itemValue="SHA-512"/>
        </h:selectOneMenu>
        <h:message for="myParamId"/>

        <h:outputText value=" "/>
        <h:commandButton value="Submit"
            action="#{myBean.processMyFile}"/>
        <h:outputText value=" "/>

    </h:panelGrid>

</h:form>

</f:view>

processMyFile() 函数通过一个输入流取得上传文件的内容，这个输入流是通过调用myFile.getInputStream()函数返回的。hash值是使用java.security.MessageDigest计算出来的，然后这个值被转换成一个string,用myResult属性储存。
package com.devsphere.articles.jsfupload;
...
import javax.faces.application.FacesMessage;
import javax.faces.context.FacesContext;

import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

import java.io.*;

public class MyBean {
    ...
    public String processMyFile() {
        try {
            MessageDigest md
                = MessageDigest.getInstance(myParam);
            InputStream in = new BufferedInputStream(
                myFile.getInputStream());
            try {
                byte[] buffer = new byte[64 * 1024];
                int count;
                while ((count = in.read(buffer)) > 0)
                    md.update(buffer, 0, count);
            } finally {
                in.close();
            }
            byte hash[] = md.digest();
            StringBuffer buf = new StringBuffer();
            for (int i = 0; i < hash.length; i++) {
                int b = hash[i] & 0xFF;
                int c = (b >> 4) & 0xF;
                c = c < 10 ? '0' + c : 'A' + c - 10;
                buf.append((char) c);
                c = b & 0xF;
                c = c < 10 ? '0' + c : 'A' + c - 10;
                buf.append((char) c);
            }
            myResult = buf.toString();
            return "OK";
        } catch (Exception x) {
            FacesMessage message = new FacesMessage(
                FacesMessage.SEVERITY_FATAL,
                x.getClass().getName(), x.getMessage());
            FacesContext.getCurrentInstance().addMessage(
                null, message);
            return null;
        }
    }

}

 

faces-config.xml 文件

这个JSF配置文件定义了背后的bean在request scope以及一个导航规则：

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE faces-config PUBLIC
    "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.1//EN"
    "http://java.sun.com/dtd/web-facesconfig_1_1.dtd">

<faces-config>

    <managed-bean>
        <managed-bean-name>myBean</managed-bean-name>
        <managed-bean-class>
            com.devsphere.articles.jsfupload.MyBean
        </managed-bean-class>
        <managed-bean-scope>request</managed-bean-scope>
    </managed-bean>

    <navigation-rule>
        <from-view-id>/MyForm.jsp</from-view-id>
        <navigation-case>
            <from-outcome>OK</from-outcome>
            <to-view-id>/MyResult.jsp</to-view-id>
        </navigation-case>
    </navigation-rule>

</faces-config>

 MyResult.jsp 页面

这个web页面显示了关于上传文件和hash值的一些信息：

<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>

<f:view>

    <h:panelGrid columns="2" border="0" cellspacing="5">

        <h:outputText value="FileName:"/>
        <h:outputText value="#{myBean.myFile.name}"/>

        <h:outputText value="FileSize:"/>
        <h:outputText value="#{myBean.myFile.size}"/>

        <h:outputText value="Param:"/>
        <h:outputText value="#{myBean.myParam}"/>

        <h:outputText value="Result:"/>
        <h:outputText value="#{myBean.myResult}"/>

    </h:panelGrid>

</f:view>

事实上，显示的文件名字可能是在客户端文件系统的完整路径，正如在下面的浏览器中看到的：

总结

在很多情况下，用户需要通过他们的浏览器上传文件，但在服务器方面并没有处理这些文件的良好方式。把小文件保存在内存里是可以接受的，但把大文件保存在临时文件里会让情况复杂。MyFaces让你选择的解决方法对你的应用程序很有帮助，但这个框架有几个小问题：当你已不再需要某个临时文件时，它却不让你删除；文件名有时候是文件路径；并且用户上传过大文件时它没有任何警告信息。但这些bug是可以修复的，因为源码可以修改的。这篇文章已经说明哪些地方的代码可以提高。不过，你可能会发现，对于很多应用程序来说，原有的MyFaces就已经足够了。这篇文章的例子是在JSF 1.1.01, MyFaces 1.0.9,和 Commons File Upload 1.0下测试的。