Przykład obsługi błędów: aplikacja CustomErrors

Po załadowaniu aplikacji Flex wywoływana jest metoda initApp() , natomiast w przypadku aplikacji dla środowiska Flash Professional wykonywany jest kod (nie funkcje) osi czasu. Ten kod definiuje przykładowy pakiet XML, który zostanie sprawdzony przez klasę Validator. Uruchamiany jest następujący kod:

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

Pakiet XML wyświetlany jest później w instancji składnika TextArea stołu montażowego. Ten krok umożliwia zmodyfikowanie pakietu XML przed próbą ponownego sprawdzenia jego poprawności.

Po kliknięciu przycisku Validate wywołana zostanie metoda validateData() . Metoda ta sprawdza poprawność pakietu XML pracownika za pomocą metody validateEmployeeXML() klasy Validator. Poniższy kod przedstawia metodę 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); 
    } 
}

Najpierw jest tworzony tymczasowy obiekt XML z użyciem treści instancji składnika TextArea o nazwie xmlText . Następnie wywoływana jest metoda validateEmployeeXML() niestandardowej klasy Validator (com.example.programmingas3/errors/Validator.as), która przekazuje tymczasowy obiekt XML jako parametr. Jeśli pakiet XML jest poprawny, instancja status składnika Label wyświetla komunikat o powodzeniu operacji, a aplikacja kontynuuje działanie. Jeśli metoda validateEmployeeXML() wygeneruje niestandardowy błąd (tj. pojawi się błąd FatalError, WarningError lub ogólny Error), wykonana zostanie właściwa instrukcja catch i wywołana metoda showFatalError() , showWarningError() lub showGenericError() . Każda z metod wyświetla właściwy komunikat w obszarze tekstowym o nazwie statusTex w celu powiadomienia użytkownika o pojawieniu się konkretnego błędu. Każda metoda aktualizuje także instancję status składnika Label konkretnym komunikatem.

Jeśli podczas próby sprawdzenia poprawności pakietu XML pracownika pojawi się błąd, w obszarze tekstowym statusText wyświetlony zostanie komunikat o błędzie, a instancja xmlText składnika TextArea i instancja validateBtn składnika Button są wyłączone tak, jak przedstawione to zostało w poniższym kodzie:

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(); 
}

Jeśli zamiast błędu krytycznego pojawi się ostrzeżenie, komunikat o błędzie zostanie wyświetlony w instancji statusText składnika TextArea, ale instancja xmlText składnika TextField i instancja składnika Button nie są wyłączone. Metoda showWarningError() wyświetla niestandardowy komunikat o błędzie w obszarze tekstowym statusText . Komunikat zawiera również pytanie o kontynuowanie sprawdzania poprawności XML lub przerwanie skryptu. Poniższy kod przedstawia fragment metody 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; 
}

Po kliknięciu przez użytkownika przycisku Yes lub No wywołana zostanie metoda closeHandler() . Poniższy kod przedstawia fragment metody closeHandler() :

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

Jeśli użytkownik przerwie skrypt, klikając przycisk Yes, wygenerowany zostanie błąd FatalError, który spowoduje zamknięcie aplikacji.

Niestandardowa klasa Validator zawiera jedną metodę - validateEmployeeXML() . Metoda validateEmployeeXML() pobiera jeden argument ( employee ), który jest pakietem XML, w celu sprawdzenia jego poprawności. Metoda validateEmployeeXML() jest następująca:

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); 
    } 
}

Aby poprawność pracownika została sprawdzona, pracownik musi należeć do jednego (i tylko jednego) centrum kosztowego. Jeśli pracownik nie należy do żadnego centrum kosztowego, metoda wygeneruje błąd FatalError, który zostanie rozpropagowany do metody validateData() głównego pliku aplikacji. Jeśli pracownik należy do więcej niż jednego centrum kosztowego, zostanie wygenerowany błąd WarningError. Końcowe sprawdzenie w module sprawdzania poprawności XML obejmuje sprawdzenie, czy dla użytkownika zdefiniowano dokładnie jeden numer ubezpieczenia społecznego (węzeł ssn w pakiecie XML). Jeśli nie istnieje dokładnie jeden węzeł ssn , zostanie wygenerowany błąd FatalError.

