Ejemplo de gestión de errores: Aplicación CustomErrors

Cuando se carga la aplicación, se llama al método initApp() para las aplicaciones de Flex o el código de la línea de tiempo (sin función) se ejecuta en Flash Professional. Este código define un paquete XML de ejemplo que comprobará la clase Validator. Se ejecuta el siguiente código:

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

El paquete XML se muestra después en una instancia de componente TextArea en el escenario, lo que permite modificar el paquete antes de intentar su revalidación.

Cuando el usuario hace clic en el botón Validate, se llama al método validateData() . Este método valida el paquete XML para empleados con el método validateEmployeeXML() de la clase Validator. El código siguiente muestra el 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); 
    } 
}

En primer lugar, se crea un objeto XML temporal con el contenido de la instancia de componente TextArea xmlText . A continuación, el método validateEmployeeXML() de la clase Validator personalizada (com.example.programmingas3/errors/Validator.as) se llama y transmite el objeto XML temporal como parámetro. Si el paquete XML es válido, la instancia de componente Label status muestra un mensaje de operación realizada correctamente y se cierra la aplicación. Si el método validateEmployeeXML() genera un error personalizado (es decir, FatalError, WarningError o Error de tipo genérico), la sentencia catch correspondiente llama al método showFatalError() , showWarningError() o showGenericError() y lo ejecuta. Cada uno de estos métodos muestra un mensaje apropiado en un área de texto denominada statusText para notificar al usuario el error concreto que se ha producido. Los métodos también actualizan la instancia de componente Label status con un mensaje determinado.

Si se produce un error grave durante el intento de validar el paquete XML para empleados, el mensaje de error se muestra en el área de texto statusText y el componente TextArea xmlText y la instancia del componente Button validateBtn se deshabilitan, tal como se indica en el código siguiente:

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

Si se produce un error de advertencia en lugar de un error grave, el mensaje de error se muestra en la instancia de TextArea statusText , pero las instancias del componente TextField y Button xmlText no se deshabilitan. El método showWarningError() muestra el mensaje de error personalizado en el área de texto statusText . El mensaje también pregunta al usuario si desea continuar con la validación del XML o cancelar la ejecución del script. El siguiente fragmento de código muestra el 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; 
}

Cuando el usuario hace clic en el botón Sí o No, se llama al método closeHandler() . El extracto siguiente muestra el método closeHandler() :

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

Si el usuario decide cancelar la ejecución del script haciendo clic en Sí, se genera un error de tipo FatalError, lo que provoca el cierre de la aplicación.

La clase Validator personalizada contiene un solo método, validateEmployeeXML() . El método validateEmployeeXML() solo procesa un único argumento, employee , que es el paquete XML que se desea validar. El método validateEmployeeXML() funciona del modo siguiente:

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 que se valide un empleado, este debe pertenecer única y exclusivamente a un centro de coste. Si el empleado no pertenece a ningún centro de coste, el método genera un error de tipo FatalError, que se propaga hasta el método validateData() del archivo de aplicación principal. Si el empleado pertenece a más de un centro de coste, se genera un error WarningError. La última comprobación en el validador de XML consiste en confirmar que el usuario tiene exactamente un número de seguridad social definido (el nodo ssn del paquete XML). Si no hay exactamente un nodo ssn , se genera un error de tipo FatalError.

Se pueden añadir otras comprobaciones al método validateEmployeeXML() ; por ejemplo, para asegurarse de que el nodo ssn contiene un número válido, o bien el empleado tiene definidos al menos un número de teléfono y una dirección de correo electrónico, y los dos valores son válidos. Asimismo, se pueden modificar los datos XML para que cada empleado tenga un ID único y especifique el ID de su responsable.

La clase ApplicationError es la clase base para las clases FatalError y WarningError. La clase ApplicationError amplía la clase Error y define sus propios métodos y propiedades, entre los que se incluye la definición de ID y gravedad de errores, así como objetos XML que contienen códigos y mensajes de error personalizados. Esta clase también define dos constantes estáticas que se usan para definir la gravedad de cada tipo de error.

El método del constructor de la clase ApplicationError es el siguiente:

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 nodo de error del objeto XML contiene un código numérico único y un mensaje de error. Los mensajes de error pueden consultarse por su código de error mediante E4X, tal como se muestra en el método getMessageText() siguiente:

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

El método getMessageText() procesa un solo argumento de tipo entero, id , y devuelve una cadena. El argumento id es el código de error que debe consultar el error. Por ejemplo, al pasar el id 9001, se recupera un error que indica que los empleados deben asignarse a un solo centro de coste. Si hay más de un error con el mismo código, ActionScript solo devuelve el mensaje de error para el primer resultado encontrado ( message[0] del objeto XMLList devuelto).

El siguiente método de esta clase, getTitle() , no procesa ningún parámetro y devuelve un valor de cadena que contiene el ID de este error específico. Este valor se emplea para ayudar a identificar fácilmente el error exacto, producido durante la validación del paquete XML. El siguiente fragmento de código muestra el método getTitle() :

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

El último método de la clase ApplicationError es toString(). Este método sustituye la función definida en la clase Error, de manera que se puede personalizar la presentación del mensaje de error. El método devuelve una cadena que identifica el mensaje y el número de error específicos que se han producido.

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

La clase FatalError amplía la clase personalizada ApplicationError y define tres métodos: el constructor FatalError, getTitle() y toString() . El primer método (el constructor de FatalError) procesa un solo argumento de tipo entero ( errorID ), y establece la gravedad del error con los valores de constantes estáticas definidas en la clase ApplicationError. El mensaje de error específico se obtiene llamando al método getMessageText() de la clase ApplicationError. El constructor de FatalError es el siguiente:

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

El siguiente método de la clase FatalError, getTitle() , sustituye el método getTitle() definido anteriormente en la clase ApplicationError, y añade el texto "-- FATAL" al título para informar al usuario de que se ha producido un error grave. El método getTitle() funciona del modo siguiente:

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

El último método de esta clase, toString() , sustituye el método toString() definido en la clase ApplicationError. El método toString() funciona es:

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

La clase WarningError amplía la clase ApplicationError y es casi idéntica a la clase FatalError, salvo por un par de cambios en cadenas poco importantes. La gravedad de los errores se establece en ApplicationError.WARNING en lugar de ApplicationError.FATAL, tal como se muestra en el código siguiente:

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