org.as2lib.core.BasicInterface +--org.as2lib.env.except.Throwable
Throwable is the basic interface for every class that is thrown.
You can actually throw every class even if it does not implement this interface but it is recommended to strictly use this interface for every throwable. Using it produces clarity and setups a standard.
It prescribes implementing classes to provide key functionalities that help you a lot when an exception is thrown and you do not catch it.
The first thing is the message. The message contains detaild information about the problem that occurred.
The second is the stack trace. The stack trace contains at least the method that actually threw the throwable. It can also contain the method that invoked the method that threw the throwable and so on.
The third feature is the cause. Let's say a throwable is thrown and you catch it. After catching it you want to throw a new throwable, that is of another type (maybe a application specific exception while the catched was a generic one from a framework) and contains another message that describes the problem from the point of view of the catching method. In such a case we of course do not want to lose the information the catched throwable provides, that caused the throwing of the new throwable. We thus create the new throwable and initialize its cause, the catched throwable, to get a more comprehensive error message.
Working with throwables in ActionScript is a little buggy and can be a pain to use if you do not know to what you have to pay attention.
The first thing is that if you catch a throwable, the type of it must be fully
qualified. You cannot import the throwable and then only use its name, because
Flash will then not recognize the type, and will not catch the thrown throwable
(Note that it actually works when working on the timeline. The problem only occures
within classes. But I would nevertheless always use fully qualified names to guard
against potential errors.). Thus write your catch-blocks always the following way.
try {
...
} catch (e:org.as2lib.env.except.IllegalArgumentException) {
...
}
The second problem occurs when working with Flex. The throwable type in the
catch-block's signature must always be a sub-class of the class Error
(which is the native 'throwable' of ActionScript). Because of that it is not
possible to catch throwables by interfaces, like this interface. If you simply want
to catch all throwables that may be thrown in your application do not specify a
throwable type or use Error if you are really really sure that all your
concrete throwable implementations extend this class. Note that the
Exception and FatalException classes extend the Error class,
so they and any sub-classes can be used with Flex.
public function getStackTrace(Void):ArrayReturns an array that contains StackTraceElement instances of the methods invoked before this throwable was thrown.
The last element is always the one that contains the actual method that threw the throwable.
The stack trace helps you a lot because it says you where the throwing of the throwable took place and also what arguments caused the throwing.
a stack containing the invoked methods until the throwable was thrown
public function addStackTraceElement(thrower, method:Function, args:Array):VoidAdds a stack trace element to the stack trace.
The new stack trace element is added to the end of the stack trace.
At some parts in your application you may want to add stack trace elements manually. This can help you to get a clearer image of what went where wrong and why. You can use this method to do so.
thrower | the object that threw, rethrew or forwarded (let pass) the throwable |
method | the method that threw, rethrew or forwarded (let pass) the throwable |
args | the arguments the method was invoked with when throwing, rethrowing or forwarding (leting pass) the throwable |
public function initCause(cause):ThrowableInitializes the cause of this throwable.
The cause can only be initialized once. You normally initialize a cause if you throw a throwable due to the throwing of another throwable. Thereby you do not lose the information the cause offers.
This method returns this throwable to have an easy way to initialize the
cause. Following is how you could use the cause mechanism.
try {
myInstance.invokeMethodThatThrowsAThrowable();
} catch (e:org.as2lib.env.except.Throwable) {
throw new MyThrowable("myMessage", this, arguments).initCause(e);
}
cause | the throwable that caused the throwing of this throwable |
this throwable itself
| IllegalStateException | if the cause has already been initialized |
public function getCause(Void)Returns the initialized cause.
The cause is the throwable that caused this throwable to be thrown.
the initialized cause
public function getMessage(Void):StringReturns the message that describes in detail what went wrong.
The message should be understandable, even for non-programmers. It should contain detailed information about what went wrong. And maybe also how the user that sees this message can solve the problem.
If the throwable was thrown for example because of a wrong collaborator or an illegal string or something similar, provide the string representation of it in the error message. It is recommended to put these between []-characters.
the message that describes the problem in detail