Xavi Beumala

Table of contents

Created

8 February 2011

Requirements

Prerequisite knowledge
Knowledge of Flex, MXML, and event handlers will help you make the most of this article.

User level
Advanced
Required products
Flash Builder 4 (Download trial)
Starting with Flash Player 10.1 and Adobe AIR 2.0, developers can capture unhandled exceptions and errors globally. Note, however, that it's a best practice to take care of the exceptions where they happen. Global handling should only be used for asynchronous exceptions that you can't really control in any other way, or for diagnosing and logging exceptions that are not being caught locally.
 
In this article I explain how to catch unhandled exceptions or errors globally using the uncaughtError event. The technique I use is declarative and MXML based; it relies on the Flex-specific [Mixin] metadata tag.
 

 
Handling uncaught errors

The new API for handing uncaught errors can be used as follows:
 
loaderInfo.uncaughtErrorEvents.addEventListener(UncaughtErrorEvent.UNCAUGHT_ERROR, onUncaughtError); private function onUncaughtError(e:UncaughtErrorEvent):void { // Do something with your error. }
When you're working with Flex and you add an UncaughtErrorEvent.UNCAUGHT_ERROR listener to the loaderInfo object, make sure you do it after FlexEvent.APPLICATION_COMPLETE event has been triggered, otherwise you'll get an error, specifically: Error #1009: Cannot access a property or method of a null object reference .
 
To simplify this procedure and eliminate the need for all this glue code and configuration code that ends up cluttering the main application class , I created a GlobalExceptionHandler component. The implementation isn't tied to the APPLICATION_COMPLETE event; instead it uses the [Mixin] metadata tag. On top of that you can use it declaratively; for example:
 
<?xml version="1.0" encoding="utf-8"?> <s:WindowedApplication xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" xmlns:mx="library://ns.adobe.com/flex/mx" xmlns:logging="com.adobe.ac.logging.*"> <fx:Declarations> <logging:GlobalExceptionHandler preventDefault="true"> <logging:LogHandlerAction/> <local:TraceHandlerAction/> </logging:GlobalExceptionHandler> </fx:Declarations> </s:WindowedApplication>
The code for this component and a sample project that uses it are included in globalExceptionHandler.zip, the sample file for this article.
 
Here is the code for GlobalExceptionHandler:
 
package com.adobe.ac.logging { import flash.display.LoaderInfo; import flash.events.UncaughtErrorEvent; import mx.managers.ISystemManager; [Mixin] [DefaultProperty("handlerActions")] public class GlobalExceptionHandler { private static var loaderInfo:LoaderInfo; [ArrayElementType("com.adobe.ac.logging.GlobalExceptionHandlerAction")] public var handlerActions:Array; public var preventDefault:Boolean; public static function init(sm:ISystemManager):void { loaderInfo = sm.loaderInfo; } public function GlobalExceptionHandler() { loaderInfo.uncaughtErrorEvents.addEventListener(UncaughtErrorEvent.UNCAUGHT_ERROR, uncaughtErrorHandler); } private function uncaughtErrorHandler(event:UncaughtErrorEvent):void { for each (var action:GlobalExceptionHandlerAction in handlerActions) { action.handle(event.error); } if (preventDefault == true) { event.preventDefault(); } } } }
Here is the code for LogHandlerAction:
 
package com.adobe.ac.logging { import mx.logging.ILogger; import mx.logging.Log; public class LogHandlerAction implements GlobalExceptionHandlerAction { private static const LOG:ILogger = Log.getLogger("UncaughtException"); public function handle(error:Object):void { if (error is Error) { var errorObj:Error = error as Error; LOG.error("{0}. {1}\n {2}", errorObj.errorID, errorObj.message, errorObj.getStackTrace()); } } }

 
Where to go from here

For more information on the new error handling APIs, see Christian Cantrell's post on Global Error Handling in AIR 2.0 and Flash Player 10.1.
 
You may also be interested in two blog posts I've written on related topics: