處理錯誤範例：CustomErrors 應用程式

當應用程式載入時，會在 Flex 應用程式中呼叫 initApp() 方法，或在 Flash Professional 應用程式中執行時間軸 (非函數) 程式碼。此程式碼會定義 Validator 類別所要驗證的樣本 XML 封包。此時會執行下列程式碼：

employeeXML =  
    <employee id="12345"> 
        <firstName>John</firstName> 
        <lastName>Doe</lastName> 
        <costCenter>12345</costCenter> 
        <costCenter>67890</costCenter> 
    </employee>; 
}

XML 封包稍後將顯示在「舞台」的 TextArea 組件實體上。這個步驟可以讓您在嘗試重新驗證 XML 封包前加以修改。

當使用者按下「驗證」按鈕時，就會呼叫 validateData() 方法。這個方法會使用 Validator 類別中的 validateEmployeeXML() 方法，驗證 employee XML 封包。下列程式碼會顯示 validateData() 方法：

function validateData():void 
{ 
    try 
    { 
        var tempXML:XML = XML(xmlText.text); 
        Validator.validateEmployeeXML(tempXML); 
        status.text = "The XML was successfully validated."; 
    } 
    catch (error:FatalError) 
    { 
        showFatalError(error); 
    } 
    catch (error:WarningError) 
    { 
        showWarningError(error); 
    } 
    catch (error:Error) 
    { 
        showGenericError(error); 
    } 
}

首先，會使用 TextArea 組件實體 xmlText 的內容，建立暫時性的 XML 物件。接著呼叫自訂 Validator 類別 (com.example.programmingas3/errors/Validator.as) 中的 validateEmployeeXML() 方法，並將暫時性的 XML 物件當做參數來傳遞。如果 XML 封包有效，status Label 組件實體就會顯示成功的訊息，而應用程式也會結束。如果 validateEmployeeXML() 方法擲回自訂錯誤 (也就是 FatalError、WarningError 或一般 Error)，則會執行適當的 catch 陳述式，並呼叫 showFatalError()、showWarningError() 或 showGenericError() 方法。這些方法都會在名為 statusText 文字區域中顯示適當的訊息，明確通知使用者發生了什麼錯誤。每一種方法也都會以明確的訊息，更新 status Label 組件實體。

如果在嘗試驗證 employee XML 封包時發生嚴重錯誤，則會在 statusText 文字區域中顯示錯誤訊息，而且 xmlText TextArea 組件實體和 validateBtn Button 組件實體都會停用，如下列程式碼所示：

function showFatalError(error:FatalError):void 
{ 
    var message:String = error.message + "\n\n"; 
    var title:String = error.getTitle(); 
    statusText.text = message + " " + title + "\n\nThis application has ended."; 
    this.xmlText.enabled = false; 
    this.validateBtn.enabled = false; 
    hideButtons(); 
}

如果發生的是警告錯誤而非嚴重錯誤，錯誤訊息同樣會顯示在 statusText TextArea 實體中，但是並不會停用 xmlText TextField 和 Button 組件實體。showWarningError() 方法會在 statusText 文字區域中顯示自訂錯誤訊息。此訊息也會要求使用者決定，看是要繼續驗證 XML 還是要取消指令碼。下列摘錄會顯示 showWarningError() 方法：

function showWarningError(error:WarningError):void 
{ 
    var message:String = error.message + "\n\n" + "Do you want to exit this application?"; 
    showButtons(); 
    var title:String = error.getTitle(); 
    statusText.text = message; 
}

當使用者按一下「是」或「否」按鈕時，會呼叫 closeHandler() 方法。下列摘錄會顯示 closeHandler() 方法：

function closeHandler(event:CloseEvent):void 
{ 
    switch (event.detail) 
    { 
        case yesButton: 
            showFatalError(new FatalError(9999)); 
            break; 
        case noButton: 
            statusText.text = ""; 
            hideButtons(); 
            break; 
    } 
}

如果使用者選擇按一下「是」來中止指令碼，則會擲回 FatalError，並造成應用程式終止。

自訂的 Validator 類別包含單一方法 validateEmployeeXML()。validateEmployeeXML() 方法接受單一引數 employee，而這就是您要驗證的 XML 封包。validateEmployeeXML() 方法如下所示：

public static function validateEmployeeXML(employee:XML):void 
{ 
    // checks for the integrity of items in the XML 
    if (employee.costCenter.length() < 1) 
    { 
        throw new FatalError(9000); 
    } 
    if (employee.costCenter.length() > 1) 
    { 
        throw new WarningError(9001); 
    } 
    if (employee.ssn.length() != 1) 
    { 
        throw new FatalError(9002); 
    } 
}

