The logging framework is a powerful feature that comes with Flex’s sdk and it’s composed by the classes under mx.logging package, which includes the two “subpackages” mx.logging.errors and mx.logging.target.

Java developers should be already confident whit such framework, because logging api are commonly used in Java programming,  Actionscript /Flash/Flex developers may find this tool a novelty (as I did).

The objective of logging framework is to provide a tool that offers a far better, flexible and centralized way to debug an application than simple use a lot of trace() callings. With Flex’s debugging framework we are able to print and filtering among different types of message based on their severity, such:

• DEBUG
• ERROR
• FATAL
• INFO
• WARN

We can also print the timestamp of the message and the class it refers to, and finally we can simultaneously print messages to different targets.

How it works

The logging framework is basically represented by 3 units: a logger, a target and a log event. The first component is the main class of the framework and its job is to register the different “loggable classes”, register one or more targets and dispatch log events. A target is a class which receives a LogEvent event and handles it by printing its information (message, date, level…) somewhere. A LogEvent event is dispatched when one of the logger methods such: debug(), error(), fatal(), info(), log() or warn() is called.

The steps required to use the logging system are the following:

1. Registering the classes for logging:

The code above will register the class Foo under the package com.daveoncode and then it will broadcast a debug and a warning message

2. Initialize and configure a logging target such TraceTarget (typically in the main class):

The code above will print log messages of all “subscribed” classes inside the package com.daveoncode, including all information available (date, time, category, level)

3. Add the target to the logger:

The previous steps can be repeated as many times as we need, in order to registering several classes and several targets (perhaps with different filters and info settings).

How to extend the framework

To extend the framework we can create new target classes, which print LogEvent data to different location and display data as we like. In my experiment I created a “mini subframework” which can print logs to text files or html files. I created the following 7 classes:

1. LogFileTarget
2. IStreamDataWriter
3. AbstractDataWriter
4. PlainTextDataWriter
5. HTMLDataWriter
6. InvalidLogFileTargetError
7. UnsupportedWriteModeError

The first, as the name suggest is a custom target class, which extends LineFormattedTarget (a target class available in Flex’s framework), it has a parametric constructor which allows the user to choose the name of the file, its directory, the type of file (txt or html) and the charset that will be used to write the file. IStreamDataWriter is an interface which simply declares one method called writeData(), the main purpose of this interface is to use it in polymorphism. IStreamDataWriter is implemented by AbstractDataWriter as an abstract method (abstract is not supported yet in as3, but is treated as abstract), this class also has a secondary method which is used by two subclasses PlainTextDataWriter and HTMLDataWriter. These classes have the duty to physically write data to the file by handling the event received by LogFileTarget which delegates the business logic to them and are used based on the writeMode configuration of  LogFileTarget, which for ease has two public constants called MODE_PLAIN_TEXT and MODE_HTML. InvalidLogFileTargetError and UnsupportedWriteModeError are obviously two custom error which are both (potentially) thrown by LogFileTarget.

This is a sample code using my own classes:

Of course this experiment will works only in AIR applications, because we need to use flash.fileystem classes.

These are the two different output that my classes will generate:
Text file
HTML file

The cool aspect of html version (LogFileTarget.MODE_HTML) is that you can filter by log type :)

If you want to use or take a look to my experiment, feel free to download my logging package here (let me know your opinion)

Alert.show("Alert message", "Alert title", Alert.OK | Alert.NO | Alert.CANCEL);

The code above generates an alert with 3 buttons (ok, no and cancel), but how it works exactly? Well, I don’t want to rewrite the article I read, but I would like to synthesize it and focus on an Actionscript usage, in order to give the basic information required to create custom classes which will accept multiple parameters an unique argument. So… what Alert.OK, Alert.NO and so on are? They are basically numbers (uint), and the result of the bitwise or operator still returns an integer, so the Alert class will receives a number as the third argument. The | operator, in practice produces a “binary sum” of the given numbers. A good way I figured out to understand what is going on when using that operator is to trace the binary representation of every number passed and then the result after the bitwise operation. To convert a “normal number” (base 10) into a binary one (base 2… only 1 or 0 sequence), we can use the toString() method by passing 2 as the radix argument:

