Beispiel: Anwendung „CustomErrors" -- Flash CS3

Die Anwendung „CustomErrors" veranschaulicht Techniken für den Einsatz benutzerdefinierter Fehler beim Erstellen von Anwendungen. Dies sind im Einzelnen:

Die Anwendungsdateien für dieses Beispiel finden Sie unter www.adobe.com/go/learn_programmingAS3samples_flash_de. Die Dateien der Anwendung „CustomErrors" befinden sich im Ordner „Samples/CustomError". Die Anwendung umfasst die folgenden Dateien:

Datei	Beschreibung
CustomErrors.mxml oder CustomErrors.fla	Die Hauptanwendungsdatei im Flash-Format (FLA) oder Flex-Format (MXML).
com/example/programmingas3/errors/ApplicationError.as	Eine Klasse, die als Basisklasse für die beiden Fehlerklassen FatalError und WarningError dient.
com/example/programmingas3/errors/FatalError.as	Eine Klasse, die einen FatalError-Fehler definiert, der in der Anwendung ausgelöst werden kann. Diese Klasse erweitert die benutzerdefinierte ApplicationError-Klasse.
com/example/programmingas3/errors/Validator.as	Eine Klasse mit einer einzelnen Methode, mit der ein vom Benutzer bereitgestelltes XML-Paket mit Mitarbeiterdaten validiert wird.
com/example/programmingas3/errors/WarningError.as	Eine Klasse, die einen WarningError-Fehler definiert, der in der Anwendung ausgelöst werden kann. Diese Klasse erweitert die benutzerdefinierte ApplicationError-Klasse.

Unterthemen

Überblick über die Anwendung „CustomErrors"

Die Datei „CustomErrors.mxml" enthält die Benutzeroberfläche und die Programmlogik für die Beispielanwendung zu benutzerdefinierten Fehlern. Wenn das creationComplete-Ereignis der Anwendung ausgelöst wurde, wird die initApp()-Methode aufgerufen. Diese Methode definiert ein XML-Beispielpaket, das mit der Validator-Klasse validiert wird. Im folgenden Code wird die initApp()-Methode veranschaulicht:

private function initApp():void
{
    employeeXML = 
        <employee id="12345">
            <firstName>John</firstName>
            <lastName>Doe</lastName>
            <costCenter>12345</costCenter>
            <costCenter>67890</costCenter>
        </employee>;
}

Das XML-Paket wird später in einer Instanz der TextArea-Komponente auf der Bühne angezeigt. Dadurch können Sie das XML-Paket bearbeiten, bevor Sie es erneut validieren.

Wenn der Benutzer auf die Schaltfläche „Validate" klickt, wird die validateData()-Methode aufgerufen. Diese Methode validiert das XML-Paket mit den Mitarbeiterdaten mithilfe der validateEmployeeXML()-Methode der Validator-Klasse. Im folgenden Code wird die validateData()-Methode veranschaulicht:

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

