Exemplo de tratamento de erros: aplicativo CustomErrors

Quando o aplicativo é carregado, o método initApp() é chamado para os aplicativos Flex ou o código (não função) de linha de tempo é executado para os aplicativos do Flash Professional. Esse código define um pacote XML de exemplo a ser verificado pela classe Validator. O seguinte código é executado:

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

O pacote XML é exibido posteriormente em uma ocorrência do componente TextArea no Palco. Esta etapa permite modificar o pacote XML antes de tentar validá-lo novamente.

Quando o usuário clica no botão Validate, o método validateData() é chamado. Esse método valida o pacote XML funcionário usando o método validateEmployeeXML() na classe Validator. O código a seguir mostra o método 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); 
    } 
}

Primeiro, um objeto XML temporário é criado usando o conteúdo da ocorrência do componente TextArea xmlText. Em seguida, o método validateEmployeeXML() na classe Validator personalizada (com.example.programmingas3/errors/Validator.as) é chamado e transmite o objeto XML temporário como um parâmetro. Se o pacote XML for válido, a ocorrência do componente Label status exibirá uma mensagem de êxito e o aplicativo será encerrado. Se o método validateEmployeeXML() lançar um erro personalizado (isto é, se ocorrer um FatalError, WarningError ou um Error genérico), a instrução catch apropriada executará e chamará o método showFatalError(), showWarningError() ou showGenericError(). Cada um desses métodos exibe uma mensagem apropriada em uma área de texto chamada statusText para notificar o usuário do erro específico que ocorreu. Cada método também atualiza a ocorrência do componente Label status com uma mensagem específica.

Se ocorrer um erro fatal durante a tentativa de validar o pacote XML funcionário, a mensagem de erro será exibida na área de texto statusText e as ocorrências dos componentes TextArea xmlText e Button validateBtn serão desativadas, como mostra o seguinte código:

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

Se ocorrer um erro de aviso, em vez de um erro fatal, a mensagem de erro será exibida na ocorrência statusText TextArea, mas as ocorrências dos componentes Button e TextField xmlText não serão desativadas. O método showWarningError() exibe uma mensagem de erro personalizada na área de texto statusText. A mensagem também solicita que o usuário decida se deseja prosseguir com a validação do XML ou cancelar o script. O seguinte trecho mostra o método 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; 
}

Quando o usuário clica no botão Yes ou No, o método closeHandler() é chamado. O seguinte trecho mostra o método closeHandler():

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

Se o usuário decidir cancelar o script clicando em Yes, um FatalError será lançado fazendo com que o aplicativo seja encerrado.

A classe Validator personalizada contém um único método, validateEmployeeXML(). O método validateEmployeeXML() usa um único argumento, employee, que é o pacote XML que você deseja validar. O método validateEmployeeXML() é o seguinte:

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

Para ser validado, um funcionário deve pertencer a um (e apenas um) centro de custos. Se o funcionário não pertencer a nenhum centro de custos, o método lançará um FatalError, que é emitido ao método validateData() no arquivo do aplicativo principal. Se o funcionário pertencer a mais de um centro de custos, será lançado um WarningError. A verificação final no validador XML é que o usuário tem exatamente um número de seguro social (o nó ssn no pacote XML). Se não houver exatamente um nó ssn, será lançado um erro FatalError.

Você pode adicionar outras verificações ao método validateEmployeeXML(), por exemplo, para garantir que o nó ssn contenha um número válido ou que o funcionário tenha pelo menos um número de telefone e um endereço de email definido, e os dois valores sejam válidos. Também é possível modificar o XML de forma que cada funcionário tenha uma ID exclusiva e especifique a ID do seu gerente.

A classe ApplicationError serve de classe base para as classes FatalError e WarningError. A classe ApplicationError estende a classe Error e define seus próprios métodos e propriedades personalizados, incluindo a definição de ID e gravidade de um erro, e um objeto XML que contém os códigos e as mensagens de erro personalizados. Essa classe também define duas constantes estáticas que são usadas para definir a gravidade de cada tipo de erro.

O método do construtor da classe ApplicationError é o seguinte:

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

Cada nó de erro no objeto XML contém um código numérico exclusivo e uma mensagem de erro. As mensagens de erro podem ser facilmente pesquisadas pelo seu código de erro usando o E4X, como mostra o seguinte método getMessageText():

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

O método getMessageText() usa um único argumento inteiro, id, e retorna uma seqüência de caracteres. O argumento id é o código de erro para o erro a ser pesquisado. Por exemplo, transmitir um id de 9001 recupera o erro dizendo que os funcionários devem ser atribuídos apenas a um centro de custos. Se houver mais de um erro com o mesmo código, o ActionScript retornará a mensagem de erro apenas para o primeiro resultado encontrado (message[0] no objeto XMLList retornado).

O método seguinte nessa classe, getTitle(), não usa nenhum parâmetro e retorna um valor de seqüência de caracteres que contém a ID de erro para esse erro específico. Esse valor é usado para ajudar a identificar com facilidade o erro exato que ocorreu durante a validação do pacote XML. O seguinte trecho mostra o método getTitle():

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

O método final na classe ApplicationError é toString(). Esse método substitui a função definida na classe Error para que você possa personalizar a apresentação da mensagem de erro. O método retorna uma seqüência de caracteres que identifica o número do erro específico e a mensagem que ocorreu.

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

A classe FatalError estende a classe ApplicationError personalizada e define três métodos: o construtor FatalError, getTitle() e toString(). O primeiro método, o construtor FatalError, usa um único argumento inteiro, errorID, define a gravidade do erro usando os valores constantes estáticos definidos na classe ApplicationError e obtém a mensagem de erro específica, chamando o método getMessageText() na classe ApplicationError. O construtor FatalError é o seguinte:

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

O método seguinte na classe FatalError, getTitle(), substitui o método getTitle() definido anteriormente na classe ApplicationError e anexa o texto "-- FATAL" no título para informar ao usuário que um erro fatal ocorreu. O método getTitle() é o seguinte:

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

O método final nessa classe, toString(), substitui o método toString() definido na classe ApplicationError. O método toString() é:

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

A classe WarningError estende a classe ApplicationError e é quase idêntica à classe FatalError, exceto por duas pequenas alterações de sequência de caracteres e por definir a gravidade do erro como ApplicationError.WARNING, em vez de ApplicationError.FATAL, como mostra o seguinte código:

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