var myNumber:uint = 3560;
trace(myNumber.toString(2));

The code above will trace: 110111101000.

So, let’s create a dummy class to do some tests:

package {

    public class BitwiseTest {

        public static const FLAG_1:uint = 1;
        public static const FLAG_2:uint = 2;
        public static const FLAG_3:uint = 4;
        public static const FLAG_4:uint = 8;
        public static const FLAG_5:uint = 16;
        public static const FLAG_6:uint = 32;

        public function BitwiseTest() {

            trace("BitwiseTest.FLAG_1: " + BitwiseTest.FLAG_1.toString(2));
            trace("BitwiseTest.FLAG_3: " + BitwiseTest.FLAG_3.toString(2));
            trace("BitwiseTest.FLAG_5: " + BitwiseTest.FLAG_5.toString(2));
            trace("BitwiseTest.FLAG_6: " + BitwiseTest.FLAG_6.toString(2));

            this.test(BitwiseTest.FLAG_1 | BitwiseTest.FLAG_3 | BitwiseTest.FLAG_5 | BitwiseTest.FLAG_6);

        }

        private function test(flags:uint):void {

            trace("flags: " + flags.toString(2));

        }

    }

}

The trace output will be:

BitwiseTest.FLAG_1: 1
BitwiseTest.FLAG_3: 100
BitwiseTest.FLAG_5: 10000
BitwiseTest.FLAG_6: 100000
flags: 110101

To check for a specific flag’s presence inside flags argument, we can use the bitwise “and” operator (&):

if ((flags & BitwiseTest.FLAG_1) > 0) {

    trace("BitwiseTest.FLAG_1 passed - (" + String(flags & BitwiseTest.FLAG_1) + ")");

}

By using the & operator on flags it will returns the flag’s value if passed to the method and 0 otherwise. By updating the test method in this manner:

private function test(flags:uint):void {

    trace("flags: " + flags.toString(2));

    if ((flags & BitwiseTest.FLAG_1) > 0) {

        trace("BitwiseTest.FLAG_1 passed - (" + String(flags & BitwiseTest.FLAG_1) + ")");

    }

    if ((flags & BitwiseTest.FLAG_2) > 0) {

        trace("BitwiseTest.FLAG_2 passed - (" + String(flags & BitwiseTest.FLAG_2) + ")");

    }

    if ((flags & BitwiseTest.FLAG_3) > 0) {

        trace("BitwiseTest.FLAG_3 passed - (" + String(flags & BitwiseTest.FLAG_3) + ")");

    }

    if ((flags & BitwiseTest.FLAG_4) > 0) {

        trace("BitwiseTest.FLAG_4 passed - (" + String(flags & BitwiseTest.FLAG_4) + ")");

    }

    if ((flags & BitwiseTest.FLAG_5) > 0) {

        trace("BitwiseTest.FLAG_5 passed - (" + String(flags & BitwiseTest.FLAG_5) + ")");

    }

    if ((flags & BitwiseTest.FLAG_6) > 0) {

        trace("BitwiseTest.FLAG_6 passed - (" + String(flags & BitwiseTest.FLAG_6) + ")");

    }		

}

We will obtain this output:

BitwiseTest.FLAG_1: 1
BitwiseTest.FLAG_3: 100
BitwiseTest.FLAG_5: 10000
BitwiseTest.FLAG_6: 100000
flags: 110101
BitwiseTest.FLAG_1 passed - (1)
BitwiseTest.FLAG_3 passed - (4)
BitwiseTest.FLAG_5 passed - (16)
BitwiseTest.FLAG_6 passed - (32)

We have successfully “intercepted” what flags has been passed to the method.
Is important to know that flag’s values can’t be progressive numbers, but they must be multiples of 2, otherwise when using the bitwise “or” operator we will obtain a “ones overlap” resulting in an entity we won’t be able to properly manage. If we replace the flags values used in the previous example in this way:

public static const FLAG_1:uint = 1;
public static const FLAG_2:uint = 2;
public static const FLAG_3:uint = 3;
public static const FLAG_4:uint = 4;
public static const FLAG_5:uint = 5;
public static const FLAG_6:uint = 6;

