Exemple de gestion des erreurs : application CustomErrors

Au chargement de l’application, la méthode initApp() est appelée dans les applications Flex ou le code du scénario (autre qu’une fonction) est exécuté dans les applications Flash Professional. Ce code définit un exemple de paquet XML que la classe Validator vérifiera. Le code suivant est exécuté :

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 du composant TextArea sur la scène. Cette étape 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() de la classe Validator. Le code suivant présente la méthode 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); 
    } 
}

Un objet XML temporaire est d’abord créé à l’aide du contenu de l’occurrence du composant TextArea xmlText . La méthode validateEmployeeXML() de la classe Validator personnalisée (com.example.programmingas3/errors/Validator.as) est ensuite appelée et transmet l’objet XML temporaire comme paramètre. Si le paquet XML est valide, l’occurrence du composant Label status affiche un message de réussite et l’application se ferme. Si la méthode validateEmployeeXML() renvoie une erreur personnalisée (c’est-à-dire qu’une erreur FatalError, WarningError ou une erreur générique se produit), l’instruction catch appropriée s’exécute et appelle les méthodes showFatalError() , showWarningError() ou showGenericError() . Chacune de ces méthodes affiche un message approprié dans une zone de texte appelée statusTex t pour avertir l’utilisateur de l’erreur spécifique qui s’est produite. Chaque méthode met également à jour l’occurrence du 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 la zone de texte statusText et l’occurrence du composant TextArea xmlText et l’occurrence du composant Button validateBtn sont désactivées, comme l’indique le code suivant :

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

S’il se produit une erreur d’avertissement au lieu d’une erreur grave, le message d’erreur est affiché dans l’occurrence de TextArea statusText , mais les occurrences de composant TextField xmlText et Button ne sont pas désactivées. La méthode showWarningError() affiche le message d’erreur personnalisé dans la zone de texte statusText . Le message invite également l’utilisateur à indiquer s’il souhaite poursuivre la validation de l’objet XML ou annuler le script. Le fragment de code suivant présente la méthode 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; 
}

Lorsque l’utilisateur clique sur le bouton Oui ou Non, la méthode closeHandler() est appelée. Le fragment de code suivant présente la méthode closeHandler() :

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

Si l’utilisateur souhaite annuler le script en cliquant sur Oui, une exception FatalError est renvoyée, provoquant l’arrêt de l’application.

La classe Validator personnalisée contient une seule méthode, validateEmployeeXML() . La méthode validateEmployeeXML() gère un seul argument, employee , qui correspond au paquet XML à 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 erreur 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 erreur WarningError est renvoyée. La dernière vérification de la validation XML contrôle que l’utilisateur possède un seul numéro de sécurité sociale défini (le nœud 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() afin de vérifier, par exemple, que le nœud ssn contient un numéro valide, ou que l’employé possède au moins un numéro de téléphone et une adresse électronique, 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.

La classe ApplicationError sert de classe de base aux 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.

La méthode du constructeur de la classe ApplicationError est la suivante :

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 nœud 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 correspond au code de 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 de cette classe, getTitle() , ne prend aucun paramètre et renvoie une valeur de chaîne qui contient l’ID de cette erreur spécifique. Cette valeur permet d’identifier aisément l’erreur exacte qui s’est 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 dernière méthode finale de 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; 
}

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 de 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 la suivante :

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

La classe WarningError étend la classe ApplicationError et est presque identique à la classe FatalError, à l’exception de 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); 
}