commons-fileupload用户指南（文档翻译
使用fileupload
根据你的应用需求，fileupload可以有许多不同的使用方式。在最简单的情况下，你可以调用一个简单的方法来解析servlet请求，然后在他们提交到你的应用时处理表单列表。在其它规模的终端上，你也可能决定将fileupload进行自定义，以完全控制个别表单项存储的方法。比如，你或许会将内容流化来保存到数据中。
在这里。我们将要描述fileupload的基本使用方法，然后解释一些更简单的，以及最常用的使用模式。fileupload的个性化在这里得到了描述。
它怎么工作
一个文件上传请求由有序表单项的列表组成，这些表单是根据RFC1867来编码的，是在html中基于表单的文件上传。fileupload能解析这样一个请求然后向你的应用提供一个单独的上传表单项的列表。每一个这样的表单项实现了FileItem接口，而不需要考虑它潜在的实现方式。每个文件的表单项拥有一系列可能对你的应用有用的属性，比如，每个项目都有一个名字和文件类型，你就可以提供一个InputStream来取它的数据。从另一方面说，你可能需要对这些选项进行不同的处理，这个可以根据对这个选项是不是一个规则的表单项来判断，即可以根据这个数据是否来源于普通的文本框或者一个简单的html表单域，还是一个能被上传的文件。FileItem接口提供了多种方法来判断它是否是一个可上传的文件，然后你就可以用最合适的方式来处理这些数据了。FileUpload使用FileItemFactory来创建新的文件项目。这正是给FileUpload带来灵活性的原因。这个工厂最终控制每个项目的创建。默认的工厂在内存或者磁盘上保存了项目的数据，这个可以根据项目的大小来定（例如，字节数据）。当然，这个动作可以通过自定义来满足你应用的需要。
解析请求
在你对要上传的选项处理之前，很显然的你得先解析这些请求本身。很直接的就是要确保这个请求是不是一个要上传的文件，然而FileUpload使这一点简单化了，你只需提供一个静态的方法来做到这一点。
//检查是否是一个文件上传请求
boolean isMultipart = FileUpload.isMultipartContent(request);
现在我们就可以准备解析这个请求到一个备选的选项了。解析的结果是一个文件选项的List,每个这样的选项都实现了FileItem接口，处理这些选项将在下面得到讨论。
最简单的情况
最简单的使用场景可以参照下面：
//创建一个新的文件上传句柄
DiskFileUpload upload = new DiskFileUpload();
//解析请求
List /* FileItem */ items = upload.parseRequest(request);
这就是所有我们需要做的，真的！
解析的结果是一个文件项目的List,每一个都实现了FileItem接口。处理这些项目将在下面讨论。
练习更多的控制
如果你的使用情景非常接近最简单的使用方式，在上文中可以看到，但是你需要更多的控制临界的大小和临时文件的驻留地址，你可以使用DiskFileUpload类的方法来自定义这些动作，就像这样：
//创建一个新的文件上传句柄
DiskFileUpload upload = new DiskFileUpload();
//设置上传参数
upload.setSizeThrehold(最大内存大小);
upload.setSizeMax(最大请求大小);
upload.setRepositoryPath(临时目录);
//解析请求
List /* FileItem */ items = upload.parseRequest(request);
当然，每个配置方法都是独立于其它的，但是如果你想一次就配置它们，你可以使用可选的parseRequest()方法，像这样：
// 建立一个新的文件上传句柄
DiskFileUpload upload = new DiskFileUpload();
// 解析请求
List /* FileItem */ items = upload.parseRequest(request,
内存大小, 允许上传的最大文件, 临时目录);
如果你想更多地控制请求的解析，比如把上传选项存储到其它地方，例如，存到数据库中-你可以参照自定义FileUpload。
处理上传选项
一旦解析过程完毕，你就可以获得一个文件选项的List，以便进一步处理。在大多数情况下，你将会根据规则的表单域来不同地处理文件的上传。所以你可能以这样的方式来处理：
// 处理上传的选项
Iterator iter = items.iterator();
while (iter.hasNext()) {
FileItem item = (FileItem) iter.next();
if (item.isFormField()) {
processFormField(item);
} else {
processUploadedFile(item);
}
}
对于一个规则的表单域来说，你对它感兴趣的可能就只有它的名字以及它的字符串值。你也会想到，处理它们是简单的:
//处理一个规则表单域
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[] data = item.get();
...
和杀毒软件的相互作用
当web容器在运行时，而杀毒软件又同时运行在同样的系统上，这种情况下在应用中使用FileUpload容易导致一些很难预料的事情.这部分将描述一些你可能要遇到的情况，我们会提供一些方法来处理它们。默认的FileUpload实现将会使超过它在内存中大小的上传的选项写入到磁盘。而当这样的文件关闭后，任何系统中的杀毒软件都会被唤醒,然后去检查它，然后会潜在地隔离这个文件--就是说，将它移动到一个不产生问题的特定地方。这样一来，对开发者来说当然是一个意外，因为刚刚上传的文件将不能被处理了。从另一方面来说，小于设定的内存大小的那些上传的文件将被保持在内存中，这样一来，将不会被杀毒软件所检测到，这样就有可能使病毒以某种方式驻留在了系统中了（虽然如果一旦它被写入到磁盘，杀毒软件就会定位并检测到它）。一个通用的解决方法是在系统中专门设置一个目录来存放这些上传的文件，然后配置杀毒软件忽略这个目录。这样将确保上传的文件在系统中不被隔离，但是这样就把扫描病毒的责任交给了应用程序的开发者了。扫描这些上传的文件的任务可以在外部的处理中实现。这样可以将干净的文件移动到一个“改进”过的地方，或者也可以把杀毒集成到应用中去。至于怎么将外部处理或集成病毒扫描到一个
应用，这个已经超出了本文档的讨论范围。
下一步是什么
希望这个页面能提供给你一个好的意见，让你在你自己的应用中能使用FileUpload。更多关于这里介绍的方法，以及其它可用的方法，你可以参照api文档。这里介绍的用法已经可以满足大多数的文件上传的需要了，当然，如果你还有更多的复杂的需求，使用它的灵活的自定义配置的能力，FileUpload一定可以能够帮助你。
Author: Bruce chen
email:love.oss@gmail.com
msn:cf_asp_master@yahoo.com.cn
欢迎指正
根据你的应用需求，fileupload可以有许多不同的使用方式。在最简单的情况下，你可以调用一个简单的方法来解析servlet请求，然后在他们提交到你的应用时处理表单列表。在其它规模的终端上，你也可能决定将fileupload进行自定义，以完全控制个别表单项存储的方法。比如，你或许会将内容流化来保存到数据中。
在这里。我们将要描述fileupload的基本使用方法，然后解释一些更简单的，以及最常用的使用模式。fileupload的个性化在这里得到了描述。
它怎么工作
一个文件上传请求由有序表单项的列表组成，这些表单是根据RFC1867来编码的，是在html中基于表单的文件上传。fileupload能解析这样一个请求然后向你的应用提供一个单独的上传表单项的列表。每一个这样的表单项实现了FileItem接口，而不需要考虑它潜在的实现方式。每个文件的表单项拥有一系列可能对你的应用有用的属性，比如，每个项目都有一个名字和文件类型，你就可以提供一个InputStream来取它的数据。从另一方面说，你可能需要对这些选项进行不同的处理，这个可以根据对这个选项是不是一个规则的表单项来判断，即可以根据这个数据是否来源于普通的文本框或者一个简单的html表单域，还是一个能被上传的文件。FileItem接口提供了多种方法来判断它是否是一个可上传的文件，然后你就可以用最合适的方式来处理这些数据了。FileUpload使用FileItemFactory来创建新的文件项目。这正是给FileUpload带来灵活性的原因。这个工厂最终控制每个项目的创建。默认的工厂在内存或者磁盘上保存了项目的数据，这个可以根据项目的大小来定（例如，字节数据）。当然，这个动作可以通过自定义来满足你应用的需要。
解析请求
在你对要上传的选项处理之前，很显然的你得先解析这些请求本身。很直接的就是要确保这个请求是不是一个要上传的文件，然而FileUpload使这一点简单化了，你只需提供一个静态的方法来做到这一点。
//检查是否是一个文件上传请求
boolean isMultipart = FileUpload.isMultipartContent(request);
现在我们就可以准备解析这个请求到一个备选的选项了。解析的结果是一个文件选项的List,每个这样的选项都实现了FileItem接口，处理这些选项将在下面得到讨论。
最简单的情况
最简单的使用场景可以参照下面：
- 被上传得选项必须以适度的大小驻留在内存中；
- 比较大的文件上传选项必须写入到磁盘的临时文件中去；
- 大文件上传请求必须不被允许；
- 默认的驻留内存的选项的最大大小，最大允许的上传文件请求，和临时文件的存储地方是可以接受的；
//创建一个新的文件上传句柄
DiskFileUpload upload = new DiskFileUpload();
//解析请求
List /* FileItem */ items = upload.parseRequest(request);
这就是所有我们需要做的，真的！
解析的结果是一个文件项目的List,每一个都实现了FileItem接口。处理这些项目将在下面讨论。
练习更多的控制
如果你的使用情景非常接近最简单的使用方式，在上文中可以看到，但是你需要更多的控制临界的大小和临时文件的驻留地址，你可以使用DiskFileUpload类的方法来自定义这些动作，就像这样：
//创建一个新的文件上传句柄
DiskFileUpload upload = new DiskFileUpload();
//设置上传参数
upload.setSizeThrehold(最大内存大小);
upload.setSizeMax(最大请求大小);
upload.setRepositoryPath(临时目录);
//解析请求
List /* FileItem */ items = upload.parseRequest(request);
当然，每个配置方法都是独立于其它的，但是如果你想一次就配置它们，你可以使用可选的parseRequest()方法，像这样：
// 建立一个新的文件上传句柄
DiskFileUpload upload = new DiskFileUpload();
// 解析请求
List /* FileItem */ items = upload.parseRequest(request,
内存大小, 允许上传的最大文件, 临时目录);
如果你想更多地控制请求的解析，比如把上传选项存储到其它地方，例如，存到数据库中-你可以参照自定义FileUpload。
处理上传选项
一旦解析过程完毕，你就可以获得一个文件选项的List，以便进一步处理。在大多数情况下，你将会根据规则的表单域来不同地处理文件的上传。所以你可能以这样的方式来处理：
// 处理上传的选项
Iterator iter = items.iterator();
while (iter.hasNext()) {
FileItem item = (FileItem) iter.next();
if (item.isFormField()) {
processFormField(item);
} else {
processUploadedFile(item);
}
}
对于一个规则的表单域来说，你对它感兴趣的可能就只有它的名字以及它的字符串值。你也会想到，处理它们是简单的:
//处理一个规则表单域
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[] data = item.get();
...
和杀毒软件的相互作用
当web容器在运行时，而杀毒软件又同时运行在同样的系统上，这种情况下在应用中使用FileUpload容易导致一些很难预料的事情.这部分将描述一些你可能要遇到的情况，我们会提供一些方法来处理它们。默认的FileUpload实现将会使超过它在内存中大小的上传的选项写入到磁盘。而当这样的文件关闭后，任何系统中的杀毒软件都会被唤醒,然后去检查它，然后会潜在地隔离这个文件--就是说，将它移动到一个不产生问题的特定地方。这样一来，对开发者来说当然是一个意外，因为刚刚上传的文件将不能被处理了。从另一方面来说，小于设定的内存大小的那些上传的文件将被保持在内存中，这样一来，将不会被杀毒软件所检测到，这样就有可能使病毒以某种方式驻留在了系统中了（虽然如果一旦它被写入到磁盘，杀毒软件就会定位并检测到它）。一个通用的解决方法是在系统中专门设置一个目录来存放这些上传的文件，然后配置杀毒软件忽略这个目录。这样将确保上传的文件在系统中不被隔离，但是这样就把扫描病毒的责任交给了应用程序的开发者了。扫描这些上传的文件的任务可以在外部的处理中实现。这样可以将干净的文件移动到一个“改进”过的地方，或者也可以把杀毒集成到应用中去。至于怎么将外部处理或集成病毒扫描到一个
应用，这个已经超出了本文档的讨论范围。
下一步是什么
希望这个页面能提供给你一个好的意见，让你在你自己的应用中能使用FileUpload。更多关于这里介绍的方法，以及其它可用的方法，你可以参照api文档。这里介绍的用法已经可以满足大多数的文件上传的需要了，当然，如果你还有更多的复杂的需求，使用它的灵活的自定义配置的能力，FileUpload一定可以能够帮助你。
Author: Bruce chen
email:love.oss@gmail.com
msn:cf_asp_master@yahoo.com.cn
欢迎指正