We will get the following output:

BitwiseTest.FLAG_1: 1
BitwiseTest.FLAG_3: 11
BitwiseTest.FLAG_5: 101
BitwiseTest.FLAG_6: 110
flags: 111
BitwiseTest.FLAG_1 passed - (1)
BitwiseTest.FLAG_2 passed - (2)
BitwiseTest.FLAG_3 passed - (3)
BitwiseTest.FLAG_4 passed - (4)
BitwiseTest.FLAG_5 passed - (5)
BitwiseTest.FLAG_6 passed - (6)

As we can see our test method is unable to understand what flags it has received due to “ones overlap” (looks at te first 5 lines).

In conclusion… using bitwise operators for flags are pretty simple, however bitwise operators can do much more but understanding the real power of these operators and how to properly use them is not so easy (at least to me :-))

Another thing I learned is that design patterns provide a way to solve problems and simplify application’s modification/extension but each pattern can be implemented in a little different way from a language to another and from a developer to another, the only thing that must be unchanged is the goal of the pattern and how it is used.
One, or maybe the simplest, pattern around is the Singleton pattern, which is even one of the most used, even without be aware of it, we used something similar. In fact, Singleton pattern is used when a class must be instantiated only one time in the application (for example a shopping cart in an e-commerce website) or better when a class must exists as only one and be accessible everywhere through a “common access point” which is for convenience a static method called getInstance().

With Java a singleton implementation should be something like this:

public class ClassicSingleton {

   private static ClassicSingleton instance = null;

   protected ClassicSingleton() {

   }

   public static ClassicSingleton getInstance() {

      if(instance == null) {
         instance = new ClassicSingleton();
      }

      return instance;

   }

}

(I taken the code above from this article on javaworld.com: http://www.javaworld.com/javaworld/jw-04-2003/jw-0425-designpatterns.html)

In Actionscript 3, the best implementation (in my opinion) of a Singleton pattern is the following:

package {

    import flash.errors.IllegalOperationError;

    public class SingletonClass {

        private static var instance:SingletonClass = new SingletonClass();

        public function SingletonClass() {

            if (instance != null) {

                throw new IllegalOperationError("SingletonClass can't be instantiated because is a Singleton. Use getInstance() to retrieve a class reference.");

            }

        }

        public static function getInstance():SingletonClass {

            return instance;

        }

    }

}

In this way if we try to call the SingletonClass constructor by using the new operator:

var mySingletonClass:SingletonClass = new SingletonClass();

we will get the error: “SingletonClass can’t be instantiated because is a Singleton. Use getInstance() to retrieve a class reference.”. So, the only and sound way to retrieve our SingletonClass is to use getInstance():

var mySingletonClass:SingletonClass = SingletonClass.getInstance();

Every time we will use getInstance() the same class reference will be returned, avoiding multiple class instantiations.

This is clear and good, but initially I was wondering why to use a method to retrieve the instance, in my own custom implementation I wrote the following code:

package {

    import flash.errors.IllegalOperationError;

    public class AbnormalSingleton {

        private static var created:Boolean;

        public function AbnormalSingleton()    {

            if (!created) {

                created = true;

            } else {

                throw new IllegalOperationError("AbnormalSingleton can't be instantiated again because is a Singleton.");

            }

        }

    }

}

With my AbnormalSingleton the first goal of the Singleton pattern is reached (you can’t get more than one instance), but the pattern has also a second goal: provide a common access point to the reference, and without the getInstance() method, this goal can’t be accomplished, moreover patterns are used to avoid errors and to be used by several developers in a clear manner. So, my idea was not so smart, because you can use the new operator to instantiate the class for the first time with no errors, but the second time you will get an error, the situation is not clear! Instead with the previous example, is immediately evident that we can’t use the class to generate multiple instance.

The only concept that should be clear, in order to achive the goal, is what prototype is and why we must use it.

Javascript is not a really object oriented language, so we can’t really talk about classes and subclassing (using extends like in Java or Actionscript), but however we can create functions that act as constructor for new js objects, and we can inherit properties from an object to another by using the prototyping technique.

Let’s consider a simple Javascript constructor function, that can be used to create an Animal object:

function Animal(name, age, sex) {
    this.name = name;
    this.age = age;
    this.sex = sex;

    this.getInfo = function() {
        alert("Name: " + this.name + "\nAge: " + this.age + "\nSex: " + this.sex);
    }
}

To extend the Animal class with a Dog class, we have to define the Dog constructor:

function Dog(name, age, sex, barkPower) {

    Animal.apply(this, arguments);

    this.barkPower = barkPower;

    this.bark = function() {

        var barkBuffer = [this.name, " says: "];

        for (var i=0; i<this.barkPower; i++) {
            barkBuffer.push("bark! ");
        }

        alert(barkBuffer.join(""));

    }

}

and then prototyping it in this way:

Dog.prototype = new Animal();

The Animal.apply() call inside Dog, is like to use super() in Java to call the SuperClass constructor.
Now our Dog has the same methods and properties of Animal, for example we can use the getInfo() method, in addition to bark():

var laika = new Dog("Laika", 5, "F", 8);
laika.getInfo();
laika.bark();

Now, let’s put the prototyping technique in practice, in order to create a custom control for our map.
The Javascript class that represents a google map’s control is GControl, so if we want to make something of us own, we must extend that class. Furthermore we have to implements at least 2 methods: initialize() and getDefaultPosition(), in practice the GControl is to be considered an interface.
The first method, must add a DOM node (a graphic button or whatelse represents our control) to the map and return it (with return), the second must return an instance of GControlPosition which is used to place the DOM node (our control) in the right position.
Our goal is to create a custom map navigation (ie: move to north, move to south, move to east and move to west), so we will create 4 js classes that will extend GControl and implements the 2 methods. We call these classes respectively: GoUpButton, GoDownButton, GoLeftButton and GoRightButton .
Let’s see how GoUpButton is structured and how it works (others buttons will differ only for their position and click handler):

function GoUpButton(map) {

    this.map = map;
    this.button = document.createElement("a");

}

The function above, is the GoUpButton‘s constructor, and as you can see it takes one argument: map, that is a reference to the map’s instance, then it creates an <a> tag that will be our clickable button.
The next step is to extend GControl:

GoUpButton.prototype = new GControl();

Now, let’s implement the initialize() method:

GoUpButton.prototype.initialize = function() {

    var map = this.map;

    this.button.className = "custom_nav_top";
    this.button.href = "javascript:;";
    this.button.title = "Move the map to the top";
    this.button.innerHTML = "N";

    GEvent.addDomListener(this.button, "click", function() {
        map.panBy(new GSize(0, 100));
    });

    map.getContainer().appendChild(this.button);

    return this.button;

}

In this method we define the CSS class for the button, set its href attribute to “javascript:;” to ensure it won’t reload the page (is not necessary, but I feel more secure by doing it), set its title attribute and its innerHTML (in this case an N, which stands for North). Then we add an (anonymous) event listener that will be triggered when the user will click the button. This listener will invoke the map’s panBy() method, which moves the map by a specific distance by using an animation. The distance is represented by an instance of GSize, which is essentially a virtual polygon, which dimension are expressed with the two parameters width and height. So with new GSize(0, 100), we will move the map 100 pixels to the top (y axis).
The last two steps in the method are add the node to the DOM (by using map’s getContainer() method, which returns the node containing the map) and returns it.

Ok, finally there is the getDeafultPosition() implementation:

GoUpButton.prototype.getDefaultPosition = function() {

    return new GControlPosition(G_ANCHOR_TOP_LEFT, new GSize(240, 5));

}

This is a really simple method that returns an instance of GControlPosition, which will define how to place the control. GControlPosition takes 2 arguments: anchor and offset, the first can be one of the following constants:

• G_ANCHOR_TOP_RIGHT
• G_ANCHOR_TOP_LEFT
• G_ANCHOR_BOTTOM_RIGHT
• G_ANCHOR_BOTTOM_LEFT

that will anchor the control to the 4 possible map’s corners, the second represents the offset (ie: the distance from the anchor point). In this way we can position our button where we like (GoUpButton will be placed 5 pixel to the top of the map and 240 pixels to the left… in a map of 500×300 pixels it will appears centered on the top).
We have finished with our custom control!
Now we have to repeat the previous steps for GoDownButton, GoLeftButton and GoRightButton, by replacing the necessary values such button’s class, innerHTML, title, panBy() argument and GControlPosition() arguments.
In order to add all the 4 controls to the map we will use addControl() method:

    map.addControl(new GoUpButton(map));
    map.addControl(new GoDownButton(map));
    map.addControl(new GoLeftButton(map));
    map.addControl(new GoRightButton(map));

The result should be this:

The full code for the map above is the following:

/* go top */
function GoUpButton(map) {
    this.map = map;
    this.button = document.createElement("a");
}

GoUpButton.prototype = new GControl();

GoUpButton.prototype.initialize = function() {

    var map = this.map;

    this.button.className = "custom_nav_top";
    this.button.href = "javascript:;";
    this.button.title = "Move the map to the top";
    this.button.innerHTML = "N";

    GEvent.addDomListener(this.button, "click", function() {
        map.panBy(new GSize(0, 100));
    });

    map.getContainer().appendChild(this.button);

    return this.button;

}

GoUpButton.prototype.getDefaultPosition = function() {
    return new GControlPosition(G_ANCHOR_TOP_LEFT, new GSize(240, 5));
}

/* go down */
function GoDownButton(map) {
    this.map = map;
    this.button = document.createElement("a");
}

GoDownButton.prototype = new GControl();

GoDownButton.prototype.initialize = function() {

    var map = this.map;

    this.button.className = "custom_nav_down";
    this.button.href = "javascript:;";
    this.button.title = "Move the map to the bottom";
    this.button.innerHTML = "S";

    GEvent.addDomListener(this.button, "click", function() {
         map.panBy(new GSize(0, -100));
    });

    map.getContainer().appendChild(this.button);

    return this.button;

}

GoDownButton.prototype.getDefaultPosition = function() {
    return new GControlPosition(G_ANCHOR_TOP_LEFT, new GSize(240, 270));
}

/* go left */
function GoLeftButton(map) {
    this.map = map;
    this.button = document.createElement("a");
}

GoLeftButton.prototype = new GControl();

GoLeftButton.prototype.initialize = function() {

    var map = this.map;

    this.button.className = "custom_nav_left";
    this.button.href = "javascript:;";
    this.button.title = "Move the map to the left";
    this.button.innerHTML = "W";

    GEvent.addDomListener(this.button, "click", function() {
        map.panBy(new GSize(100, 0));
    });

    map.getContainer().appendChild(this.button);

    return this.button;

}

GoLeftButton.prototype.getDefaultPosition = function() {
    return new GControlPosition(G_ANCHOR_TOP_LEFT, new GSize(5, 140));
}

/* go right */
function GoRightButton(map) {
    this.map = map;
    this.button = document.createElement("a");
}

GoRightButton.prototype = new GControl();

GoRightButton.prototype.initialize = function() {

    var map = this.map;

    this.button.className = "custom_nav_right";
    this.button.href = "javascript:;";
    this.button.title = "Move the map to the right";
    this.button.innerHTML = "E";

    GEvent.addDomListener(this.button, "click", function() {
         map.panBy(new GSize(-100, 0));
    });

    map.getContainer().appendChild(this.button);

    return this.button;

}

GoRightButton.prototype.getDefaultPosition = function() {
    return new GControlPosition(G_ANCHOR_TOP_LEFT, new GSize(470, 140));
}

function initialize() {

    if (GBrowserIsCompatible()) {

        var map = new GMap2(document.getElementById("map_canvas"));

        map.addControl(new GoUpButton(map));
        map.addControl(new GoDownButton(map));
        map.addControl(new GoLeftButton(map));
        map.addControl(new GoRightButton(map));
        map.setCenter(new GLatLng(41.87194, 12.56738), 5);

    }

}

I would like to thanks Mike Potter, for the gift. I’ve appreciated it very much, and I hope to enter in the active Actionscript/Flex community as soon as possible.