最近一段时间都在为文件上传这件事焦心，总是找不合适的代码，自己水平差写不出什么好东西出来，所以问题一直拖到现在。今天在google上看到commons FileUpload的相关简介，马上就去Apache Jakarta Project去找。哈哈……没错，就是它啦~
花了一个小时把它的E文Overview看了一下，觉得使用起来实在太方便了，短短地几句话就可以完成上传操作，真不赖，让我又可以小偷懒一把：P。下午，又写了一个简单的Bean来测试里面关键的类的使用，更具体的了解了它的方法作用的结果。再把那个E文User Guide主要的地方，在这里翻译一下。对于做页面上传文件的工作应该有一定的帮助。
Using FileUpload
使用FileUpload
FileUpload can be used in a number of different ways, depending upon the requirements of your application. In the simplest case, you will call a single method to parse the servlet request, and then process the list of items as they apply to your application. At the other end of the scale, you might decide to customize FileUpload to take full control of the way in which individual items are stored; for example, you might decide to stream the content into a database.
FileUpload可以根据应用程序的需求在很多不同的地方使用。举个很简单的例子，你可能调用一个简单的方法去编译servlet请求，并且把这些项目作为你的应用程序一部分来应用。从另一个方面来讲，你可能想自定义FileUpload来完成所有项目的存储；再来个例子，你可能想流化内容而存入数据库。
Here, we will describe the basic principles of FileUpload, and illustrate some of the simpler - and most common - usage patterns. Customization of FileUpload is described elsewhere .
这里我们会介绍FileUpload基础的使用原则，并描述一些简单的通用的使用模式。关于FileUpload自定义的介绍会在其它地方（其实那里什么也没有）讲。
How it works
简介
A file upload request comprises an ordered list of items that are encoded according to RFC 1867 , "Form-based File Upload in HTML". FileUpload can parse such a request and provide your application with a list of the individual uploaded items. Each such item implements t he FileItem interface, regardless of its underlying implementation.
一个上传请求由一系列根据RFC1867（这个文章我已经放在BLOG收藏夹HTML目录下）编码的项目。FileUpload可以编译这样的请求并将这一系列的个性化上传项目传递给你的应用程序。每一个这样的项目都实现了FielItem接口，不管它是怎么实现的。
Each file item has a number of properties that might be of interest for your application. For example, every item has a name and a content type, and can provide an InputStream to access its data. On the other hand, you may need to process items differently, depending upon whether the item is a regular form field - that is, the data came from an ordinary text box or similar HTML field - or an uploaded file. The FileItem interface provides the methods to make such a determination, and to access the data in the most appropriate manner.
每一个文件项目有一些自己的属性，这些属性也许正是你的应用程序感兴趣的地方。例如，每个项目有个一个名字和内容类型，并且可以提供一个输入流来访问这写数据。另一方面来看，你可能需要用不同方式来处理不同的项目，这就依赖与项目是否是一个正常的字域，也就是说，这些数据来自于一个普通的文本框或类似HTML的字域或一个上传文件。FileItem接口提供一些方法来做这样一个决定，并且访问这些数据用最合适的方法。
FileUpload creates new file items using a FileItemFactory . This is what gives FileUpload most of its flexibility. The factory has ultimate control over how each item is created. The default factory stores the item's data in memory or on disk, depending on the size of the item (i.e. bytes of data). However, this behavior can be customized to suit your application.
FileUpload使用FileItemFactory创建一个新的文件项目。对于FileUpload来说这是完全可行的。工厂是唯一全盘控制每个项目的创建的工具。默认的工厂存储项目的数据在内存或者硬盘里，这都依赖于项目的大小（如，数据字节数组）。不过，还是可以把它定义成为合适你的应用程序使用的。
Parsing the request
Before you can work with the uploaded items, of course, you need to parse the request itself. Ensuring that the request is actually a file upload request is straightforward, but FileUpload makes it simplicity itself, by providing a static method to do just that.
在使用上传项目工作之前，你还需要编译请求。最重要的事情就要确定这个请求确实来自于文件上传，不过FileUpload利用一个静态方法使它自身简单化了。
// Check that we have a file upload request
boolean isMultipart = FileUpload.isMultipartContent(request);
Now we are ready to parse the request into its constituent items.
现在我们可以准备开始编译请求了。
The simplest case
简单的例子
The simplest usage scenario is the following:
Uploaded items should be retained in memory as long as they are reasonably small.
Larger items should be written to a temporary file on disk.
Very large upload requests should not be permitted.
The built-in defaults for the maximum size of an item to be retained in memory, the maximum permitted size of an upload request, and the location of temporary files are acceptable.
下面是一些简单的使用场景：
l 上传项目只要足够小，就应该保留在内存里。
l 较大的项目应该被写在硬盘的临时文件上。
l 非常大的上传请求应该避免。
l 限制项目在内存中所占的空间，限制最大的上传请求，并且设定临时文件的位置。
Handling a request in this scenario couldn't be much simpler:
处理这个场景的请求很简单：
// Create a new file upload handler
DiskFileUpload upload = new DiskFileUpload();
// Parse the request
List /* FileItem */ items = upload.parseRequest(request);
That's all that's needed. Really!
这就是我们所需要的全部代码了！
The result of the parse is a List of file items, each of which implements the FileItem interface. Processing these items is discussed below.
编译的结果就是生成了一系列文件项目，每个文件项目实现一个FileItem接口。下面将介绍如何处理这写项目。
Exercising more control
控制练习
If your usage scenario is close to the simplest case, described above, but you need a little more control over the size thresholds or the location of temporary files, you can customize the behavior using the methods of the DiskFileUpload class, like this:
如果你的使用场景和最简单例子很接近，但是你又需要一点点扩展的控制，包括大小的极限或者临时文件的设置等，你可以通过DiskFileUpload类的方法来自定义行为，像这样：
// Create a new file upload handler
DiskFileUpload upload = new DiskFileUpload();
// Set upload parameters
upload.setSizeThreshold(yourMaxMemorySize);
upload.setSizeMax(yourMaxRequestSize);
upload.setRepositoryPath(yourTempDirectory);
// Parse the request
List /* FileItem */ items = upload.parseRequest(request);
Of course, each of the configuration methods is independent of the others, but if you want to configure them all at once, you can do that with an alternate parseRequest() method, like this:
当然，每个配置方法是独立于其它任意一个的，但是如果你想一次性配置他们，你可以用parseRequest()的另一个重载方法，像这样：
// Create a new file upload handler
DiskFileUpload upload = new DiskFileUpload();
// Parse the request
List /* FileItem */ items = upload.parseRequest(request,
yourMaxMemorySize, yourMaxRequestSize, yourTempDirectory);
Should you need further control over the parsing of the request, such as storing the items elsewhere - for example, in a database - you will need to look into customizing FileUpload.
如果你还想使用更多的控制，比如存储项目到其它地方（如，数据库），那么你可以看FileUpload自定义（这个连接又是个假的，空页面）介绍。
Processing the uploaded items
处理上传项目
Once the parse has completed, you will have a List of file items that you need to process. In most cases, you will want to handle file uploads differently from regular form fields, so you might process the list like this:
一旦编译完成，那么你会得到一个待处理的文件项目列表。很多的情况下，你会想单独处理每个特定的项目，因此，你可以这样做：
// Process the uploaded items
Iterator iter = items.iterator();
while (iter.hasNext()) {
FileItem item = (FileItem) iter.next();
if (item.isFormField()) {
processFormField(item);
} else {
processUploadedFile(item);
}
}
For a regular form field, you will most likely be interested only in the name of the item, and its String value. As you might expect, accessing these is very simple.
对于普通的表单字域来说，你可能对项目的名称很感兴趣。完成你的需求真的很简单，照下面的做：
// Process a regular form field
if (item.isFormField()) {
String name = item.getFieldName();
String value = item.getString();
...
}
For a file upload, there are several different things you might want to know before you process the content. Here is an example of some of the methods you might be interested in.
对于上传文件，这里就有很多不同啦~你可能想知道更多其它的内容。下面是个例子，里面包含了不少有趣的方法。
// Process a file upload
if (!item.isFormField()) {
String fieldName = item.getFieldName();
String fileName = item.getName();
String contentType = item.getContentType();
boolean isInMemory = item.isInMemory();
long sizeInBytes = item.getSize();
...
}
With uploaded files, you generally will not want to access them via memory, unless they are small, or unless you have no other alternative. Rather, you will want to process the content as a stream, or write the entire file to its ultimate location. FileUpload provides simple means of accomplishing both of these.
对于上传的文件，你肯定不希望总是通过内存来访问它，除非它很小，或者你实在没有别的选择余地了。你很希望使用流来处理文件内容或者写文件实体到它最终的地址。FileUpload提供简单的方式，来完成两方面的需求。
// Process a file upload
if (writeToFile) {
File uploadedFile = new File(...);
item.write(uploadedFile);
} else {
InputStream uploadedStream = item.getInputStream();
...
uploadedStream.close();
}
Note that, in the default implementation of FileUpload, write() will attempt to rename the file to the specified destination, if the data is already in a temporary file. Actually copying the data is only done if the rename fails, for some reason, or if the data was in memory.
If you do need to access the uploaded data in memory, you need simply call the get() method to obtain the data as an array of bytes.
注意：在FileUpload的默认实现中wirte()方法应该值得关注，如果数据还在临时文件没有移除，那么这个方法就会试图重命名这个文件为相应的目标文件。事实上如果重命名失败了的话，数据就仅仅被拷贝。如果你需要访问内存中的上传数据，你可以用get()方法来获得数据的二进制数组形式。
// Process a file upload in memory
byte[] data = item.get();
...
What's next
下一步做什么
Hopefully this page has provided you with a good idea of how to use FileUpload in your own applications. For more detail on the methods introduced here, as well as other available methods, you should refer to the JavaDocs .
希望这个文章对你使用FileUpload有一些帮助。对于更多的细节，还是要阅读配套的文档。
The usage described here should satisfy a large majority of file upload needs. However, should you have more complex requirements, FileUpload should still be able to help you, with it's flexible customization capabilities.
这个使用简介应该是足够满足你大部分的需求。但是如果你有更复杂的需求的话，你还要自定义合适的可行方案。
到这里就粗略的把用户指南翻译了一遍，刚刚开始学习使用这个工具包，理解难免有偏差，我还会随着具体的使用来完善一些细节方面的内容（没办法，官方网站没有这方面的介绍，只能自己摸索了，呵呵）。
