Commons FileUpload

转载自（https://my.oschina.net/u/2000201/blog/486744）

1    概述

Commons FileUpdate包很容易为你的Servlet和web应用程序添加健壮的、高性能的文件上传功能。
FileUpload解析遵循RFC 1876（在HTML中基于表单的文件上传）HTTP请求。即，如果一个HTTP请求使用POST方法提交，并
且使用“multipart/form-data”的内容类型，然后FileUpload解析请求，使结果易于调用者使用。
从1.3开始，FileUpload处理RFC 2047编码头值。

2    用户指南

2.1    使用FileUpload

FileUpload能使用大量不同的方式，依赖于你的应用程序的需求。在简单的情况下，你将调用简单的方法解析Servlet请求，
然后处理item列表作为它们应用到你的应用程序。在天平的另一端，你可能决定自定义FileUpload充分的控制单个item存储
的方式；例如，你可能决定将流的内容写入数据库。
这里，我们将描述FileUpload的基本原则，并阐述一些更简单的——并且更通用的——使用模式。
FileUpload依赖于Commons IO。

2.2    工作原理

一个文件上传请求包含一个根据RFC 1867（在HTML中基于表单的文件上传）编码的有序item列表。FileUpload能解析这么一个请求，并提供给你的应用程序单独的上传item列表。每个item实现FileItem接口，不管它底层实现。
本文描述Commons FileUpload类库的传统API。传统API是便利方式。然而，对于最终性能，你可能喜欢快速的流API。
每个文件item有你的应用程序可能感兴趣的许多属性。例如，每个item有一个名字和内容类型，并提供一个InputStream访问
它的数据。换句话说，你可能需要处理不同的item，依赖于是否item是常规表单——即，数据来自原始文本框或类似于HTML字段——或上传文件。FileItem接口提供方法做出这一决定，并以最适当的方式访问数据。
FileUpload使用FileItemFactory创建新文件item。这给FileUpload更大的灵活性。工厂最终控制每个item如何创建。工厂实
现当前过渡FileUpload存储item的数据在内存或磁盘，依赖于item的大小（例如，数据的字节）。然而，该行为能自定义适合你的应用程序。

2.3    Servlet和Portlet

从1.1开始，FileUpload支持Servlet和Portlet环境的文件上传请求。在两种环境中的使用几乎相同，因此，本文只讲述
Servlet环境。
如果你构建一个Portlet应用程序，以下两点不同你应该阅读API文档：

ServletFileUpload类->PortletFileUpload类
HttpServletRequest类->ActionRequest类

2.4    解析请求

你处理上传item之前，当然，你需要解析请求。确保，请求是一个简单的真实文件上传请求，但FileUpload使其变得简单，
通过提供一个静态方法做到这一点。

// 检查，我们有一个文件上传请求
boolean isMultipart = ServletFileUpload.isMultipartContent(request);

现在，我们准备解析请求为item。

2.5    最简单的情况

以下是最简单的使用情景：

• 上传item应该保留在内容中，只要它相当小。

• 大型item应该写入磁盘上的临时文件。

• 非常大的上传请求应该不被允许。

• 内置默认的保存在内存中的一个item的最大大小，一个上传请求的最大大小，和可接受的临时文件位置。

在这种情况下，处理请求不应该更简单：

// 创建基于磁盘文件item的工厂
DiskFileItemFactory factory = new DiskFileItemFactory();

// 配置一个仓库（确保一个安全的临时位置被使用）
ServletContext servletContext = this.getServletConfig().getServletContext();
File repository = (File) servletContext.getAttribute("javax.servlet.context.tempdir");
factory.setRepository(repository);

// 创建一个新的文件上传处理器
ServletFileUpload upload = new ServletFileUpload(factory);

// 解析请求
List<FileItem> items = upload.parseRequest(request);

这是我们的所有需要。
解析的结果是文件item List，每个FileItem接口的实现。

2.6    练习更多控制

如果你使用的情景是上面描述的最简单的情况，但是你需要一点更多的控制，你能易于定制上传处理器或文件item工厂的行为。
以下例子显示各种配置选项：

// 创建基于磁盘文件item的工厂
DiskFileItemFactory factory = new DiskFileItemFactory();