Można dodać kolejne punkty sprawdzania do metody validateEmployeeXML() — np. aby zapewnić, że węzeł ssn zawiera poprawny numer lub że pracownik posiada zdefiniowany co najmniej jeden numer telefonu oraz adres e-mail i obie wartości są poprawne. Programista może także zmodyfikować XML tak, aby każdy pracownik posiadał unikalne ID oraz określone ID swojego kierownika.

Klasa ApplicationError pełni rolę bazowej klasy błędu dla obu klas FatalError i WarningError. Klasa ApplicationError rozszerza klasę Error i definiuje własne, niestandardowe metody i właściwości, łącznie z definiowaniem ID błędu, poziom istotności oraz obiektu XML, który zawiera kody oraz komunikaty niestandardowego błędu. Ta klasa definiuje także dwie stałe statyczne, używane do definiowania poziom istotności dla każdego typu błędu.

Metoda konstruktora klasy ApplicationError jest następująca:

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>; 
}

Każdy węzeł błędu w obiekcie XML zawiera unikalny kod numeryczny oraz komunikat o błędzie. Komunikaty o błędzie można łatwo wyszukać na podstawie ich kodu błędu za pomocą E4X, co przedstawia poniżej metoda getMessageText() :

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

Metoda getMessageText() pobiera pojedynczy argument w postaci liczby całkowitej ( id ) i zwraca ciąg znaków. Argument id jest kodem błędu do wyszukania błędu. Na przykład: przekazanie argumentu id o wartości 9001 spowoduje pobranie błędu, mówiącego o tym, że pracownicy muszą być przypisani tylko do jednego centrum kosztowego. Jeśli co najmniej jeden błąd ma ten sam kod błędu, w języku ActionScript zwracany jest komunikat o błędzie tylko dla pierwszego wyszukanego wyniku ( message[0] w zwróconym obiekcie XMLList).

Kolejna metoda w klasie — getTitle() — nie przyjmuje żadnych parametrów i zwraca wartość w postaci ciągu znaków, która zawiera ID błędu dla konkretnego błędu. Ta wartość używana jest w celu ułatwienia identyfikacji właściwego błędu, który pojawił się podczas sprawdzania poprawności pakietu XML. Poniższy kod przedstawia fragment metody getTitle() :

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

Ostatnią metodą klasy ApplicationError jest metoda toString(). Ta metoda zastępuje funkcję zdefiniowaną w klasie Error tak, aby możliwe było dostosowanie prezentacji komunikatu o błędzie. Metoda zwraca ciąg znaków, który identyfikuje konkretny numer i komunikat błędu, który się pojawił.

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

Klasa FatalError rozszerza niestandardową klasę ApplicationError oraz definiuje trzy metody: konstruktor FatalError, getTitle() oraz toString() . Pierwsza metoda (konstruktor FatalError) przyjmuje jeden argument w postaci liczby całkowitej ( errorID ) i ustawia poziom istotności błędu za pomocą wartości stałych statycznych w klasie ApplicationError i pobiera konkretny komunikat o błędzie przez wywołanie metody getMessageText() klasy ApplicationError. Konstruktory klasy FatalError:

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

Kolejna metoda klasy FatalError ( getTitle() ) zastępuje metodę getTitle() zdefiniowaną wcześniej w klasie ApplicationError i dołącza tekst „-- FATAL” w tytule, aby poinformować użytkownika o pojawieniu się błędu krytycznego. Metoda getTitle() jest następująca:

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

Ostatnia metoda tej klasy — toString() — zastępuje metodę toString() zdefiniowaną w klasie ApplicationError. Metoda toString() to:

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

Klasa WarningError rozszerza klasę ApplicationError jest prawie identyczna z klasą FatalError poza kilkoma mniejszymi zmianami ciągu znaków; ustawia poziom istotności błędu na wartość ApplicationError.WARNING zamiast ApplicationError.FATAL, co przedstawia poniższy kod:

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