Esempio: Applicazione CustomErrors -- Flash CS3

L'applicazione CustomErrors illustra le tecniche di gestione degli errori personalizzati durante la creazione di un'applicazione. Le tecniche sono descritte di seguito.

Per ottenere i file dell'applicazione per questo esempio, accedere all'indirizzo www.adobe.com/go/learn_programmingAS3samples_flash_it. I file dell'applicazione CustomErrors si trovano nella cartella Samples/CustomError. L'applicazione comprende i seguenti file:

File	Descrizione
CustomErrors.mxml o CustomErrors.fla	Il file principale dell'applicazione in Flash (FLA) o Flex (MXML)
com/example/programmingas3/errors/ApplicationError.as	Classe Error che funge da classe base per le classi FatalError e WarningError.
com/example/programmingas3/errors/FatalError.as	Classe che definisce l'errore FatalError che l'applicazione può generare. Si tratta di un'estensione della classe personalizzata ApplicationError.
com/example/programmingas3/errors/Validator.as	Classe che definisce il metodo di convalida del pacchetto XML dipendente fornito dall'utente.
com/example/programmingas3/errors/WarningError.as	Classe che definisce l'errore WarningError che l'applicazione può generare. Si tratta di un'estensione della classe personalizzata ApplicationError.

Sezioni

Panoramica dell'applicazione CustomErrors

Il file CustomErrors.mxml racchiude l'interfaccia utente e una parte della logica alla base dell'applicazione CustomErrors. Una volta inviato l'evento creationComplete dell'applicazione, viene chiamato il metodo initApp() che definisce un pacchetto XML campione da verificare tramite la classe Validator. Il codice seguente illustra il metodo initApp():

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

Il pacchetto XML viene in seguito visualizzato nell'istanza di un componente TextArea sullo stage. In questo modo è possibile modificare il pacchetto XML prima di sottoporlo a una seconda convalida.

La selezione del pulsante Validate da parte dell'utente richiama il metodo validateData(). Il metodo convalida il pacchetto XML del dipendente tramite il metodo validateEmployeeXML() della classe Validator. Il codice seguente illustra il metodo 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);
    }
}

Per cominciare, viene creato un oggetto XML temporaneo usando il contenuto dell'istanza xmlText del componente TextArea. In seguito, viene chiamato il metodo validateEmployeeXML() della classe personalizzata Validator (com.example.programmingas3/errors/Validator.as) che passa l'oggetto XML temporaneo come parametro. Se il pacchetto XML è valido, l'istanza status del componente Label visualizza un messaggio indicante che l'operazione ha avuto esito positivo e l'applicazione si chiude. Se il metodo validateEmployeeXML() ha generato un errore personalizzato (cioè, un errore FatalError, WarningError o GenericError), viene eseguita l'istruzione catch appropriata che richiama il metodo showFatalError(), showWarningError() oppure showGenericError(). Ognuno di questi metodi visualizza un messaggio pertinente in un componente Alert per informare l'utente dell'errore specifico che si è verificato. Ogni metodo aggiorna, inoltre, l'istanza status del componente Label con un messaggio appropriato.

Se si verifica un errore irreversibile durante il tentativo di convalidare il pacchetto XML del dipendente, il messaggio di errore viene visualizzato in un componente Alert e l'istanza xmlText del componente TextArea e l'istanza validateBtn del componente Button vengono disabilitate, come illustra il codice seguente:

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

Se si verifica un'avvertenza in luogo di un errore irrecuperabile, il messaggio di errore viene comunque visualizzato nell'istanza di un componente Alert, ma le istanze dei componenti TextField e Button non vengono disabilitate. Il metodo showWarningError() visualizza il messaggio di errore personalizzato nell'istanza del componente Alert. Il messaggio chiede, inoltre, all'utente di decidere se desidera procedere con la convalida del pacchetto XML o annullare lo script. La seguente porzione di codice illustra il metodo 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;
}

Quando l'utente chiude l'istanza del componente Alert mediante il pulsante Yes o No, viene chiamato il metodo closeHandler(). La seguente porzione di codice illustra il metodo closeHandler():

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

Se l'utente sceglie di annullare lo script facendo clic su Yes nella finestra di avvertenza Alert, viene generato un errore FatalError e l'applicazione viene interrotta.

Creazione della classe Validator personalizzata

