org.as2lib.core.BasicClass +--org.as2lib.env.overload.Overload
Overload provides methods to overload a method.
With overloading you have typically two or more methods with the same name. Which method gets actually invoked depends on its type signature, that means its return and arguments' types. Here is an example of what overloading may look if it would be supported by Flash (note that this code does actually not work).
Example:
// MyClass.as
class MyClass {
public function myMethod(number:Number, string:String):Void {
trace("myMethod(Number, String):Void");
}
public function myMethod(number:Number):Void {
trace("myMethod(Number):Void");
}
public function myMethod(string:String):Number {
trace("myMethod(String):Number");
return 1;
}
}
Usage:
// test.fla
var myInstance:MyClass = new MyClass();
myInstance.myMethod(1);
myInstance.myMethod(2, "myString");
var number:Number = myInstance.myMethod("myString");
trace(number);
Output:
myMethod(Number):Void myMethod(Number, String):Void myMethod(String):Number 1
As you can see, depending on what type the passed-in arguments have a different
method is invoked. This is sadly not possible with ActionScript, that is what this
class is for. Using the overload mechanism this class offers the overloading looks
as follows:
// MyClass.as
class MyClass {
public functino myMethod() {
var o:Overload = new Overload(this);
o.addHandler([Number, String], myMethodByNumberAndString);
o.addHandler([Number], myMethodByNumber);
o.addHandler([String], myMethodByString);
return o.forward(arguments);
}
public function myMethodByNumberAndString(number:Number, string:String):Void {
trace("myMethod(Number, String):Void");
}
public function myMethodByNumber(number:Number):Void {
trace("myMethod(Number):Void");
}
public function myMethodByString(string:String):Number {
trace("myMethod(String):Number");
return 1;
}
}
Using the above testing code the output looks the same.
While this is a good overloading mechanism / overloading alternative it still has some disadvantages.
Overload class throws an UnknownOverloadHandlerException if the
real arguments match no added overload handler.
But if you declare the methods to overload to as public, as in the example, you can still invoke them directly. Doing so, all the above problems do not hold true anymore. The overloaded methods then acts more as a convenient method that is easy to use if appropriate.
new Overload()
public function Overload(target)
Constructs a new Overload instance.
The passed-in target is normally the object on which the overloading
takes place. This means it is the object that declares all methods that take
part at the overloading.
target | the target to invoke the overloaded method on |
public function setDefaultHandler(method:Function):VoidSets the default handler.
This handler will be used if no other handler matches to a list of arguments. All real arguments used for the overloading are passed as parameters to the method of this default handler.
The method is invoked on the same scope as the other handlers. That is the
target passed-in on construction.
var overload:Overload = new Overload(this);
overload.addHandler([String], methodWithStringArgument);
overload.addHandler([Number], methodWithNumberArgument);
overload.setDefaultHandler(function() {
trace(arguments.length + " arguments were used.");
});
return overload.forward(arguments);
If the passed-in method is null, undefined or not of
type "function" the default handler gets removed.
method | the method of the handler to invoke if no added handler matches the overload arguments |
public function removeDefaultHandler(Void):VoidRemoves the default handler.
This handler is used if no other handler matches to a list of arguments.
public function addHandlerByHandler(handler:OverloadHandler):Void
Adds the passed-in handler.
Overload handlers are used to determine the method to forward to. This is done using the methods OverloadHandler.matches and OverloadHandler.isMoreExplicit. If both conditions hold true the method invocation is forwarded to the method of the handler, that gets returned by the OverloadHandler.getMethod method.
If the passed-in handler is null or undefined no
actions will take place.
handler | the new overload handler to add |
public function addHandlerByValue(argumentsTypes:Array, method:Function):OverloadHandler
Adds a new SimpleOverloadHandler instance, that gets configured with the
passed-in argumentsTypes and method.
Overload handlers are used to determine the method to forward to. This is done using the methods OverloadHandler.matches and OverloadHandler.isMoreExplicit. If both conditions hold true the method invocation is forwarded to the method of the handler, that gets returned by the OverloadHandler.getMethod method.
The passed-in argumentsTypes are the types of arguments the method
expects from the real arguments to have. The SimpleOverloadHandler does
its matches and explicity checks upon these arguments' types.
The passed-in method is the method to invoke if the added handler
matches the real arguments and if it is the most explicit handler among all
matching ones.
argumentsTypes | the arguments' types of the overload handler |
method | the method corresponding to the passed-in argumentsTypes
|
the newly created overload handler
public function removeHandler(handler:OverloadHandler):Void
Removes the passed-in handler.
All occurrences of the passed-in handler are removed.
handler | the overload handler to remove |
public function forward(args:Array)
Forwards to the appropriate overload handler depending on the passed-in
args.
This is not done by using the OverloadHandler.execute method but
manually by using apply on the method returned by the
OverloadHandler.getMethod method. Invoking the method this way
increases the number of possible recurions with overlaoded methods.
If the args array is null or undefined an empty array
is used instead.
If no overload handler matches, the default overload handler will be used if it has been set.
Overload handlers are supposed to have the same type signature if the
OverloadHandler.isMoreExplicit method returns null.
the return value of the invoked method
| UnknownOverloadHandlerException | if no adequate overload handler could be found |
| SameTypeSignatureException | if there exist at least two overload handlers with the same type siganture, that means their arguments' types are the same |
public function getMatchingHandler(args:Array):OverloadHandlerReturns the most explicit overload handler from the array of matching handlers.
If the args array is null or undefined an empty array
is used instead.
If no handler matches the default handler gets returned if it has been set.
Overload handlers are supposed to have the same type signature if the
OverloadHandler.isMoreExplicit method returns null.
args | the arguments that shall match to a specific overload handler |
the most explicit overload handler
| UnknownOverloadHandlerException | if no adequate overload handler could be found |
| SameTypeSignatureException | if there exist at least two overload handlers with the same type siganture, that means their arguments' types are the same |