您要驗證的員工必須屬於一個 (唯一一個) 成本中心。如果員工不屬於任何成本中心，此方法便會擲回 FatalError，並反昇至主應用程式檔案中的 validateData() 方法。如果員工屬於一個以上的成本中心，則會擲回 WarningError。XML 驗證工具的最終檢查，是使用者只有一個所定義的社會安全號碼 (XML 封包中的 ssn 節點)。如果 ssn 節點不是剛好一個，則會擲回 FatalError 錯誤。

您可以為 validateEmployeeXML() 方法新增其它檢查。例如，為確定 ssn 節點包含有效數字，或是員工至少定義了一個電話號碼和電子郵件位址，而且這兩個值都是有效的。您也可以修改 XML，讓每位員工都有唯一的 ID，並指定其經理的 ID。

ApplicationError 類別可做為 FatalError 和 WarningError 類別的基底類別。ApplicationError 類別會擴充 Error 類別，同時定義自己的自訂方法和屬性，包括定義錯誤 ID、嚴重性，以及包含自訂錯誤代碼和訊息的 XML 物件。此類別也會定義兩個靜態常數，用來定義每種錯誤類型的嚴重性。

ApplicationError 類別的建構函式方法如下所示：

public function ApplicationError() 
{ 
    messages =  
        <errors> 
            <error code="9000"> 
                <![CDATA[Employee must be assigned to a cost center.]]> 
            </error> 
            <error code="9001"> 
                <![CDATA[Employee must be assigned to only one cost center.]]> 
            </error> 
            <error code="9002"> 
                <![CDATA[Employee must have one and only one SSN.]]> 
            </error> 
            <error code="9999"> 
                <![CDATA[The application has been stopped.]]> 
            </error> 
        </errors>; 
}

XML 物件中的每個錯誤節點都包含唯一的數值代碼和錯誤訊息。您可以使用 E4X，藉由錯誤碼輕鬆地查詢錯誤訊息，如下列 getMessageText() 方法所示：

public function getMessageText(id:int):String 
{ 
    var message:XMLList = messages.error.(@code == id); 
    return message[0].text(); 
}

getMessageText() 方法會採用單一整數引數 id，並且傳回字串。id 引數就是您要查詢的錯誤代碼。例如，若您傳遞的 id 為 9001，則會擷取到一個錯誤，告訴您只能為員工指定一個成本中心。如果有一個以上的錯誤具有相同的錯誤代碼，ActionScript 只會針對第一個找到的結果 (所傳回 XMLList 物件中的 message[0]) 傳回錯誤訊息。

此 getTitle() 類別中的下一個方法不會採用任何參數，並且會傳回字串值，其中內含此一特定錯誤的錯誤 ID。此值用於協助您輕鬆識別在驗證 XML 封包期間，所發生的明確錯誤。下列摘錄會顯示 getTitle() 方法：

public function getTitle():String 
{ 
    return "Error #" + id; 
}

ApplicationError 類別中的最後一個方法是 toString()。這個方法會覆寫 Error 類別所定義的函數，讓您自訂錯誤訊息的顯示方式。方法會傳回字串，用以識別特定的錯誤號碼以及所發生的訊息。

public override function toString():String 
{ 
    return "[APPLICATION ERROR #" + id + "] " + message; 
}

FatalError 類別會擴充自訂的 ApplicationError 類別，並定義三種方法：FatalError 建構函式、getTitle() 以及 toString()。第一種方法是 FatalError 建構函式，它會採用單一整數引數 errorID，並使用 ApplicationError 類別中定義的靜態常數值來設定錯誤的嚴重性，以及呼叫 ApplicationError 類別的 getMessageText() 方法，取得特定錯誤的錯誤訊息。FatalError 建構函式如下所示：

public function FatalError(errorID:int) 
{ 
    id = errorID; 
    severity = ApplicationError.FATAL; 
    message = getMessageText(errorID); 
}

FatalError 類別的下一個方法是 getTitle()，它會覆寫之前在 ApplicationError 類別中定義的 getTitle() 方法，並將文字「-- FATAL」附加到標題中，通知使用者發生了嚴重錯誤。getTitle() 方法如下所示：

public override function getTitle():String 
{ 
    return "Error #" + id + " -- FATAL"; 
}

此類別最後一個方法是 toString()，會覆寫 ApplicationError 類別中定義的 toString() 方法。toString() 方法是

public override function toString():String 
{ 
    return "[FATAL ERROR #" + id + "] " + message; 
}

WarningError 類別會擴充 ApplicationError 類別，而且幾乎和 FatalError 類別相同，只有幾個字串的小變動，以及將錯誤嚴重性設定為 ApplicationError.WARNING 而非 ApplicationError.FATAL，如下列程式碼所示：

public function WarningError(errorID:int) 
{ 
    id = errorID; 
    severity = ApplicationError.WARNING; 
    message = super.getMessageText(errorID); 
}