2006 年底搜尋 AJAX Upload 的實作,結果沒有找到完整的 Java 版本。僅存的成果是 TELIO 公司的 Pierre-Alexandre 發表的〈AJAX Upload progress monitor for Commons-FileUpload Example〉,附帶一支 ajax-upload-1.0.war。
該文完成上傳工作的部分是 Apache 的 Commons-FileUpload 元件,但程式中所用的 FileUpload 1.1 版並沒有 1.2 版才提供的上傳處理 Listener 功能,這使檢測上傳進度變得困難。我想正是這個原因,促使 Pierre-Alexandre 採取了 DWR + MonitoredDiskFileItem/MonitoredDiskFileItemFactory(分別繼承 DiskFileItem 與 DiskFileItemFactory)的做法:前者負責在瀏覽器端進行遠端呼叫;後者在讀取檔案資料時統計總量、已讀量與檔案數,並存進 Session,供瀏覽器透過 DWR 遠端呼叫 UploadMonitor.getUploadInfo 進行輪詢。
在我看來,該實作有兩點不足:
Prototype + Servlet 的 Example
基於研究 Prototype 的目的,我嘗試實作了一個 Prototype + Servlet 的簡單範例。工作流程如下:
XmlUnSerializer 這個類別雖然無法通吃任何形式的 Bean,但應付一般 Bean、帶有 Collection 型別屬性的 Bean 以及 Bean List 還是夠用的:
/**
* 將 bean 序列化為 UTF-8 編碼的 xml
*/
public static String serializeBean(Object beanObj) throws IOException { ... }
/**
* 將 bean 列表序列化為 UTF-8 編碼的 xml
*/
public static String serializeBeanList(Object beanListObj) throws IOException { ... }
用 FileUploadStatus 記錄上傳狀態,作為伺服器端與瀏覽器端溝通的媒介:伺服器把這個類別的物件序列化成 XML 送出,瀏覽器端再以 JavaScript 反序列化,取得對應的狀態物件。
private long uploadTotalSize = 0; // 上傳總量 private long readTotalSize = 0; // 已讀取上傳總量 private int currentUploadFileNum = 0; // 當前上傳檔案序號 private int successUploadFileCount = 0; // 成功讀取的檔案數 private String status = ""; // 狀態描述 private long processStartTime = 0l; // 處理起始時間 private long processEndTime = 0l; // 處理終止時間 private long processRunningTime = 0l; // 處理執行時間 private List uploadFileUrlList = new ArrayList(); // 上傳檔案 URL 清單 private boolean cancel = false; // 是否取消上傳 private String baseDir = ""; // 上傳基準目錄
改用 Commons-FileUpload 1.2 版(20070103)。此版本與 1.1 的關鍵差異,在於提供了能監視上傳情況的 ProgressListener 介面:開發者透過 FileUploadBase 的 setProgressListener 植入自己的 Listener,而實作這個介面相當簡單。
/**
* 更新狀態
*
* @param pBytesRead 已讀取位元組總數
* @param pContentLength 資料總長度
* @param pItems 當前正在被讀取的 field 序號
*/
public void update(long pBytesRead, long pContentLength, int pItems) {
FileUploadStatus status =
BackGroundService.takeOutFileUploadStatusBean(this.session);
logger.debug("當前正在處理第 " + pItems + " 個文件");
status.setUploadTotalSize(pContentLength);
if (pContentLength == -1) {
// 讀取完成
status.setStatus("完成對 " + pItems + " 個檔案的讀取:讀取了 " + pBytesRead + " bytes.");
status.setReadTotalSize(pBytesRead);
status.setSuccessUploadFileCount(pItems);
status.setProcessEndTime(System.currentTimeMillis());
status.setProcessRunningTime(status.getProcessEndTime());
} else {
// 讀取中
status.setStatus("當前正在處理第 " + pItems + " 個檔案:已讀取 "
+ pBytesRead + " / " + pContentLength + " bytes.");
status.setReadTotalSize(pBytesRead);
status.setCurrentUploadFileNum(pItems);
status.setProcessRunningTime(System.currentTimeMillis());
}
BackGroundService.storeFileUploadStatusBean(this.session, status);
}
很明顯,我也把 FileUploadStatus 存在 Session 中。
BackGroundService 這個 Servlet 負責三件事:接收表單 POST 資料、回應狀態輪詢請求、處理取消上傳的請求。雖然這些職責可以拆開(例如另建一個 FileUploadManager 類別),但為了簡單明瞭、易於閱讀,我把它們放在同一個 Servlet 中,僅以不同方法區隔。
/**
* 處理檔案上傳
*/
private void processFileUpload(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
DiskFileItemFactory factory = new DiskFileItemFactory();
factory.setSizeThreshold(10240000); // 記憶體閾值,超過後寫入暫存檔
factory.setRepository(new File(request.getRealPath("/upload/temp")));
ServletFileUpload upload = new ServletFileUpload(factory);
upload.setFileSizeMax(10240000); // 單一檔案大小上限
upload.setSizeMax(10240000); // 整個 request 的大小上限
upload.setProgressListener(new FileUploadListener(request.getSession()));
// 保存初始化後的 FileUploadStatus Bean
storeFileUploadStatusBean(request.getSession(),
initFileUploadStatusBean(request));
String forwardURL = "";
try {
List items = upload.parseRequest(request);
// 先取出用來決定返回路徑的表單欄位
for (int i = 0; i < items.size(); i++) {
FileItem item = (FileItem) items.get(i);
if (item.isFormField()) {
forwardURL = item.getString();
break;
}
}
for (int i = 0; i < items.size(); i++) {
FileItem item = (FileItem) items.get(i);
// 用戶取消上傳:刪除已上傳檔案並跳出
if (takeOutFileUploadStatusBean(request.getSession()).getCancel()) {
deleteUploadedFile(request);
break;
}
// 存檔
else if (!item.isFormField() && item.getName().length() > 0) {
String fileName = takeOutFileName(item.getName());
File uploadedFile = new File(
request.getRealPath(UPLOAD_DIR) + File.separator + fileName);
item.write(uploadedFile);
FileUploadStatus st =
takeOutFileUploadStatusBean(request.getSession());
st.getUploadFileUrlList().add(fileName);
storeFileUploadStatusBean(request.getSession(), st);
Thread.sleep(500);
}
}
} catch (FileUploadException e) {
uploadExceptionHandle(request, "上傳檔案時發生錯誤:" + e.getMessage());
} catch (Exception e) {
uploadExceptionHandle(request, "保存上傳檔案時發生錯誤:" + e.getMessage());
}
if (forwardURL.length() == 0) {
forwardURL = DEFAULT_UPLOAD_FAILURE_URL;
}
request.getRequestDispatcher(forwardURL).forward(request, response);
}
回應狀態輪詢與處理取消請求,各自都是短ifiable 的一段:
/**
* 回應上傳狀態查詢
*/
private void responseFileUploadStatusPoll(HttpServletRequest request,
HttpServletResponse response) throws IOException {
response.setContentType("text/xml");
response.setCharacterEncoding("UTF-8");
response.setHeader("Cache-Control", "no-cache");
response.getWriter().write(XmlUnSerializer.serializeBean(
request.getSession().getAttribute(UPLOAD_STATUS)));
}
/**
* 處理取消檔案上傳
*/
private void processCancelFileUpload(HttpServletRequest request,
HttpServletResponse response) throws IOException {
FileUploadStatus st =
(FileUploadStatus) request.getSession().getAttribute(UPLOAD_STATUS);
st.setCancel(true);
request.getSession().setAttribute(UPLOAD_STATUS, st);
responseFileUploadStatusPoll(request, response);
}
Prototype 給開發者更多的自由選擇
瀏覽器端用了兩個自製類別:AjaxWrapper 封裝 Ajax.Request,XMLDomForAjax 則負責把伺服器回傳的 XML 反序列化為 JavaScript 物件。
先解決 this 被重寫的問題
為了避免在 AjaxWrapper 的回呼方法中 this 被重寫,我用 ClassUtils 為任何類別的每個方法註冊一個對該物件自身的參照:
// 類別工具
var ClassUtils = Class.create();
ClassUtils.prototype = {
initialize: function() {},
/**
* 為類別的每個方法註冊一個對類別物件的自我參照
* @param reference 對類別物件的參照
*/
registerFuncSelfLink: function(reference) {
for (var n in reference) {
var item = reference[n];
if (item instanceof Function) {
item.$ = reference;
}
}
}
}
這個技巧的原理是:JavaScript 的方法在被當成回呼傳出去時,this 會指向呼叫它的上下文而非原本的物件。透過在函式物件上掛一個 $ 屬性指向自己,就能在方法內部用 arguments.callee.$ 取回正確的參照。
把 XML 反序列化為 JavaScript 物件
XMLDomForAjax 建立跨平台的 DOM 解析器(IE 走 ActiveXObject("Microsoft.XMLDOM"),其餘瀏覽器走 DOMParser),再走訪根節點下的每個 field 元素,依 type 屬性決定要轉成字串、數值還是陣列:
createDomParser: function(xml) {
if (window.ActiveXObject) {
var doc = new ActiveXObject("Microsoft.XMLDOM");
doc.async = "false";
doc.loadXML(xml);
} else {
var parser = new DOMParser();
var doc = parser.parseFromString(xml, "text/xml");
}
return doc;
}
deserializedBeanFromXML: function(xml) {
var funcHolder = arguments.callee.$;
var doc = funcHolder.createDomParser(xml);
var objDomTree = doc.documentElement; // documentElement 總是文件的 root
var obj = new Object();
for (var i = 0; i < objDomTree.childNodes.length; i++) {
var node = objDomTree.childNodes[i];
if (node.nodeType == funcHolder.ELEMENT_NODE && node.tagName == 'field') {
var nodeText = funcHolder.getNodeText(node);
var type = node.getAttribute('type');
var value;
if (type == 'java.util.List') {
value = value || new Array();
if (nodeText.length > 0) value[value.length] = nodeText;
} else if (type == 'long' || type == 'java.lang.Long'
|| type == 'int' || type == 'java.lang.Integer') {
value = parseInt(nodeText);
} else if (type == 'double' || type == 'float'
|| type == 'java.lang.Double' || type == 'java.lang.Float') {
value = parseFloat(nodeText);
} else {
value = nodeText; // java.lang.String 及其他
}
obj[node.getAttribute('name')] = value;
}
}
return obj;
}
其中 getNodeText() 採遞迴寫法,把節點底下所有文字節點與 CDATA 內容拼接起來:
getNodeText: function(node) {
var funcHolder = arguments.callee.$;
if (node.nodeType == funcHolder.TEXT_NODE
|| node.nodeType == funcHolder.CDATA_SECTION_NODE) {
return node.data;
}
var returnValue = [];
for (var i = 0; i < node.childNodes.length; i++) {
returnValue.push(funcHolder.getNodeText(node.childNodes[i]));
}
return returnValue.join('');
}
AjaxWrapper 的核心方法
/**
* 以 get 方式向 server 發送 request
* @param url
* @param params
* @param callBackFunction 發送成功後回呼的函式或函式名
*/
putRequest: function(url, params, callBackFunction) {
var funcHolder = arguments.callee.$;
new Ajax.Request(url, {
method: 'get',
parameters: params,
requestHeaders: ['my-header-encoding', 'utf-8'],
onFailure: function() {
alert('對不起,網路通訊失敗,請重新整理!');
},
onSuccess: function(transport) {},
onComplete: function(transport) {
funcHolder.callBackHandler.apply(funcHolder, [transport, callBackFunction]);
}
});
},
/**
* 遠端呼叫的回呼處理
*/
callBackHandler: function(transport, callBackFunction) {
var funcHolder = arguments.callee.$;
if (transport.status != 200) {
alert("獲得回應失敗,請求狀態:" + transport.status);
} else {
funcHolder.xml_source = transport.responseText;
if (typeof callBackFunction == 'function') {
callBackFunction(transport.responseText);
} else {
new execute().evalFunc(callBackFunction, transport.responseText);
}
}
}
頁面上的主要方法
// 刷新上傳狀態
function refreshUploadStatus() {
var ajaxW = new AjaxWrapper(false);
ajaxW.putRequest('./uploadStatus.action', 'uploadStatus=',
function(responseText) {
var deserialor = new XMLDomForAjax(false);
var uploadInfo = deserialor.deserializedBeanFromXML(responseText);
var progressPercent = Math.ceil(
uploadInfo.readTotalSize / uploadInfo.uploadTotalSize * 100);
$('progressBarText').innerHTML =
' 上傳處理進度: ' + progressPercent + '% ['
+ uploadInfo.readTotalSize + '/' + uploadInfo.uploadTotalSize
+ ' bytes] 正在處理第' + uploadInfo.currentUploadFileNum + '個檔案'
+ ' 耗時: '
+ (uploadInfo.processRunningTime - uploadInfo.processStartTime) + ' ms';
$('progressStatusText').innerHTML = ' 反饋狀態: ' + uploadInfo.status;
$('totalProgressBarBoxContent').style.width =
parseInt(progressPercent * 3.5) + 'px';
});
}
// 開始上傳處理
function startProgress() {
Element.show('progressBar');
$('progressBarText').innerHTML = ' 上傳處理進度: 0%';
$('progressStatusText').innerHTML = ' 反饋狀態:';
$('uploadButton').disabled = true;
new PeriodicalExecuter(refreshUploadStatus, 2);
return true;
}
// 取消上傳處理
function cancelProgress() {
$('cancelUploadButton').disabled = true;
var ajaxW = new AjaxWrapper(false);
ajaxW.putRequest('./uploadStatus.action', 'cancelUpload=true',
function(responseText) {
// 因為表單正在提交,這段可能不會執行
...
});
}
起始頁面
上傳進行中
上傳完成後的檔案清單
用戶取消上傳後顯示的頁面
上傳過程中出錯(檔案過大)
PeriodicalExecuter(fn, 2) 每兩秒輪詢一次;間隔太短會讓伺服器被狀態請求淹沒,反而拖慢真正的上傳。FileUploadStatus。若使用者開多個分頁同時上傳,這裡會互相干擾。takeOutFileName() 過濾客戶端傳來的名稱,這一步是必要的——直接使用會有路徑穿越(path traversal)風險。cancel 旗標是在下一輪迴圈才被檢查,因此取消並非即時生效;若追求即時中止,需要更進一步的設計。整體而言,這個實作示範了「非同步輪詢 + 伺服器端進度物件」這套通用骨架。掌握它之後,無論換成 Prototype、jQuery 或原生 fetch,前端只是替換通訊層;而後端真正需要保留的,是那個能隨時被查詢的上傳狀態。
圖片與資源來源: