源码(四) - FileItemFactory和DiskFileItemFactory

一.概述

1.DiskFileItemFactory

默认的FileItemFactory实现
1.此实现 创建FileItem实例，并将较小的items保存在内存中，将较大的items缓存到磁盘上的临时文件
2.存储到磁盘上内容的大小阈值和创建临时文件的目录都是可以配置的
3.如果没有配置，默认配置值如下：
    3.1 大小阈值为10KB
    3.2 Repository是系统默认的临时目录，由其返回：System.getProperty("java.io.tmpdir")

4.当使用DiskFileItemFactory时，您应该考虑以下内容：
  4.1 当临时文件不在需要时，临时文件会自动删除（更确切的说：当java.io.File对应的实例被垃圾回收时）
  4.2 清理这些临时文件是由一个FileCleaningTracker实例和一个相关的线程完成的
    4.3 在复杂的环境中，例如在Web应用程序中，您应该考虑终止此线程，例如，当您的Web应用程序结束时。
  请参阅“Resource cleanup”部分在commons-fileupload的用户指南中： http://commons.apache.org/proper/commons-fileupload/using.html

2.Resource cleanup

2.1 本节仅在使用的DiskFileItem时适用。 换句话说，如果上传文件在处理它们之前被写入临时文件，那么它是适用的。

2.2 如果不再使用这些临时文件，则会自动删除这些临时文件（更确切地说，如果相应的DiskFileItem实例被垃圾回收，则可以通过org.apache.commons.io.FileCleanerTracker类静默地创建，这个类可以启动还原线程。

2.3 如果不再需要，这个还原线应停止。 在一个servlet环境中，这是通过使用一个名为FileCleanerCleanup的特殊servlet上下文监听器完成的。 为此，请在Web.xml中添加如下所示的部分：

This section applies only, if you are using the DiskFileItem. In other words, it applies, if your uploaded files are written to temporary files before processing them.

