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