Flash CS3 Documentation

Programming ActionScript 3.0 > Handling errors > Basics of error handling

Basics of error handling

Introduction to error handling

A run-time error is something that goes wrong in your ActionScript code that stops the ActionScript content from running in Adobe Flash Player. To ensure that your ActionScript code runs smoothly for users, you must write code in your application that handles the error--that fixes it, works around it, or at least lets the user know that it's happened. This process is called error handling.

Error handling is a broad category that includes responding to many kinds of errors that are thrown during compilation or at run time. Errors that happen at compile time are often easier to identify--you must fix them in order to complete the process of creating a SWF file. This chapter doesn't discuss compile-time errors; for more information on writing code that doesn't contain compile-time errors, see ActionScript language and syntax and Object-oriented programming in ActionScript. This chapter focuses on run-time errors.

Run-time errors can be more difficult to detect, because in order for them to occur the erroneous code must actually be run. If a segment of your program has several branches of code, like an if..then..else statement, you must test every possible condition, with all the possible input values that real users might use, in order to confirm that your code is error-free.

Run-time errors can be divided into two categories: program errors are mistakes in your ActionScript code, such as specifying the wrong data type for a method parameter; logical errors are mistakes in the logic (the data checking and value manipulation) of your program, such as using the wrong formula to calculate interest rates in a banking application. Again, both of these types of errors can often be detected and corrected ahead of time by diligently testing your application.

Ideally, you'll want to identify and remove all errors from your application before it is released to end users. However, not all errors can be foreseen or prevented. For example, suppose your ActionScript application loads information from a particular website that is outside of your control. If at some point that website isn't available, the part of your application that depends on that external data won't behave correctly. The most important aspect of error handling involves preparing for these unknown cases and handling them gracefully so that users can continue to use your application, or at least get a friendly error message explaining why it isn't working.

Run-time errors are represented in two ways in ActionScript:

• Error classes: Many errors have an error class associated with them. When an error occurs, Flash Player creates an instance of the specific error class that is associated with that particular error. Your code can use the information contained in that error object to make an appropriate response to the error.
• Error events: Sometimes an error occurs when Flash Player would normally trigger an event. In those cases, Flash Player triggers an error event instead. Like other events, each error event has a class associated with it, and Flash Player passes an instance of that class to the methods that are subscribed to the error event.

To determine whether a particular method can trigger an error or error event, see the method's entry in the ActionScript 3.0 Language and Components Reference.

Common error-handling tasks

These are common error-related tasks you might need to perform with your code:

• Writing code to handle errors
• Testing for, catching, and re-throwing errors
• Defining your own error class
• Responding to error and status events

Important concepts and terms

The following reference list contains important terms that you will encounter in this chapter:

• Asynchronous: A program command such as a method call that doesn't provide an immediate result; instead it gives a result (or error) in the form of an event.
• Catch: When an exception (a run-time error) occurs and your code becomes aware of the exception, that code is said to catch the exception. Once an exception is caught, Flash Player stops notifying other ActionScript code of the exception.
• Debugger version: A special version of Flash Player that contains code for notifying users of run-time errors. In the standard version of Flash Player (the one that most users have), errors that aren't handled by your ActionScript code are ignored by Flash Player. In the debugger version (which is included with Adobe Flash CS3 Professional and Adobe Flex), a warning message appears when an unhandled error happens.
• Exception: An error that happens while a program is running and that the run-time environment (that is, Flash Player) can't resolve on its own.
• Re-throw: When your code catches an exception, Flash Player no longer notifies other objects of the exception. If it's important for other objects to be notified of the exception, your code must re-throw the exception to start the notification process again.
• Synchronous: A program command, such as a method call, that provides an immediate result (or immediately throws an error), meaning the response can be used within the same code block.
• Throw: The act of notifying Flash Player (and consequently, notifying other objects and ActionScript code) that an error has occurred is known as throwing an error.

Working through in-chapter examples

As you're working through the chapter, you may want to test some of the example code listings for yourself. Essentially all the code listings in this chapter include the appropriate trace() function call. To test the code listings in this chapter:

1. Create an empty Flash document.
2. Select a keyframe in the timeline.
3. Open the Actions panel and copy the code listing into the Script pane.
4. Run the program using Control > Test Movie.

   You will see the results of the code listing's trace() functions in the Output panel.

Some of the later code listings are more complex and are written as a class. To test these examples:

1. Create an empty Flash document and save it to your computer.
2. Create a new ActionScript file and save it in the same directory as the Flash document. The file's name should match the name of the class in the code listing. For instance, if the code listing defines a class named ErrorTest, use the name ErrorTest.as to save the ActionScript file.
3. Copy the code listing into the ActionScript file and save the file.
4. In the Flash document, click a blank part of the Stage or work space to activate the document Property inspector.
5. In the Property inspector, in the Document Class field, enter the name of the ActionScript class you copied from the text.
6. Run the program using Control > Test Movie

   You will see the results of the example in the Output panel (if the example uses the trace() function) or in a text field created by the example code.

These techniques for testing example code listings are described in more detail in Testing in-chapter example code listings.

Flash CS3