La classe Validator personalizzata contiene un unico metodo: validateEmployeeXML(). Il metodo validateEmployeeXML() accetta un solo argomento, employee, vale a dire il pacchetto XML da convalidare. Il metodo validateEmployeeXML() è il seguente:

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

Per poter essere convalidato, un dipendente deve appartenere a un centro costi (e solo a uno). Se il dipendente non appartiene a nessun centro costi, il metodo genera un FatalError che si propaga al metodo validateData() nel file principale dell'applicazione. Se il dipendente appartiene a più di un centro costi, viene generato un WarningError. La verifica finale effettuata sul pacchetto XML controlla che per l'utente sia definito un numero di iscrizione alla previdenza sociale (il nodo ssn del pacchetto XML). Se non è disponibile esattamente un nodo ssn, viene generato un FatalError.

A discrezione dello sviluppatore, è possibile aggiungere verifiche supplementari al metodo validateEmployeeXML(), ad esempio, per controllare che il nodo ssn contenga un numero valido o che per il dipendente siano stati definiti almeno un numero di telefono e un indirizzo e-mail e che entrambi i valori siano validi. Si può inoltre modificare il codice XML in modo che ogni dipendente disponga di un ID univoco e indichi l'ID del proprio manager.

Definizione della classe ApplicationError

La classe ApplicationError funge da classe base per le classi FatalError e WarningError. La classe ApplicationError è un'estensione della classe Error che definisce i metodi e proprietà specifici, compresa la definizione di un ID errore, la gravità e l'oggetto XML che contiene i codici e i messaggi dell'errore personalizzato. La classe definisce anche due costanti statiche utilizzate per definire la gravità di ogni tipo di errore.

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

Ogni nodo errore dell'oggetto XML contiene un codice numerico e un messaggio univoco. I messaggi di errore possono essere facilmente consultati in base al codice di errore usando E4X, come illustrato nel metodo getMessageText() seguente:

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

Il metodo getMessageText() accetta un solo argomento costituito da un numero intero, id, e restituisce una stringa. L'argomento id è il codice dell'errore da cercare. Ad esempio, passando un id 9001 si recupera l'errore secondo il quale i dipendenti devono essere assegnati a un solo centro costi. Se più errori condividono lo stesso codice, ActionScript restituisce il messaggio di errore per il primo risultato trovato (message[0] nell'oggetto XMLList restituito).

Il metodo seguente di questa classe, getTitle(), non accetta parametri e restituisce una stringa che contiene l'ID specifico dell'errore. Questo valore viene utilizzato nel titolo del componente Alert per contribuire all'identificazione dell'errore esatto verificatosi durante la convalida del pacchetto XML. La seguente porzione di codice illustra il metodo getTitle():

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

L'ultimo metodo della classe ApplicationError è toString() che sostituisce la funzione definita nella classe Error per rendere possibile la personalizzazione della presentazione del messaggio di errore. Il metodo restituisce una stringa che identifica un numero di errore specifico e il messaggio.

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

Definizione della classe FatalError

La classe FatalError è un'estensione della classe personalizzata ApplicationError e definisce tre metodi: la funzione di costruzione FatalError, getTitle() e toString(). Il primo metodo, la funzione di costruzione FatalError, accetta un solo argomento costituito da un numero intero, errorID, imposta la gravità dell'errore mediante valori costanti statici definiti nella classe ApplicationError e ottiene il messaggio di errore specifico chiamando il metodo getMessageText() della classe ApplicationError. La funzione di costruzione FatalError è la seguente:

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

Il metodo seguente della classe FatalError, getTitle(), sostituisce il metodo getTitle() definito nella classe ApplicationError e aggiunge la stringa "-- FATAL" al titolo per informare l'utente che si è verificato un errore irrecuperabile. Il metodo getTitle() è il seguente:

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

L'ultimo metodo di questa classe, toString(), sostituisce il metodo toString() definito nella classe ApplicationError. Il metodo toString() è il seguente:

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

Definizione della classe WarningError

La classe WarningError è un'estensione della classe ApplicationError ed è quasi identica alla classe FatalError, fatta eccezione per un paio di variazioni minime alle stringhe e per il fatto che imposta la gravità dell'errore su ApplicationError.WARNING in luogo di ApplicationError.FATAL, come illustrato nel codice seguente:

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