Every good framework must support output handling. Output handling is essential because it helps you during debugging and lets you find out information about the control flow of your program. You alse need a way to get output when you are not in the Flash environment and trace() thus won’t work.
The as2lib’s output handling offers support for this and is highly extensible. It is possible to replace almost every class with your custom one also this is hopefully not necessary. All the classes needed to handle output are located in the org.as2lib.env.out package. The base class is the Out class.
The most important operations in this class are setLevel(OutLevel), addHandler(OutHandler) and of cource the operations to actually print something out: log(String), debug(String), info(String), warning(String), error(Throwable) and fatal(Throwable). As you can see there exist several different output levels. The ones that are provided by us are: Out.ALL, Out.DEBUG, Out.INFO, Out.WARNING, Out.FATAL and Out.NONE. You can of course expand this list as you need it. If you set the OutLevel to for example Out.ERROR, error and fatal output wll be made. That means all output that is logically located under the set OutLevel will be made including the set OutLevel.
Another thing you can do is setting different OutHandlers. OutHandlers are responsible for printing the messages out in a well formatted way. An OutHandler can for example be the TraceHandler that just uses trace() to print out the information. But you can of course also add more complex OutHandlers that write the information into a text file or something like that.
When you now use for example the operation Out.log(String) what happens is that an OutWriteInfo (org.as2lib.env.out.info.OutWriteInfo) containing the String as well as the level will be passed to the write(OutWriteInfo) operation of all registered OutHandlers. In case of using fatal(Throwable) or error(Throwable) to write out Throwables an OutErrorInfo (org.as2lib.env.out.info.OutErrorInfo) containing the Throwable as well as the level will be passed to the error(OutErrorInfo) operation of all OutHandlers. The OutHandler is now responsible for stringifying the passed OutWriteInfo or OutErrorInfo. There already exist two Stringifier that do exactly this job. They reside in the org.as2lib.env.out.string package and are called WriteStringifier or ErrorStringifier respectively.
Click the following link for an UML diagram depicting the relationships between the various out classes: Output Handling: Class Diagram.
Read on for an example of how to use the as2lib’s out classes.
The usage is pretty simple. Just import the Out class, create a new instance of it, add the needed OutHandlers, set the OutLevel and print something out.
-
import org.as2lib.env.out.Out;
-
import org.as2lib.env.out.handler.TraceHandler;
-
-
var out:Out = new Out();
-
out.setLevel(Out.WARNING);
-
out.addHandler(new TraceHandler());
-
out.warning("I’m warning you!");
-
out.info("This output will not be made because the OutLevel is set to Out.WARNING.");
A custom handler that uses the predefined Stringifiers could look like the following TraceHandler (The TraceHandler is already part of the as2lib. We used it in the above example.):
-
import org.as2lib.env.out.OutHandler;
-
import org.as2lib.env.out.info.OutWriteInfo;
-
import org.as2lib.env.out.info.OutErrorInfo;
-
import org.as2lib.env.out.OutConfig;
-
import org.as2lib.core.BasicClass;
-
-
class org.as2lib.env.out.handler.TraceHandler extends BasicClass implements OutHandler {
-
public function write(info:OutWriteInfo):Void {
-
trace(OutConfig.getWriteStringifier().execute(info));
-
}
-
-
public function error(info:OutErrorInfo):Void {
-
trace(OutConfig.getErrorStringifier().execute(info));
-
}
-
}
The steps I have done to implement a custom OutHandler are creating a new class, letting it implement the OutHandler interface and defining the two methods write(OutWriteInfo) and error(OutErrorInfo). The stringify process is being done by the Stringifier set in the OutConfig. You can overwrite the set Stringifier to get custom output using the OutConfig.setWriteStringifier(Stringifier) or OutConfig.setErrorStringifier(Stringifier) operations.
Well, that’s it for now. You know everything to get started.
