Exemple : Application CustomErrors -- Flash CS3

L'application CustomErrors décrit les techniques d'utilisation des erreurs personnalisées lors de la création d'une application. Ces techniques sont les suivantes :

Pour obtenir les fichiers d'application pour cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers d'application CustomErrors se trouvent dans le dossier Samples/CustomError. Cette application se compose des fichiers suivants :

Fichier	Description
CustomErrors.mxml ou CustomErrors.fla	Le fichier d'application principal dans Flash (FLA) ou Flex (MXML)
com/example/programmingas3/errors/ApplicationError.as	Une classe servant de classe d'erreur de base pour les classes FatalError et WarningError.
com/example/programmingas3/errors/FatalError.as	Une classe qui définit une erreur FatalError qui peut être renvoyée par l'application. Cette classe étend la classe ApplicationError personnalisée.
com/example/programmingas3/errors/Validator.as	Une classe qui définit une seule méthode qui valide un paquet XML employee fourni par l'utilisateur.
com/example/programmingas3/errors/WarningError.as	Une classe qui définit une erreur WarningError qui peut être renvoyée par l'application. Cette classe étend la classe ApplicationError personnalisée.

Sous-rubriques

Présentation de l'application CustomErrors

Le fichier CustomErrors.mxml contient l'interface utilisateur et une logique pour l'application d'erreur personnalisée. Une fois que l'événement creationComplete de l'application est distribué, la méthode initApp() est appelée. Cette méthode définit un exemple de paquet XML que la classe Validator vérifiera. Le code suivant présente la méthode initApp() :

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

Le paquet XML est ensuite affiché dans une occurrence de composant TextArea sur la scène. Ceci vous permet de modifier le paquet XML avant de tenter de le revalider.

Lorsque l'utilisateur clique sur le bouton de validation, la méthode validateData() est appelée. Cette méthode valide le paquet XML employee à l'aide de la méthode validateEmployeeXML() dans la classe Validator. Le code suivant présente la méthode validateData() :

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