// 设置工厂约束
factory.setSizeThreshold(yourMaxMemorySize);
factory.setRepository(yourTempDirectory);

// 创建一个新的文件上传处理器
ServletFileUpload upload = new ServletFileUpload(factory);

// 设置全部请求大小约束
upload.setSizeMax(yourMaxRequestSize);

// 解析请求
List<FileItem> items = upload.parseRequest(request);

当然，每个配置方法独立于其它方法，但如果你想要同时配置工厂，你能使用构造函数，像这样：

// 创建一个基于磁盘的文item工厂
DiskFileItemFactory factory = new DiskFileItemFactory(yourMaxMemorySize, yourTempDirectory);

你应该需要在请求解析上更高级的控制，例如，在其它地方存储item——例如，在数据库中。

2.7    处理上传item

一旦解析完成，你将有一个需要处理的文件item List。在大多数情况下，你将想要处理不同于普通表单字段的文件上传，
因此你可以像这样处理：

// 处理上传item
Iterator<FileItem> iter = items.iterator();
while (iter.hasNext()) {
    FileItem item = iter.next();

if (item.isFormField()) {
        processFormField(item);
    } else {
        processUploadedFile(item);
    }
}

对于表单字段，你将只对item名称和它的String值感兴趣。正如你料想的，访问这些非常简单。

// 处理常规表单字段
if (item.isFormField()) {
    String name = item.getFieldName();
    String value = item.getString();
    ...
}

对于文件上传，有几种不同的东西，你可能会想知道你处理之前的内容。下面是一些你可能感兴趣的方法示例。

// 处理文件上传
if (!item.isFormField()) {
    String fieldName = item.getFieldName();
    String fileName = item.getName();
    String contentType = item.getContentType();
    boolean isInMemory = item.isInMemory();
    long sizeInBytes = item.getSize();
    ...
}

使用上传文件，你通常不想通过内存要访问它们，除非它们很小，或者你没有其它选择。你宁愿将想要处理的内容作为一个流，或写入整个文件到它的最终位置。FileUpload提供简单的方法完成这两种。

// 处理文件上传
if (writeToFile) {
    File uploadedFile = new File(...);
    item.write(uploadedFile);
} else {
    InputStream uploadedStream = item.getInputStream();
    ...
    uploadedStream.close();
}

注意，在默认的FileUpload实现中，如果数据已经在临时文件中，write()将试图重命名文件到指定目标。
如果你需要访问内存中的上传数据，你需要简单调用get()方法获取数据作为byte数组。

// 处理内存中的文件上传
byte[] data = item.get();
...

2.8    资源清理

如果你使用DiskFileItem，你上传的文件处理之前被写入临时文件。这些临时文件被自动删除，如果他们不再使用，如果相应的java.io.File实例被垃圾回收。通过org.apache.commons.io.FileCleaner类默默开启一个清理线程。这个清理线程应该被停止，如果它不再需要。在Servlet环境中，通过使用一个特定Servlet上下文监听器（FileCleanerCleanup）来完成。为了这么做，在你的web.xml中添加：

<web-app>
  ...
  <listener>
    <listener-class>
      org.apache.commons.fileupload.servlet.FileCleanerCleanup
    </listener-class>
  </listener>
  ...
</web-app>

2.9    创建DiskFileItemFactory

FileCleanerCleanup提供一个org.apache.commons.io.FileCleaningTracker实例。当创建org.apache.commons.fileupload.disk.DiskFileItemFactory时必须使用该实例。

public static DiskFileItemFactory newDiskFileItemFactory(ServletContext context, File repository) {
    FileCleaningTracker fileCleaningTracker = FileCleanerCleanup.getFileCleaningTracker(context);
    DiskFileItemFactory factory = new DiskFileItemFactory(DiskFileItemFactory.DEFAULT_SIZE_THRESHOLD, repository);
    factory.setFileCleaningTracker(fileCleaningTracker);
    return factory;
}

2.10    禁用临时文件清理

为了禁用临时文件跟踪，你可以设置FileCleaningTracker为null。因此，创建文件将不再被跟踪。尤其，它们将不再被自动删除。

2.11    集成病毒扫描

