Jakarta Commons FileUpload 用戶(hù)指南
本文是分享文檔站長(zhǎng)胡蘿卜的作品。大家可以自由閱讀、在網(wǎng)絡(luò)上進(jìn)行分發(fā)，前提是必須保留本文檔的完整性。
分享文檔是一家專(zhuān)業(yè)的Java技術(shù)網(wǎng)站，給中國(guó)Java 程序員提供各種Java資源如文檔，工具，教程，社區(qū)交流等。
我們的官方網(wǎng)站是：http://chinesedocument.com
我們的官方論壇是：http://bbs.chinesedocument.com
請(qǐng)大家多多關(guān)注分享文檔，我們還會(huì)發(fā)布更多優(yōu)秀的文檔！
第1章 使用FileUpload
FileUpload能以多種方式使用，這取決于你的應(yīng)用需求。舉個(gè)簡(jiǎn)單的例子，你可能調(diào)用一個(gè)單獨(dú)的方法來(lái)解析servelt的請(qǐng)求，并且處理那些項(xiàng)目。 從另一個(gè)方面來(lái)講，你可能想自定義FileUpload來(lái)完全控制個(gè)別項(xiàng)目的存貯；例如，你想流化那些內(nèi)容，并存到數(shù)據(jù)庫(kù)里去。
這里我們會(huì)介紹使用FileUpload的基礎(chǔ)原則，并描述一些簡(jiǎn)單的通用的使用模式。我們會(huì)在在其它地方介紹關(guān)于FileUpload的自定義。
FileUpload依賴(lài)于一些公用的IO，因此，要確保在你繼續(xù)之前，你的classpath里已經(jīng)有依賴(lài)頁(yè)面里提起的那些版本。
第2章 FileUpload如何工作？
一個(gè)上傳請(qǐng)求由一系列根據(jù)RFC1867（"Form-based File Upload in HTML".）編碼的項(xiàng)目列表組成。FileUpload可以解析這樣的請(qǐng)求，并為你的應(yīng)用提供那些已上傳的項(xiàng)目的列表。每一個(gè)這樣的項(xiàng)目都實(shí)現(xiàn)了FielItem接口，我們不用管它們的底層實(shí)現(xiàn)。
這個(gè)頁(yè)面描述了commons fileupload庫(kù)的常用API。這些常用API是非常方便的途徑。然而，為了最好的性能，你可能更喜歡最快的Streaming API 。
每一個(gè)文件項(xiàng)目有一些自己的屬性，這些屬性也許正是你的應(yīng)用程序感興趣的地方。例如，每個(gè)項(xiàng)目有個(gè)一個(gè)名字和內(nèi)容類(lèi)型，并且可以提供一個(gè)輸入流來(lái)訪問(wèn)它們的數(shù)據(jù)。另一方面來(lái)看，你可能需要用不同方式來(lái)處理不同的項(xiàng)目，這就依賴(lài)于那些項(xiàng)目是否是一個(gè)正常的表單字域，也就是說(shuō)，這些數(shù)據(jù)來(lái)自于一個(gè)普通的文本框或類(lèi)似HTML的字域，還是一個(gè)要上傳文件字段。FileItem接口提供一些方法來(lái)做這樣一個(gè)決定，并且用最合適的方法訪問(wèn)這些數(shù)據(jù)。
FileUpload使用FileItemFactory創(chuàng)建一個(gè)新的文件項(xiàng)目。這將會(huì)給FileUpload最好的靈活性。工廠最終控制每個(gè)項(xiàng)目如何被創(chuàng)建。默認(rèn)的工廠在內(nèi)存或者硬盤(pán)里存儲(chǔ)項(xiàng)目的數(shù)據(jù)，這依賴(lài)于項(xiàng)目的大小（例如，有多少字節(jié)的數(shù)據(jù)。）。不過(guò)，為了適用于你的應(yīng)用，你還是可以自定義這種行為的。
第3章 servlets and portlets
從V1.1版開(kāi)始，F(xiàn)ileUpload就開(kāi)始支持servlet和portlet的文件上傳請(qǐng)求。這兩種環(huán)境的用法基本上差不多，因此，文檔的剩下部分都將是在servlet環(huán)境里。
如果你正在構(gòu)建一個(gè)portet應(yīng)用，那么下面兩個(gè)差別是你在讀文檔時(shí)應(yīng)注意的：
你在哪里引用了ServletFileUpload類(lèi)，就用PortletFileUpload類(lèi)來(lái)替代它。
你在哪里引用了HttpServletRequest類(lèi)，就用ActionRequest類(lèi)替代它。
第4章 解析請(qǐng)求
在你同那些上傳的項(xiàng)目一起工作前，你需要先解析請(qǐng)求本身。以確保這個(gè)請(qǐng)求確實(shí)是一個(gè)文件上傳請(qǐng)求。FileUpload是通過(guò)調(diào)用一個(gè)靜態(tài)方法來(lái)實(shí)現(xiàn)的。
// Check that we have a file upload request
boolean isMultipart = ServletFileUpload.isMultipartContent(request);
現(xiàn)在，我們已經(jīng)準(zhǔn)備好解析請(qǐng)求里的項(xiàng)目了。
4.1 最簡(jiǎn)單的例子
下面是一些簡(jiǎn)單的使用場(chǎng)景：
?? 上傳項(xiàng)目只要足夠小，就應(yīng)該保留在內(nèi)存里。
?? 較大的項(xiàng)目應(yīng)該被寫(xiě)在硬盤(pán)的臨時(shí)文件上。
?? 非常大的上傳請(qǐng)求應(yīng)該避免。
?? 限制項(xiàng)目在內(nèi)存中所占的空間，限制最大的上傳請(qǐng)求，并且設(shè)定臨時(shí)文件的位置。
處理這個(gè)場(chǎng)景的請(qǐng)求很簡(jiǎn)單：
// Create a factory for disk-based file items
FileItemFactory factory = new DiskFileItemFactory();
// Create a new file upload handler
ServletFileUpload upload = new ServletFileUpload(factory);
// Parse the request
List /* FileItem */ items = upload.parseRequest(request);
這就是我們所需要的全部代碼了！
解析的結(jié)果就是一個(gè)項(xiàng)目的List,每個(gè)項(xiàng)目都實(shí)現(xiàn)了FileItem接口。我們將在下面討論如何處理這些項(xiàng)目。
4.2 訓(xùn)練如何控制
如果你的使用場(chǎng)景和上面那個(gè)簡(jiǎn)單的例子很接近，但是你又需要一點(diǎn)點(diǎn)控制，那么你可以很容易地定義upload處理器或者文件項(xiàng)目工廠的行為。下面這個(gè)例子顯示了幾個(gè)配置選項(xiàng)。
// Create a factory for disk-based file items
DiskFileItemFactory factory = new DiskFileItemFactory();
// Set factory constraints
factory.setSizeThreshold(yourMaxMemorySize);
factory.setRepository(yourTempDirectory);
// Create a new file upload handler
ServletFileUpload upload = new ServletFileUpload(factory);
// Set overall request size constraint
upload.setSizeMax(yourMaxRequestSize);
// Parse the request
List /* FileItem */ items = upload.parseRequest(request);
當(dāng)然，每個(gè)配置方法是獨(dú)立于其它任意一個(gè)的。但是如果你想一次性配置他們，你可以用parseRequest()的另一個(gè)重載方法，像這樣：
// Create a factory for disk-based file items
DiskFileItemFactory factory = new DiskFileItemFactory(
yourMaxMemorySize, yourTempDirectory);
如果你還想使用更多的控制，比如存儲(chǔ)項(xiàng)目到其它地方（如，數(shù)據(jù)庫(kù)），那么你可以看FileUpload自定義介紹。
第5章 處理上傳的項(xiàng)目
一旦解析完成，那么你會(huì)得到一個(gè)待處理的文件項(xiàng)目列表。很多的情況下，你會(huì)想用不同的方式來(lái)處理文件上傳域和正常的表單域，因此，你可以這樣做：
// Process the uploaded items
Iterator iter = items.iterator();
while (iter.hasNext()) {
FileItem item = (FileItem) iter.next();
if (item.isFormField()) {
processFormField(item);
} else {
processUploadedFile(item);
}
}
對(duì)于普通的表單域來(lái)說(shuō)，你可能對(duì)項(xiàng)目的名稱(chēng)和字符型值 很感興趣。就像你希望的那樣，照下面的做：
// Process a regular form field
if (item.isFormField()) {
String name = item.getFieldName();
String value = item.getString();
...
}
對(duì)于上傳文件，這里就有很多不同啦~你可能想知道更多其它的內(nèi)容。下面是個(gè)例子，里面包含了不少你感興趣的方法。
// 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();
...
}
對(duì)于上傳的文件，你肯定不希望總是通過(guò)內(nèi)存來(lái)訪問(wèn)它，除非它很小，或者你實(shí)在沒(méi)有別的選擇余地了。你很希望使用流來(lái)處理文件內(nèi)容或者將文件保存到它的最終位置。FileUpload提供簡(jiǎn)單的方式來(lái)完成兩方面的需求。
// Process a file upload
if (writeToFile) {
File uploadedFile = new File(...);
item.write(uploadedFile);
} else {
InputStream uploadedStream = item.getInputStream();
...
uploadedStream.close();
}
注意：在FileUpload的默認(rèn)實(shí)現(xiàn)中wirte()方法應(yīng)該值得關(guān)注，如果數(shù)據(jù)還在臨時(shí)文件里沒(méi)有移除，那么這個(gè)方法就會(huì)試圖重命名這個(gè)文件為相應(yīng)的目標(biāo)文件。事實(shí)上如果重命名失敗了的話，數(shù)據(jù)就僅僅被拷貝。
如果你需要訪問(wèn)內(nèi)存中的上傳數(shù)據(jù)，你可以用get()方法來(lái)獲得數(shù)據(jù)的二進(jìn)制數(shù)組形式。
// Process a file upload in memory
byte[] data = item.get();
...
第6章 清除資源
這一節(jié)只適用于你使用了DiskFileItem。換句話說(shuō)，它只適用于你在處理上傳文件之前將上傳文件寫(xiě)入過(guò)臨時(shí)文件這種情形。
像這種臨時(shí)文件會(huì)被自動(dòng)刪除， 如果它們不再被使用（更確切地說(shuō)，java.io.File的實(shí)例已經(jīng)被GC掉了。 ）這是由org.apache.commons.io.FileCleaner類(lèi)在后臺(tái)完成的，它會(huì)啟動(dòng)一個(gè)收割機(jī)線程。
這個(gè)收割機(jī)線程在它不再被需要時(shí)會(huì)被停止。在servlet環(huán)境里，這是通過(guò)指定一個(gè)名叫FileCleanerCleanup的servlet上下文監(jiān)聽(tīng)器來(lái)實(shí)現(xiàn)的。要做到這里，在你的web.xml增加下面的代碼：
<web-app>
...
<listener>
<listener-class>
org.apache.commons.fileupload.servlet.FileCleanerCleanup
</listener-class>
</listener>
...
</web-app>
不幸的是，事情到這里還沒(méi)完。如果你和下面的情況一樣，那么你就只需要按照上面的做，就可以清除資源了。
你使用的是commons-io 1.3或者更晚的版本。
你是從web應(yīng)用的web-inf/lib里載入commons-io的，并不是從其它位置，如Tomcat的common/lib下。
如果commons-io 1.3是從你的WEB容器的classpath里載入的，那么，下面的情況可能會(huì)出現(xiàn)：
建議你運(yùn)行兩個(gè)應(yīng)用，一個(gè)叫A，一個(gè)叫B。（這兩個(gè)應(yīng)用可能是完全一樣，只不過(guò)上下文名稱(chēng)不一樣。）這兩個(gè)應(yīng)用都使用了FileCleanerCleanup。現(xiàn)在，如果你終止應(yīng)用A，B還在運(yùn)行，這時(shí)，A會(huì)終止B的收割機(jī)線程。換言之，你要十分仔細(xì)地考慮是使用FileCleanerCleanup，還是不使用。
第7章 觀察上傳進(jìn)度
如果你希望可以上傳很大的文件，這時(shí)，你可能想將上傳的狀態(tài)告訴用戶(hù)，如已經(jīng)接收了多少。
觀察上傳進(jìn)度需要通過(guò)一個(gè)處理監(jiān)聽(tīng)器來(lái)實(shí)現(xiàn)。
//Create a progress listener
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);
上面這個(gè)監(jiān)聽(tīng)器是有問(wèn)題的。因?yàn)樗浅ｎl繁地被調(diào)用。這會(huì)帶來(lái)性能問(wèn)題。一個(gè)比較好的解決辦法是，減少調(diào)用。例如，如果megabytes被改變，那么就發(fā)出一個(gè)消息。
//Create a progress listener
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.");
}
}
};