Zuerst wird mithilfe des Inhalts der TextArea-Komponenteninstanz xmlText ein temporäres XML-Objekt erstellt. Dann wird die validateEmployeeXML()-Methode der benutzerdefinierten Validator-Klasse („com.example.programmingas3/errors/Validator.as") aufgerufen. Das temporäre XML-Objekt wird als Parameter übergeben. Wenn das XML-Paket gültig ist, wird in der Label-Komponenteninstanz status eine Erfolgsmeldung angezeigt und die Anwendung beendet. Wenn die validateEmployeeXML()-Methode einen benutzerdefinierten Fehler auslöst (d. h. beim Auftreten von FatalError, WarningError oder eines generischen Error-Ereignisses), wird die entsprechende catch-Anweisung ausgeführt, die eine der Methoden showFatalError(), showWarningError() oder showGenericError() aufruft. Mit jeder dieser Methoden wird in einer Alert-Komponente eine entsprechende Meldung angezeigt, um den Benutzer über den genauen Fehler zu informieren. Alle diese Methoden aktualisieren auch die Label-Komponenteninstanz status mit einer speziellen Meldung.

Wie aus dem folgenden Codebeispiel hervorgeht, wird beim Auftreten eines schwerwiegenden Fehlers während des Validierens des XML-Pakets die Fehlermeldung in einer Alert-Komponente angezeigt und die TextArea-Komponenteninstanz xmlText sowie die Button-Komponenteninstanz validateBtn deaktiviert:

public function showFatalError(error:FatalError):void
{
    var message:String = error.message + "\n\n" + "Click OK to end.";
    var title:String = error.getTitle();
    Alert.show(message, title);
    status.text = "This application has ended.";
    this.xmlText.enabled = false;
    this.validateBtn.enabled = false;
}

Wenn anstelle eines schwerwiegenden Fehlers eine Warnung ausgelöst wird, wird die Fehlermeldung in einer Alert-Komponenteninstanz angezeigt, die TextArea- und die Button-Komponenteninstanzen werden jedoch nicht deaktiviert. Die showWarningError()-Methode zeigt die benutzerdefinierte Fehlermeldung in der Alert-Komponenteninstanz an. In der Meldung wird der Benutzer auch aufgefordert zu entscheiden, ob das Validieren des XML-Pakets fortgesetzt oder das Skript beendet werden soll. Im folgenden Codeauszug wird die showWarningError()-Methode veranschaulicht:

public function showWarningError(error:WarningError):void
{
    var message:String = error.message + "\n\n" + "Do you want to exit this application?";
    var title:String = error.getTitle();
    Alert.show(message, title, Alert.YES | Alert.NO, null, closeHandler);
    status.text = message;
}

Wenn der Benutzer die Alert-Komponenteninstanz durch Klicken auf eine der Schaltflächen „Ja" oder „Nein" schließt, wird die closeHandler()-Methode aufgerufen. Im folgenden Codeauszug wird die closeHandler()-Methode veranschaulicht:

private function closeHandler(event:CloseEvent):void
{
    switch (event.detail)
    {
        case Alert.YES:
            showFatalError(new FatalError(9999));
            break;
        case Alert.NO:
            break;
    }
}

Wenn sich der Benutzer dafür entscheidet, das Skript durch Klicken auf die Schaltfläche „Ja" des Warnmeldungsdialogfelds abzubrechen, wird eine FatalError-Ausnahme ausgelöst, die das Beenden der Anwendung zur Folge hat.

Erstellen einer benutzerdefinierten Validator-Klasse

Die benutzerdefinierte Validator-Klasse enthält eine einzige Methode: validateEmployeeXML(). Die validateEmployeeXML()-Methode hat nur einen Parameter: employee. Dies ist das zu validierende XML-Paket. Es folgt die validateEmployeeXML()-Methode:

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

Für eine erfolgreiche Validierung muss ein Mitarbeiter einer (und nur einer) Kostenstelle angehören. Wenn der Mitarbeiter keiner Kostenstelle angehört, löst die Methode eine FatalError-Ausnahme aus, die durch Bubbles die validateData()-Methode in der Datei der Hauptanwendung erreicht. Wenn der Mitarbeiter mehreren Kostenstellen angehört, wird eine WarningError-Ausnahme ausgelöst. Bei der letzten Überprüfung durch den XML-Validator wird sichergestellt, dass für den Mitarbeiter genau eine Sozialversicherungsnummer definiert ist (der ssn-Knoten des XML-Pakets). Wenn es nicht genau einen ssn-Knoten gibt, wird der FatalError-Fehler ausgelöst.

Sie können der validateEmployeeXML()-Methode zusätzliche Tests hinzufügen, beispielsweise um sicherzustellen, dass der ssn-Knoten eine gültige Nummer enthält oder dass für den Mitarbeiter mindestens eine Telefonnummer und E-Mail-Adresse definiert sind und beide Werte gültig sind. Sie können die XML-Daten auch dahingehend ändern, dass jeder Mitarbeiter über eine eindeutige ID verfügt und die ID des Vorgesetzten angegeben wird.

Definieren der ApplicationError-Klasse

Die ApplicationError-Klasse dient als Basisklasse für die beiden Fehlerklassen FatalError und WarningError. Die ApplicationError-Klasse erweitert die Error-Klasse und definiert benutzerdefinierte Methoden und Eigenschaften. Dazu gehören eine Fehler-ID, der Schweregrad und ein XML-Objekt mit den Fehlercodes und Fehlermeldungen. Diese Klasse definiert auch zwei statische Konstanten, die zur Angabe des Schweregrads des jeweiligen Fehlertyps verwendet werden.

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

Jeder Fehlerknoten im XML-Objekt enthält einen eindeutigen numerischen Code und eine Fehlermeldung. Fehlermeldungen können mit E4X problemlos anhand des entsprechenden Fehlercodes ermittelt werden, wie mit der folgenden getMessageText()-Methode veranschaulicht wird:

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

Die getMessageText()-Methode erwartet das ganzzahlige Argument id und gibt einen String zurück. Das Argument id ist der Fehlercode des nachzuschlagenden Fehlers. Beispielsweise wird beim Übergeben von „9001" für id die Fehlermeldung zurückgegeben, dass Mitarbeiter nur einer Kostenstelle zugeordnet sein dürfen. Wenn mehrere Fehler mit demselben Fehlercode vorhanden sind, wird nur die Fehlermeldung für das erste gefundene Ergebnis (message[0] im XMLList-Ergebnisobjekt) zurückgegeben.

Die nächste Methode dieser Klasse, getTitle(), erfordert keine Parameter und gibt einen Stringwert mit der Fehler-ID dieses spezifischen Fehlers zurück. Der Wert wird im Titel der Alert-Komponente verwendet, damit Sie den genauen Fehler besser identifizieren können, der beim Validieren des XML-Pakets aufgetreten ist. Im folgenden Codeauszug wird die getTitle()-Methode veranschaulicht:

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

Die letzte Methode der ApplicationError-Klasse ist toString(). Diese Methode überschreibt die in der Error-Klasse definierte Funktion, damit Sie die Darstellung der Fehlermeldungen anpassen können. Die Methode gibt einen String zurück, der die jeweilige Fehlernummer und Fehlermeldung für den aufgetretenen Fehler enthält.

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

Definieren der FatalError-Klasse

Die FatalError-Klasse erweitert die benutzerdefinierte ApplicationError-Klasse und definiert drei Methoden: den FatalError-Konstruktor, getTitle() und toString(). Die erste Methode, der FatalError-Konstruktor, erwartet als einziges Argument eine Ganzzahl, errorID. Der Schweregrad des Fehlers wird dann mithilfe der in der ApplicationError-Klasse definierten Konstanten festgelegt. Durch Aufrufen der getMessageText()-Methode der ApplicationError-Klasse wird die entsprechende Fehlermeldung ermittelt. Es folgt der FatalError-Konstruktor:

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

Die nächste Methode der FatalError-Klasse, getTitle(), überschreibt die zuvor in der ApplicationError-Klasse definierte getTitle()-Methode und fügt dem Titel den Text „-- FATAL" hinzu, um den Benutzer über das Auftreten eines schwerwiegenden Fehlers zu informieren. Die getTitle()-Methode wird wie folgt ausgeführt:

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

Die letzte Methode dieser Klasse, toString(), überschreibt die in der ApplicationError-Klasse definierte toString()-Methode. Es folgt die toString()-Methode:

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

Definieren der WarningError-Klasse

Die WarningError-Klasse erweitert die ApplicationError-Klasse und ist fast identisch mit der FatalError-Klasse. Wie aus dem folgenden Code ersichtlich ist, unterscheidet sie sich nur durch geringfügige Stringänderungen und das Setzen des Fehlerschweregrads auf ApplicationError.WARNING anstelle auf ApplicationError.FATAL:

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