病毒扫描和web容器运行在相同的系统中对于使用FileUpload的应用程序会导致一些意想不到的行为。本文描述一些你可能遇到的行为，并且提供一些如何处理它们的方式。
FileUpload的默认实现将导致上传的item超过某一阀值被写入磁盘。就这样一个文件关闭，系统上的任何病毒扫描程序会来检查它，并且可能隔离文件——即，把它移动到一个不能导致文件的地方。当然，这将给应用程序开发人员一个惊喜，因为上传文件item不再有效。话句话说，上传item在相同阀值下将保存在内容中，因此将不会被病毒扫描器发觉。这允许一个病毒可能以某种形式被保留（尽管从不写入磁盘，病毒扫描程序应该定位和检查它）。
一个常用的解决办法是将所有上传的文件放置系统的一个目录中，并配置病毒扫描器忽略该目录。这将确保应用程序不会丢掉文件，然而脱离病毒扫描程序的职责范围，对上传的文件进行病毒扫描可以由外部处理，移动干净或以清理了文件到“批准”位置，或在应用程序中集成病毒扫描程序。

2.12    查看进程

如果你期望真实的大文件上传，那么它将很好的报告给你的用户已经接收了多少。每个HTML页面允许实现一个进度条，通过返回一个multipart/replace响应或这样的东西。

查看上传进度可以通过提供一个进度监听器完成：

// 创建一个进度监听器
ProgressListener progressListener = new ProgressListener(){
   public void update(long pBytesRead, long pContentLength, int pItems) {
       System.out.println("We are currently reading item " + pItems);
       if (pContentLength == -1) {
           System.out.println("So far, " + pBytesRead + " bytes have been read.");
       } else {
           System.out.println("So far, " + pBytesRead + " of " + pContentLength
                              + " bytes have been read.");
       }
   }
};
upload.setProgressListener(progressListener);

帮自己一个忙，实现你的第一个进度监听器，像上面这样，因为它显示了一个陷阱：进度监听器被频繁调用。依赖于Servlet引擎和其它环境工厂，它可能调用任何网络包！换句话说，你的进程监听器可能成为性能问题！一个典型的解决方法是减少进度监听器的活跃度。例如，你可以只在兆字节数量改变时发出消息：

// 创建进度监听器
ProgressListener progressListener = new ProgressListener(){
   private long megaBytes = -1;
   public void update(long pBytesRead, long pContentLength, int pItems) {
       long mBytes = pBytesRead / 1000000;
       if (megaBytes == mBytes) {
           return;
       }
       megaBytes = mBytes;
       System.out.println("We are currently reading item " + pItems);
       if (pContentLength == -1) {
           System.out.println("So far, " + pBytesRead + " bytes have been read.");
       } else {
           System.out.println("So far, " + pBytesRead + " of " + pContentLength
                              + " bytes have been read.");
       }
   }
};

3    流API

3.1    为什么使用流？

假设，文件item实际被用户访问之前必须存储在某一地方。这种方式很方便，因为它允许易于访问item内容。话句话说，
它消耗内存和时间。
流API允许你牺牲一点点便利，优化性能和较低的内存配置。然而，流API更轻量级，因此易于理解。

3.2    工作原理

FileUpload类用于访问表单字段和字段顺序，它们已经通过客户端发送。然而，FileItemFactory完全被忽略。

3.3    解析请求

首先，不要忘记确保，请求实际是一个文件上传请求。这通常是通过使用相同的静态方法。

// 检查我们有一个文件上传请求
boolean isMultipart = ServletFileUpload.isMultipartContent(request);

现在我们已经准备好解析请求：

// 创建新文件上传处理器
ServletFileUpload upload = new ServletFileUpload();

// 解析请求
FileItemIterator iter = upload.getItemIterator(request);
while (iter.hasNext()) {
    FileItemStream item = iter.next();
    String name = item.getFieldName();
    InputStream stream = item.openStream();
    if (item.isFormField()) {
        System.out.println("Form field " + name + " with value "
            + Streams.asString(stream) + " detected.");
    } else {
        System.out.println("File field " + name + " with file name "
            + item.getName() + " detected.");
        // 处理输入流
        ...
    }
}