dpdk Open Source

In this article I would like to elaborate a little on two of the more basic classes in our tool kit, namely Log and LogEvent. Both can be found in the nl.dpdk.log package.

Log and LogEvent are used in conjunction with each other and are used to log messages and act as a substitute for Flash’s built-in trace statement. (But you probably figured all that out by just looking at the class names so I’m going to delve in a little deeper and provide you with some usage examples here.)

Log is a static class which is used to debug your applications. It provides a (better) alternative to Flash’s default trace statement by giving the user the option of assigning a severity or “level” to a log message and optionally displaying the time at which the log message was sent.

Assigning a severity is done by calling one of the six log methods, respectively: debug, info, status, warn, error, fatal. (Remember, Log is a static class so call these methods as such: Log.debug(”message”, “sender”); etc.)
It is also possible to filter which messages will be outputted/displayed by invoking setLevel on Log and passing one of the six Log.LEVEL_* constants. For example:

// Ensures only messages with a level of "warn" or higher ("error and "fatal") are outputted.
Log.setLevel(Log.LEVEL_WARN);

As you’ve seen in the Log.debug call above, each of the six log methods accepts 2 parameters, namely “message” and “sender”. Both of these parameters accept String values.
These parameters should be filled with respectively, a human readable message which will be outputted and the (optionally fully qualified) class name and method name in which the log call was made.
To simplify this task, we’ve created a simple Eclipse FDT template which looks like this:

Log.debug("${cursor}", "${enclosing_type}.${enclosing_method}()");

We’ve named this template logdebug so you can just type logd, hit ctrl+space and have a Log.debug call all ready to go in a couple of keystrokes. Just create six of these to easily use all the levels of Log.

You can toggle a couple of other things besides the minimum output level of your log messages as well.
You can toggle whether or not the time (in milliseconds via getTimer()) on which the log message was outputted will be displayed though setIsTimeDisplayed().
And you can toggle whether or not each log message is traced in Flash’s output panel through it’s built-in trace statement.

The real power of Log lies in the two remaining methods I haven’t discussed yet. I’m talking about addListener and removeListener (which are used in conjunction with the LogEvent class).
These methods allow you to specify a listener in the form of a method closure which will receive a single parameter of type LogEvent each time a Log message is outputted. (So only messages equal to or above the current level will broadcast a LogEvent.)
Each LogEvent contains all the information of a Log message, including the time the message was outputted, the level name of the message, the message itself and the sender of the message.
This allows you to easily attach other means of displaying a Log message in your application. You could for example display a certain status window for a specific Log level, Log each message to a Remoting enabled backend (with use of our RemotingService and RemotingProxy), display each Log message in a debug textfield for simple live debugging of your application, etc. The possibilities are endless. All you need to do is:

// You can place this anywhere in your application and you can add multiple listeners as well.
Log.addListener(myCustomLogListener);

Of course you’re also able to remove a listener if you no longer need it. By invoking removeListener:

// Again, you can place this anywhere in your application (as long as there is a reference to myCustomLogListener).
Log.removeListener(myCustomLogListener);

So Log and LogEvent are both really easy to use but enable very powerful debugging tools and in combination with a smart FDT template provide a great work flow as well.
To summarize this post and to close up, here’s a small code example for you to work with:

// Inside you main Application class.
import nl.dpdk.log.Log;
 
// Inside an init method of Application.
Log.setLevel(Log.LEVEL_ERROR);
 
// Inside an init method of a StatusWindow class.
Log.addListener(onLogMessageReceived);
 
// Inside a StatusWindow class.
// Note: this method will only be called when a message with a Log level of error or higher is outputted.
// Note: each log message above or equal to the log level of error is also traced and the time is also shown by default.
private function onLogMessageReceived(e:LogEvent):void
{
	setTitle(e.getLevelName() + ": something went wrong.");
	setMessage(e.getSender() + " raised an error after " + e.getTime() + 
			 " milliseconds.\n" + "Message: " + e.getMessage());
	show();
}
 
// Inside some other class and/or method.
// Note: this will not be shown in the StatusWindow.
Log.debug("someVariable: " + someVariable, "SomeOtherClass.someOtherMethod");
 
// Inside yet another class and/or method.
// Note: this will be shown in the StatusWindow.
Log.fatal("Some critical proces failed.", "YetAnotherClass.someMethod");