Un objet XML temporaire est d'abord créé à l'aide du contenu de l'occurrence de composant TextArea xmlText. Ensuite, la méthode validateEmployeeXML() dans la classe Validator personnalisée (com.example.programmingas3/errors/Validator.as) est appelée et transmet l'objet XML temporaire comme paramètre. Si le paquet XML est valide, l'occurrence de composant Label status affiche un message de réussite et l'application se ferme. Si la méthode validateEmployeeXML() a renvoyé une erreur personnalisée (c'est-à-dire qu'une erreur FatalError, WarningError ou une erreur générique s'est produite), l'instruction catch appropriée est exécutée et appelle les méthodes showFatalError(), showWarningError() ou showGenericError(). Chacune de ces méthodes affiche un message approprié dans une composant Alert afin d'informer l'utilisateur de l'erreur spécifique qui s'est produite. Chaque méthode met également à jour l'occurrence de composant Label status avec un message spécifique.

Si une erreur grave se produit pendant une tentative de validation du paquet XML employee, le message d'erreur s'affiche dans un composant Alert, et l'occurrence de composant TextArea xmlText et l'occurrence de composant Button validateBtn sont désactivées, comme l'indique le code suivant :

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

Si une erreur d'avertissement au lieu d'une erreur grave se produit, le message d'erreur est désactivé dans une occurrence de composant Alert, mais les occurrences de composant TextField et Button ne sont pas désactivées. La méthode showWarningError() affiche le message d'erreur personnalisée dans l'occurrence de composant Alert. Le message invite également l'utilisateur à indiquer s'il souhaite poursuivre la validation du XML ou abandonner le script. Le fragment de code suivant présente la méthode showWarningError() :

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

Lorsque l'utilisateur ferme l'occurrence de composant Alert au moyen du bouton Oui ou Non, la méthode closeHandler() est appelée. Le fragment de code suivant présente la méthode closeHandler() :

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

Si l'utilisateur souhaite abandonner le script en cliquant sur Oui dans la boîte de dialogue Alert d'erreur d'avertissement, une exception FatalError est renvoyée, provoquant l'arrêt de l'application.

Création d'une validation personnalisée

La classe de validation personnalisée contient une seule méthode, validateEmployeeXML(). La méthode validateEmployeeXML() prend un seul argument, employee, qui correspond au paquet XML que vous souhaitez valider. La méthode validateEmployeeXML() est la suivante :

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

Un employé doit appartenir à un (et un seul) centre de coût pour être validé. S'il n'appartient à aucun centre de coût, la méthode renvoie une FatalError, qui se propage jusqu'à la méthode validateData() dans le fichier d'application principale. Si l'employé appartient à plusieurs centres de coût, une WarningError est renvoyée. La dernière vérification dans la validation XML contrôle que l'utilisateur a exactement un numéro de sécurité sociale défini (le noeud ssn dans le paquet XML). S'il n'y a pas exactement un nœud ssn, une erreur FatalError est renvoyée.

Vous pouvez ajouter des vérifications supplémentaires à la méthode validateEmployeeXML(). Par exemple, pour vérifier que le noeud ssn contient un numéro valide, ou que l'employé a au moins un numéro de téléphone et une adresse électronique définis, et que ces deux valeurs sont valides. Vous pouvez également modifier le XML de façon à ce que chaque employé ait un ID unique et spécifie l'ID de son responsable.

Définition de la classe ApplicationError

La classe ApplicationError sert de classe de base pour les classes FatalError et WarningError. Elle étend la classe Error et définit ses propres propriétés et méthodes personnalisées, y compris un ID d'erreur, la gravité et un objet XML contenant les codes d'erreur personnalisés et les messages. Cette classe définit également deux constantes statiques utilisées pour définir la gravité de chaque type d'erreur.

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

Chaque noeud d'erreur dans l'objet XML contient un code numérique unique et un message d'erreur. Vous pouvez consulter facilement les messages d'erreur par code d'erreur à l'aide d'E4X, comme indiqué dans la méthode getMessageText() suivante :

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

La méthode getMessageText() prend un seul argument entier, id, et renvoie une chaîne. L'argument id est le code d'erreur pour l'erreur à rechercher. Par exemple, lorsque vous transmettez un id de 9001, l'erreur indiquant que les employés doivent être affectés à un seul centre de coût est renvoyée. Si plusieurs erreurs ont le même code, ActionScript renvoie le message d'erreur uniquement pour le premier résultat trouvé (message[0] dans l'objet XMLList renvoyé).

La méthode suivante dans cette classe, getTitle(), ne prend aucun paramètre et renvoie une valeur de chaîne qui contient l'ID d'erreur pour cette erreur spécifique. Cette valeur est utilisée dans le titre du composant Alert pour identifier l'erreur exacte s'étant produite lors de la validation du paquet XML. Le fragment de code suivant présente la méthode getTitle() :

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

La méthode finale dans la classe ApplicationError est toString(). Cette méthode remplace la fonction définie dans la classe Error pour que vous puissiez personnaliser la présentation du message d'erreur. La méthode renvoie une chaîne qui identifie le numéro d'erreur spécifique et le message qui s'est affiché.

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

Définition de la classe FatalError

La classe FatalError étend la classe ApplicationError personnalisée et définit trois méthodes : le constructeur FatalError, getTitle(), et toString(). La première méthode, le constructeur FatalError, prend un seul argument entier, errorID, et définit la gravité de l'erreur à l'aide des valeurs de constante statiques définies dans la classe ApplicationError. Elle obtient le message de l'erreur spécifique en appelant la méthode getMessageText() dans la classe ApplicationError. Le constructeur FatalError se présente comme suit :

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

La méthode suivante dans la classe FatalError, getTitle(), remplace la méthode getTitle() définie précédemment dans la classe ApplicationError et ajoute le texte "-- FATAL" dans le titre pour informer l'utilisateur qu'une erreur grave s'est produite. La méthode getTitle() se présente comme suit :

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

La méthode finale dans cette classe, toString(), remplace la méthode toString() définie dans la classe ApplicationError. La méthode toString() est

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

Définition de la classe WarningError

La classe WarningError étend la classe ApplicationError et est presque identique à la classe FatalError, excepté quelques changements de chaîne mineurs. Elle définit la gravité de l'erreur sur ApplicationError.WARNING au lieu de ApplicationError.FATAL, comme indiqué dans le code suivant :

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