DIV CSS 佈局教程網

掌控上傳進度的 AJAX Upload:Prototype + Servlet 實作
編輯:AJAX基礎知識     

動機

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 進行輪詢。

在我看來,該實作有兩點不足:

  1. 沒有用戶取消上傳的功能。
  2. 完全依賴 DWR,未使用 Prototype。對於不熟悉 DWR 的開發者存在知識門檻,而且 DWR 的個性使得它不易被整合進既有專案。

Prototype + Servlet 的實作


Prototype + Servlet 的 Example

基於研究 Prototype 的目的,我嘗試實作了一個 Prototype + Servlet 的簡單範例。工作流程如下:

  1. 表單提交上傳欄位的同時,以 Ajax 週期性地從 Servlet 輪詢上傳狀態。
  2. 依狀態資訊更新進度條與相關文字,即時反映傳輸情況。
  3. 若用戶取消上傳,進行清理:刪除已上傳的檔案,並在表單頁面顯示相關資訊。
  4. 若上傳完成,在表單頁面顯示已上傳的檔案內容或連結,也可與 Ajax SlideShow 之類的應用結合。

伺服器端:Bean 序列化

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 { ... }

上傳狀態 Bean

用 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 中。

Servlet 的實作

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 給開發者更多自由


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) 每兩秒輪詢一次;間隔太短會讓伺服器被狀態請求淹沒,反而拖慢真正的上傳。
  • 狀態必須與工作階段綁定。上傳請求與輪詢請求是兩個獨立的 HTTP 請求,能配對起來完全是靠 Session 中的 FileUploadStatus。若使用者開多個分頁同時上傳,這裡會互相干擾。
  • 檔案名稱不可直接採用。範例以 takeOutFileName() 過濾客戶端傳來的名稱,這一步是必要的——直接使用會有路徑穿越(path traversal)風險。
  • 取消只做「標記」。cancel 旗標是在下一輪迴圈才被檢查,因此取消並非即時生效;若追求即時中止,需要更進一步的設計。
  • 用 XML 傳狀態其實偏重。這個狀態物件結構單純,用 JSON 會更輕、解析更快;這也是後來業界普遍的選擇。

整體而言,這個實作示範了「非同步輪詢 + 伺服器端進度物件」這套通用骨架。掌握它之後,無論換成 Prototype、jQuery 或原生 fetch,前端只是替換通訊層;而後端真正需要保留的,是那個能隨時被查詢的上傳狀態。

圖片與資源來源:

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved