Simon Wacker

Programmers try to avoid the potential of errors as good as they can; but unfortunately errors nevertheless occur. Thus handling errors is an important issue when writing applications. If errors are properly handled you improve your program in readability, reliability and maintainability. But, to handle errors properly you need a good underlying error handling API. While the ActionScript 2.0 programming language provides needed key constructs like try..catch..finally-blocks and a throw-statement it lacks a good API.

The only help Macromedia’s Error API offers is a class “Error” which can be passed a message and which returns that message on an invocation of its “toString” method. This is definitely to less to make up a good error handling API. Missing features are:

• A stack trace that tells at least who, which class and method, threw the error and which parameters were passed-to the method when it threw the error. In the best case, this stack trace contains the whole method execution sequence beginning at the method that threw the error and ending at the application’s entry point.
• The ability to assign cause-errors. These are catched errors that themselves caused other errors to be thrown.
• At least two types of exceptions that differ in fatality. The less fatal exception may be caused by a wrong user input and the fatal exception indicates a programming error.

These are the features of the As2lib Exception API. With the term exception we refer to an error or better an exceptional event. This means an exception is an event that occurs during the execution of an application that disrupts its normal flow. Note that this does not mean that the exception will break the application. The exception should and must be handled somewhere in the application before this happens. At best the application will then recover itself and at worst it prints an error message to the user. With fatal exceptions indicating programming errors you may also think about directly informing the developer about it.

When you use exceptions in your application you should pay special attention to the following issues:

• Make your exception informative by providing a detailed message intended for developers that includes as much context information as possible and maybe even information on how to resolve the problem. You may also provide an error code either as string or number that can be used to obtain an error message to display to the user.
  If you want to include the content of a variable or method etc. specify its name surrounded by single quotation marks “‘”, followed by the string representation of its content surrounded by a squared open “[” and close “]” brace, for example “… ‘myVariable’ [itsContent] …”.
• Create a base exception per module of you application or event per package. In an application these base exceptions are in most cases normal, not fatal, exceptions. They enable you to catch exceptions at different levels of detail.
• Distinguish different problems not only by error messages and error codes but by separate sub-classes with an informative name of your common base classes. This is because you cannot catch exceptions based on error messages or error codes and thus prevent code to react appropriate if different reactions are required.

Now enogh of all that theory; let’s take a look at the As2lib Exception API.

The As2lib Exception API supplies two kinds of exceptions:

• The “Exception” class that indicates a normal exceptional event that can in most cases be handled. Such an exception is for example the “UnknownServiceException” that is thrown if an external service cannot be reached. The application can in such a case retry to connect after waiting a few milliseconds.
• The “FatalException” class that indicates a fatal exceptional event that is mostly caused due to a programming error and can mostly only be resolved by the programmer itself. A fatal exception is for example the “AbstractOperationException” that indicates that a method has been called that was marked as abstract and should have been overridden by the programmer.

Both these exceptions are implementations of the “Throwable” interface that is the core piece of the API. The most important methods this interface declares are:

• The “initCause” method that initializes the cause of the new throwable. Sometimes you want or you have to transform a low level exception into a high level exception. You can do this by just catching the low level exception and throwing a new high level exception. But doing so without initializing the low level exception as the cause of the high level exception you would use all its useful information.
• The “addStackTraceElement” method that adds a new element to the stack trace. Make use of this method at key points in your application to make it easier following the stack trace and tracking down the exception’s cause.

When you encounter that you need to throw an exception, first look whether such an exception already exists, if not create a new one with an informative name that extends your base exception.

You can now throw this exception at the appropriate place providing an informative message and other helpful information. Do not forget to document the exceptions that are thrown in your method documentation. Because otherwise it is not possible to know which exceptions are thrown besides browsing the code or encountering an exception at run-time.

The last two parameters are are not mandatory but it is good pratice to provide them; otherwise where the exception came from will not be included in the resulting string message.

When you catch the exception you must pay attention to a quirk in ActionScript 2.0 compiled by Flash (this quirk does not exist when you use the Motion-Twin ActionScript 2.0 Compiler or Flex). If you do not declare the fully qualified exception name as exception type in catch-blocks, exceptions of exactly this type will not be catched. Thus do always declare the fully qualified exception name.

If you do not catch an exception or if you trace the string representation of an exception in the Flash Output Panel may appear something like this:

Error messages or detail messages are provided with every exception. They describe in detail what the problem is, why it is a problem and maybe even how this problem may be solved; try to give as much context information as possible. These messages are inteded for developers, not for display to users of your application. If you want to display a message to users, provide an error code with your exception. This error code can either be a string or a number. The advantage of a string error code is that it may itself make sense to users. You can use this error code to get an error message intended for users from a XML or property file that fits the user’s locale.

You may wonder why error messages are so important. The answer is simple. When you work on a project there are probably at least two programmers involved that work on code and use each others’ code. With detailed error messages you can quickly fix the problem if it occurs, without having to ask the other developer what the problem may be and how it can be fixed. The developer who wrote the code you must use may also have left your company some time ago, so you are not even able to ask him. Another issue is when you need to use code you wrote maybe 2 years before and you encounter an error. In all these situations (and there are definitely more) you are more than thankful that yourself and your co-workers took the time to write detailed error messages that help you to fix problems in just a few minutes.

When you write error messages you should pay attention to the format. You should not use different error message formats in one application. Following are common error message standards.

• Write full sentences that start with an upper case letter and end with a period. An error message can consist of multiple sentences and even multiple lines.
• Put in-line API names like parameter names, variable names, method names etc. in single quotes “‘”.
• Put in-line content of for example a variable in square brackets “[]”. Ensure that the string representation of the content is useful and not just something like “[type Function]” but “org.as2lib.data.holder.map.HashMap”. You may want to use the As2lib Reflection API to format the content.
• Write error messages in simple present.
• Write as precise as possible.

I suggested using reflections to look up API names or do some similar tasks. The problem at this is that it costs time even though the exception may be catched one method down in the stack and the detailed error message may not be needed at all and was thus generated in vain. If it is likely that the exception is catched, that is mostly with non-fatal exceptions, it is a good idea to generate detailed error messages lazily. With the As2lib Exception API you can therefor override the “doToString” or the “getMessage” method. Do not override the “toString” method because it does some more work than just generating the string representation of the exception; it also forwards the exception’s string representation to a logger of the As2lib Logging API if the exception was not catched. This more than helpful information would be lost otherwise. The “MethodCallRangeError” of the As2lib Mock Object API uses this method of error message generation.

As you can see al the detailed information that tooks some time to be constructed is only generated if needed. This also factors the error message generation out of the actual code and into the exception, where it belongs. Note that in the above example we have overridden the “doToString” method and not the “getMessage” method. We are thus actually working with two levels of error messages, one detailed that is generated lazily and is returned by the exception’s “toString” method and one not that detailed that is passed-in on construction and returned by the exception’s “getMessage” method. If you override the “getMessage” method, the “doToString” method is the default one that uses the stringifier that can be edited. In this case the stack trace and possible causes are by default also included in the resulting string on invocation of the “toString” method. Note that this is not the case in the above example.

Code must be debugged. With small projects debugging is not much of a problem, but when it comes to larger ones it is a pain to track down bugs that are only recognizable at run-time. These bugs may depend on some previous state and the interaction of large application modules. To make debugging easier it is necessary to trace the application’s execution. In Flash this can be done using “trace”. The problem with “trace” is that it is very primitive. It does not allow for different levels of output nor for custom output devices (an exception right now is the Motion-Twin ActionScript 2.0 Compiler, that allows you to replace calls to “trace” by a custom method prior to compilation). What is needed is a general easy to use logging API that allows for different log levels and that can be easily expanded to support an endless amount of different output possibilities and that can easily integrate other logging APIs without compromising their special functionalities.

You may wonder, why not just use a debugging tool? There are some major differences with instrumentation and debugging.

• Debugging sessions help you track down today’s bugs, but not tomorrow’s.
• Debugging is time consuming. It may be quicker to step through a log file to search for the bug source.
• Logging makes you think about your application.
• Logging let’s you easily track down bugs that occured when a client worked with your program. You may not be able to reproduce the bug or to fix it if you had not logged.
• Logging is more informative than debugging in that it provides detailed human written description on what is going on.
• Logging gives you control on how and where to log. You are not bloating your log file with trivial information.

As already stated a logging API should fulfil some general requirements.

• A simple API.
• Simple configuration.
• Several log levels or priorities, like debug, info, warning, error and fatal and the ability to choose which messages at which level to log.
• The ability to query whether messages with a given level will be logged. This may improve performance because it prevents unnecessary construction of messages that will not be logged.
• The ability to change message formatting.
• The ability to change output devices.

Given these functionalities it is also important when and how to log.

• Log heavily in important and error-prone code sections.
• Modify and improve log messages whenever you think of it to be necessary, like with ambiguous or unclear messages.
• Think about the correct log level for log messages. Log messages at the same level should be of the same level of detail.

“Logger” is the most important interface of the As2lib Logging API. It is the only interface you work with in your application code. All other classes and interfaces of the API just offer special configuration functionalities that are not visible to your application code; you only may use them for configuration on start-up.

That said, what exactly offers the “Logger” interface?

• Generic methods to log at different levels. These methods are in ascending priority: “debug”, “info”, “warning”, “error” and “fatal”.
• Generic methods to figure out whether messages at a given level will actually be logged. These methods, again in ascending priority, are: “isDebugEnabled”, “isInfoEnabled”, “isWarningEnabled”, “isErrorEnabled” and “isFatalEnabled”.

All these methods are generic because they are not bound to any underlying API. The log methods take any type of message as parameter and the query methods return primitive boolean values. How the messages will be logged or how the level is determined depends on the specific implementation. This general approach makes it very easy to switch between different implementations and gives you the ability to work with the logging API of another framework to savor all its special functionalities without tieing your logging code in your application to this logging API.

The As2lib itself offers broad support for different logging APIs and consoles. These include ASCB Library Logging API, LuminicBox Logging API, Flash Debug Panel Source from Bit-101, Alcon, Flashout and SWF Console from Music Theory. This support is offered by “Logger” implementations designed to work with the specific APIs and by “LogHandler” implementations which are discussed in a following tutorial page.

In your application code you obtain a logger through a general access point like your application context or config or from the “LogManager” of the As2lib Logging API. The “LogManager”s duty is simply holding a reference to a logger instance that shall be returned on a call to the static “LogManager.getLogger” method or holding a repository that is responsible for the actual creation or look-up of the logger instance to return. But again the application code is unaware of where the logger comes from.

In your application code you best use a logger as follows.

As you can see I am first checking whether the info message will actually be logged and only if this holds true I will actually log the message. In the above example this check may not be necessary because we are not concatenating strings or looking-up a class’s name using reflections, so this may not improve performance. But in most cases it really improves performance; thus I think of it to be good practice.

Note that also I used a string message in the above example, I could also have logged any kind of object. How the string representation is obtained from the object depends on the concrete “Logger” implementation. It may obtain it just by invoking the object’s “toString” method, but it may also iterate over the object’s variables and methods and log these. Using an object as message may also improve performance because for example the “toString” method of the object is only invoked if the message is actually going to be logged. This approach could be called “Lazy Log Message Generation”.

There is one method we have not talked about yet: “getLogger”. This method is in the above example responsible for returning the “Logger” instance. If you have an application context or config this method’s implementation may look like this:

As already mentioned you can also use the “LogManager” to get your logger.

The only thing you must keep care of is that the “LogManager” is configured with the logger to return before its “LogManager.getLogger” method is invoked.

In the above case we are configuring the “LogManager” with a “TraceLogger” instance. “TraceLogger” simply formats all messages using the “LogMessage” class and “trace”s the formatted message. The formatted message includes for example the log level of the message. You just have to replace this single line of configuration code to make all your application code log to a new console. If you are for example switching from the Macromedia Compiler (MMC) to the Motion-Twin ActionScript 2.0 Compiler (MTASC) you may want to log with Flashout.

I said above that the “Logger” interface can also be used just as delegate and general interface for other logging APIs. Such a API is for example the ASCB Library Logging API. Joey Lott has written a great article about this API: Flash Logging - A Better Trace. To gain all strengths of this API you can configure the “LogManager” with the “AscbLogger”. The “AscbLogger” simply wraps a logger of the ASCB Library Logging API. You can thus do everything the same as Joey Lott explains it in his article. The only thing that differs are the calls to the log methods; you call them on an instance of the generic “Logger” interface and not on the ASCB Logger directly.

As you may have noticed there is a weakness with our way of configuring the “LogManager”. We always return the same logger. It would be great if we could for example return different loggers depending on different logger names. These loggers may also be part of a hierarchy and share their configuration, like the log level, with their children. As you may have guessed this functionalities can actually be achieved with no more than a few lines of configuration code. This is covered in the next tutorial page; just go on.

A logger repository manages multiple loggers. The “LoggerRepository” declares only one method “getLogger(String):Logger”. This method returns a logger appropriate to the passed-in logger name. At its simplest form a “LoggerRepository” implementation just creates, stores and returns loggers by name. But a logger repository can also be more complex.

Let us begin with a simple logger repository, the AscbLoggerRepository. This repository does exactly the things I said when refering to the simplest form of repository. On invocation of the “getLogger” method it first looks whether a logger with the given name has already been stored. If so, this logger will be returned. Otherwise a new “AscbLogger” instance will be created, stored and then returned. As you can see there is not much magic going on. The great thing about this is that the returned loggers are configured with the given name and that this name is shown (by default) with the logged message. This makes it very easy to find out who logged which messages. We can of course still use the “LogManager” as on the previous tutorial page. We just have to configure it with the “AscbLoggerRepository”.

We also have to change the call to the static “LogManager.getLogger” method; we must include a name now. Note that you should decide at the beginning of the project whether to use named loggers or just one logger for the whole project. This largely depends on the size of your application. With small applications it may not be necessary to include a logger name in a message. You can also just always invoke the “LogManager.getLogger” method with a name regardless of whether the underlying configuration supports named loggers. This enables you to switch between the two styles of logger management as you please. You might also use a complex and slower logger management during production to be able to track down problems fast and a simple and fast logger management when the application is in use. The simple management may just ignore the given name. Following is the body of the “getLogger” method of the example of the previous tutorial page.

A complex logger repository is the “LoggerHierarchy”. It manages loggers hierarchical. Every class that gets a logger passes in its name (as we did in the previous example) that is used as the logger’s name. This firstly clearly states which class logged which message in the log output and secondly makes up the hierarchical structure. A fully qualified class name consists of its namespace, that is its preceding package structure, plus the name of the class; for example “org.as2lib.env.except.Exception”. In this case the parent of the logger with full name “org.as2lib.env.except.Exception” is “org.as2lib.env.except” and the parent of this parent is “org.as2lib.env” and so on. It is now possible to configure every node in this hierarchical structure and its children will inherit this configuration unless they overwrite it. The call to the “LogManager.getLogger” method stays the same. Again, what has to be changed is the configuration.

In the above configuration example we are first creating a new “LoggerHierarchy” instance. We are then instantiating two hierarchy able loggers, “coreLogger” and “invisibleLogger”, that are assigned to two nodes in the hierarchy, “org.myproject” and “org.myproject.invisiblemodule”, and adding these two loggers to the hierarchy. The hierarchy itself is set as repository on the “LogManager”. The “coreLogger” logs to the Flash Output Panel (”TraceHandler”) and to the Flashout Console (”FlashoutHandler”). The “invisibleLogger” inherits the handlers from its parent logger, the “coreLogger”, but it sets its log level to “NONE”. This means that it does not log messages.

If we now execute the following code, the message “This is an informative message.” will be logged to the Flash Output Panel and to the Flashout Console.

But if our class is somewhere in the “org.myproject.invisiblemodule” package or any sub-package no log output will be made.

It is important to note that with “SimpleHierarchicalLogger” instances the log level is, if not specified directly, the level of its parent and the handlers are all handlers of its parents. The children inherit the configuration of their parent or parents.

In the above example I have introduced a new notion: log handlers. The following tutorial page gives more insight into their usage.

A “LogHandler” is responsible for the actual logging of messages with some loggers. All loggers that offer hierarchy support for the “LoggerHierarchy” repository must work with log handlers, because otherwise inheriting the output devices of the parents would not be possible. Such a logger is the “SimpleHierarchicalLogger”. But log handlers are not only helpful in a hierarchy. Also non-hierarchical loggers like the “SimpleLogger” can benefit from log handlers. Log handlers enable a logger to support more than one output device. With log handlers one and the same logger can for example log to the Flash Output Panel and to a log file.

When you now invoke any log method on the above “SimpleLogger” instance it will dispatch a “LogMessage” instance containing all information about the actual message, like its level, to all regitered handlers that are then responsible for creating the string representation of the given “LogMessage” instance, probably via the “LogMessage.toString” method, and for writing this string to the actual output device.

As you can see, loggers supporting log handlers are much more flexible than the ones that do not, like “TraceLogger” that is hard-coded to log to the Flash Output Panel. But you must also see the downside of this approach: it costs performance, even if there is only one handler added. I thus recommend using loggers with handler support only in production and only if they are needed and switching to hard-coded loggers when the application is actually in use.

There are some loggers that work with the “LogMessage” class; above all loggers that work with “LogHandler”s. A “LogMessage” simply holds all information regarding an actual log message. These information are the message itself, the level at which the message is logged, the name of the logger the message is logged on and the time at which the log message was created. To now actually log the message it must be stringified, this means a string representation of the message including all extra information must be generated. To do this you simply have to invoke the “LogMessage.toString” method. The string this method returns is generated through a stringifier that can be set via the “LogMessage.setStringifier” method. There also exists a customizable “LogMessage” stringifier, “PatternLogMessageStringifier”. You can use this stringifier or a custom one to format log messages as you please.

An event is every change in an application an event handler receives. Events are for example triggered if a certain point in an application is reached or if a user interacts with the application. In theory everything can trigger events. An event-driven API normally consists of two main modules.

• A dispatcher is responsible for dispatching the event to multiple event handlers. Dispatchers are also called broadcasters, distributors, publishers and multicasters.
• Event Handlers are responsible for handling events. They receive the event and operate in accordance with it. They may also consume the event and thus stop the event to be dispatched to further event handlers. Event handlers are also called listeners, subscribers and observers.

In most event APIs, event handlers can register themselves at a dispatcher. If an event occurs the dispatcher then dispatches the event to all registered event handlers. Thus the dispatcher has two main responsibilites.

• Managing a collection of event handlers.
• Dispatching events to all registered event handlers if they occur and maybe managing an event queue that holds unprocessed events.

Some dispatchers also support the consumption of events. The dispatcher then dispatches an event to event handlers step-by-step, until an event handler consumes the event. This is sometimes called to veto to an event.

Events are used when there is more than one object or there are an unknown number of objects that may want to be notified if some specific operation took place. For example if a user pressed a button. It is bad pracitice to use events for every interaction between objects because this adds unnecessary complexity and slows the execution of the program down. So, think carefully if using events really benefits your application in your specific case.

The Observer Design Pattern is closely related to events. The “Subject” is analog to the “Dispatcher” and the “Observer” to the “Event Handler”. Reading the Observer’s intent you can clearly see the connection: “Define a one-to-many dependency between objects so that when one object changes state, all its dependents are notified and updated automatically.”.

In the As2lib Event API we call event handlers listeners and thus a collection of event handlers listener source. The “EventListenerSource” interface declares common methods needed to manage a collection of listeners. A listener source is so to speak a data holder that holds listeners. The As2lib Event API offers two types of listener sources.

• The “SimpleEventListenerSource” manages listeners in the simplest way possible.
• The “TypeSafeEventListenerSource” manages listeners and ensures that it contains only listeners of a specific type.

Depending on your event handling implementation you may not need a type-safe listener source because you may have ensured the correct type of the listeners somehow else. In such a case use the simple listener source or the type-safe listener source with a flag that the type shall not be checked. Otherwise use the type-safe listener source because it prevents unexpected behavior caused by wrong listeners.

This As2lib Broadcaster Event API is built around the “EventBroadcaster” interface. This interface combines listener source and dispatch functionalities. The “dispatch” method expects exactly one parameter that must be of type “EventInfo”. This event info is also passed-to the listeners. It holds at least the name of the event that is also the name of the method to invoke on the listeners, the event method. It may also contain any additional information. The normal process when working with this API is as follows:

• Creating a listener interface that declares the event method. This event method takes one parameter that must be of type “EventInfo” or a sub-interface or implementation-class.
  1. interface MyListener {
  2.     public function onMyEvent(myEventInfo:MyEventInfo):Void;
  3. }
  4.  
• Creating the specific event info class that has been used as type for the event method’s parameter. This class must implement the “EventInfo” interface. The “getName” method should return a hard-coded string, the name of the event method.
  1. class MyEventInfo implements EventInfo {
  2.     private var information:String;
  3.     public function MyEventInfo(information:String) {
  4.         this.information = information;
  5.     }
  6.     public function getInformation(Void):String {
  7.         return this.information;
  8.     }
  9.     public function getName(Void):String {
  10.         return "onMyEvent";
  11.     }
  12. }
  13.  

In your application you instantiate an event broadcaster for every event, listeners can register to and implement the appropriate add and remove methods that should be properly typed to the listener interfaces. Now when an event occurs you instantiate the appropriate event info with all needed information and dispatch to the added listeners with the appropriate broadcaster passing-in the instantiated event info.

The advantages of this approach are:

• If the event method’s name of a listener changes there is only one place to change the event method’s name, the event info class.
• Because of your typed methods to add and remove listeners you ensure that only listeners that really implement the expected interface are added, so there is no need for further type-checking by the listener source, which leads to better performance.
• Because of your event info class that contains all event specific information you are not bloating the event method’s parameter list. Note though that in the above case this would not have been necessary because we have only one information.
• This approach is rather fast because it does not have to make any detours.
• This approach does not prescribe the existence of a listener interface or class. Note that I myself think of not declaring an explicit listener type as bad practice.
• If one of the listeners needs more information one can simply extend the event info without having to alter other listeners.

But there are also many disadvantages:

• The compiler does not check whether the event method’s name on the listener and the one in the event info class are in sync.
• The listener must always get its information from the passed-in event info. If there is no information needed or if the information needed is only one value, as in the above example, an event info is overkill and unintuitive.
• The listener is bound or has a dependency to the As2lib Broadcaster Event API because it declares one parameter of type “EventInfo”.
• There must be one, in some cases unnecessary class, the “EventInfo” implementation.

Let’s move on and take a look at the As2lib Multicaster Event API that eliminates some of the disadvantages, but adds some new ones.

The core interface of the As2lib Multicaster Event API is the “EventMulticaster”. This interface combines, like the “EventBroadcaster” interface of the previous tutorial page, listener source and dispatch functionalities. The difference is that this time the “dispatch” method expects any number of parameters of any type that are passed-to the event methods of all registered listeners; the listener interface is thus not bound to an event info and a specific event API. All the rest stays basically the same.

The advantages are:

• We do not bind our listeners anymore to a specific event API by allowing custom parameters.
• We can still package information/parameters into one data transfer object if we want to, but it is not prescribed. And this object also does not have to extend or implement a specific class or interface.
• Dispatching events and declaring listeners feels much more natural and is more intutitive.

But again this is connected with some disadvantages:

• The name of the event method is in most implementations passed-in on instantiation of every event multicaster. This is more error-prone because it is easy to make a typo. If the listener’s event method’s name changes we also have to change the event method name in multiple locations.
• Compile-time checking of whether the event method’s name on the listener and the ones we pass-to our event multicasters is still not given.

Again, there issstill much that can be improved; most notably the lack of compile-time checking. This issue is addressed by the As2lib Distributor Event API, so go on.

Unlike the previously discussed event APIs, this API’s base interface is not a dispatcher but a dispatcher control: “EventDistributorControl”. This interface acts as a listener source and a provider and controller of a typed distributor. You again create such a control per event providing it the listener interface or class.

You can then use this control to add and remove listeners.

If the event occurs you first get a typed distributor from the control and invoke the event method on it passing-in the appropriate parameters. The neat thing about this is that you get compile-time checking whether the method you are invoking exists and whether the parameters are of correct type.

The advantages are obvious:

• You have proper compile-time checking when dispatching the event; type-checking of parameters and existence-checking of method.
• You can have proper type-checking of listeners because you specified the expected listener type.
• You can use custom parameters and are not bound to an event info. But if you want to package the information in one object you are free to do so; this object must not extend or implement any specific class or interface, its just a design choice.
• The listener is not bound to any specific event API.

One disadvantage may be that if the name of the event method on the listener changes you have to make a change in every place where you dispatch events. But the compiler tells you that and where these changes have to be made. A good IDE also changes all calls to the method automatically if you change the method’s name. So, this is not much of an issue.