Such temporary files are deleted automatically, if they are no longer used (more precisely, if the corresponding instance of DiskFileItem is garbage collected. This is done silently by the org.apache.commons.io.FileCleanerTracker class, which starts a reaper thread.

This reaper thread should be stopped, if it is no longer needed. In a servlet environment, this is done by using a special servlet context listener, called FileCleanerCleanup. To do so, add a section like the following to your web.xml:

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

二.FileItemFactory接口

// 1.2.1
package org.apache.commons.fileupload;

/**
 * 用于创建FileItem实例
 * <p>A factory interface for creating {@link FileItem} instances. 
 * Factories can provide their own custom configuration, over and above that provided
 * by the default file upload implementation.</p>
 */
public interface FileItemFactory {
    /**
	 * 从提供的参数和任何本地工厂配置创建新的FileItem实例
     * Create a new {@link FileItem} instance from the supplied parameters and any local factory configuration.
     *
     * @param fieldName   表单字段的名称
     * @param contentType 表单字段的内容类型
     * @param isFormField true表示这是一个简单的表单字段
     * @param fileName    上传文件的名称，由浏览器或其他客户端提供
     *
     * @return The newly created file item.
     */
    FileItem createItem(
			String fieldName,
            String contentType,
            boolean isFormField,
            String fileName
            );
}

三.DiskFileItemFactory源码

// 1.2.1
package org.apache.commons.fileupload.disk;

import java.io.File;

import org.apache.commons.fileupload.FileItem;
import org.apache.commons.fileupload.FileItemFactory;
import org.apache.commons.io.FileCleaningTracker;

/**
 * 默认的FileItemFactory实现
 * 1.此实现创建FileItem实例，并将较小的items保存在内存中，将较大的items缓存到磁盘上的临时文件
 * 2.存储到磁盘上内容的大小阈值和创建临时文件的目录都是可以配置的
 * 3.如果没有配置，默认配置值如下：
 *   3.1 大小阈值为10KB
 *   3.2 Repository是系统默认的临时目录，由其返回：System.getProperty("java.io.tmpdir")
 * 4.当使用DiskFileItemFactory时，您应该考虑以下内容：
 *	 4.1 当临时文件不在需要时，临时文件会自动删除（更确切的说：当java.io.File对应的实例被垃圾回收时）
 *	 4.2 清理这些临时文件是由一个FileCleaningTracker实例和一个相关的线程完成的
 *   4.3 在复杂的环境中，例如在Web应用程序中，您应该考虑终止此线程，例如，当您的Web应用程序结束时。
 *		 请参阅“Resource cleanup”部分在commons-fileupload的用户指南中。
 * The default {@link org.apache.commons.fileupload.FileItemFactory} implementation. 
 * This implementation creates {@link org.apache.commons.fileupload.FileItem} instances which keep their
 * content either in memory, for smaller items, or in a temporary file on disk, for larger items. 
 * The size threshold, above which content will be stored on disk, is configurable, 
 * as is the directory in which temporary files will be created
 *
 * <p>If not otherwise configured, the default configuration values are as
 * follows:
 * <ul>
 *   <li>Size threshold is 10KB.</li>
 *   <li>Repository is the system default temp directory, as returned by
 *       <code>System.getProperty("java.io.tmpdir")</code>.</li>
 * </ul>
 * </p>
 *
 * When using the <code>DiskFileItemFactory</code>, then you should consider the following: 
 * 	Temporary files are automatically deleted as soon as they are no longer needed. (More precisely, when the corresponding instance of {@link java.io.File} is garbage collected.)
 *  Cleaning up those files is done by an instance of {@link FileCleaningTracker}, and an associated thread. 
 *  In a complex environment, for example in a web application, you should consider terminating this thread, for example, when your web applicatio ends. 
 *  See the section on "Resource cleanup" in the users guide of commons-fileupload.</p>
 *
 * @since FileUpload 1.1
 */
public class DiskFileItemFactory implements FileItemFactory {
    /**
	 * 存储到磁盘上内容的默认大小阈值，为10KB
     * The default threshold above which uploads will be stored on disk.
     */
    public static final int DEFAULT_SIZE_THRESHOLD = 10240;

    /**
	 * 存储在磁盘上传文件的文件目录
     * The directory in which uploaded files will be stored, if stored on disk.
     */
    private File repository;

    /**
	 * 存储到磁盘上内容的大小阈值
     * The threshold above which uploads will be stored on disk.
     */
    private int sizeThreshold = DEFAULT_SIZE_THRESHOLD;

    /**
	 * FileCleaningTracker的实例，负责删除临时文件
     * The instance of {@link FileCleaningTracker}, which is responsible for deleting temporary files.
     * <p>May be null, if tracking files is not required.</p>
     */
    private FileCleaningTracker fileCleaningTracker;

    /**
	 * 构造此类的未配置实例。 所产生的工厂可以通过调用适当的setter方法进行配置。
     * Constructs an unconfigured instance of this class. The resulting factory may be configured by calling the appropriate setter methods.
     */
    public DiskFileItemFactory() {
        this(DEFAULT_SIZE_THRESHOLD, null);
    }

    /**
	 * 构造此类的预配置实例。
     * Constructs a preconfigured instance of this class.
     *
     * @param sizeThreshold 阈值，低于它保留在内存中，高于它以临时文件缓存到磁盘上
     * @param repository    The data repository, which is the directory in
     *                      which files will be created, should the item size
     *                      exceed the threshold.
     */
    public DiskFileItemFactory(int sizeThreshold, File repository) {
        this.sizeThreshold = sizeThreshold;
        this.repository = repository;
    }

    /**
	 * 返回用于临时存储大于配置大小阈值的文件的目录。
     * Returns the directory used to temporarily store files that are larger
     * than the configured size threshold.
     *
     * @return 返回临时文件所在的目录。
     */
    public File getRepository() {
        return repository;
    }

    /**
	 * 设置用于临时存储大于配置大小阈值的文件的目录。
     * Sets the directory used to temporarily store files that are larger
     * than the configured size threshold.
     *
     * @param repository The directory in which temporary files will be located.
     */
    public void setRepository(File repository) {
        this.repository = repository;
    }

    /**
	 * 返回大小阈值，默认为10KB
     * Returns the size threshold beyond which files are written directly to
     * disk. The default value is 10240 bytes.
     *
     * @return The size threshold, in bytes.单位为字节
     */
    public int getSizeThreshold() {
        return sizeThreshold;
    }


    /**
	 * 设置阈值
     * Sets the size threshold beyond which files are written directly to disk.
     *
     * @param sizeThreshold The size threshold, in bytes.
     */
    public void setSizeThreshold(int sizeThreshold) {
        this.sizeThreshold = sizeThreshold;
    }

    /**
	 * 从提供的参数和本地工厂配置创建一个新的DiskFileItem实例
     * Create a new {@link org.apache.commons.fileupload.disk.DiskFileItem}
     * instance from the supplied parameters and the local factory
     * configuration.
     *
     * @param fieldName   The name of the form field.
     * @param contentType The content type of the form field.
     * @param isFormField <code>true</code> if this is a plain form field;
     *                    <code>false</code> otherwise.
     * @param fileName    The name of the uploaded file, if any, as supplied
     *                    by the browser or other client.
     *
     * @return The newly created file item.
     */
    public FileItem createItem(String fieldName, String contentType, boolean isFormField, String fileName) {
        DiskFileItem result = new DiskFileItem(fieldName, contentType, isFormField, fileName, sizeThreshold, repository);
        FileCleaningTracker tracker = getFileCleaningTracker();
        if (tracker != null) {
            tracker.track(result.getTempFile(), this);
        }
        return result;
    }


    /**
	 * 返回FileCleaningTracker实例
     * Returns the tracker, which is responsible for deleting temporary files.
     * @return An instance of {@link FileCleaningTracker}, defaults to
     *   {@link org.apache.commons.io.FileCleaner#getInstance()}. Null,
     *   if temporary files aren't tracked.
     */
    public FileCleaningTracker getFileCleaningTracker() {
        return fileCleaningTracker;
    }

    /**
	 * 返回tracker，它负责删除临时文件。
     * Returns the tracker, which is responsible for deleting temporary files.
     * @param pTracker An instance of {@link FileCleaningTracker}, which will from now on track the created files. May be null to disable tracking.
	 *					FileCleaningTracker的一个实例，它将从现在开始跟踪创建的文件。 为null表示禁用跟踪。
     */
    public void setFileCleaningTracker(FileCleaningTracker pTracker) {
        fileCleaningTracker = pTracker;
    }
}