[Show Table of Contents]	9 Working with ActionScript	[Hide Table of Contents]

Previous 9.5.5 Augmenting Class definitions with Metadata	Home Up One Level

9.5.6 Trace Statement Processing

The trace() function call is a built-in function in the Flash player for outputting information to the Flash environment console. This function is case-insensitive, regardless of the player version it is targeted at and must take one single argument, which is output to the console.

9.5.6.1 Trace Statement Removal

Trace statements are generally only used during development of an SWF application. Once development is complete, there is no reason to deploy the SWF with the embedded trace statements - this will often cause the SWF to be significantly larger than it needs to be, execute slower and possible compromise the security of an application. However, it is also desirable to retain the trace statement in the code for continued development.

Rather than remove all trace statements manually, it is possible for KineticFusion to remove all trace() function calls from generated code. This will increase both execution speed and reduce the output movie size. Removing trace statements may have side-effects however, as the expression passed as an argument to the function is also discarded For example:

i=0;
while( i < 10)
    trace( i++); // discarded so loop becomes infinite

These side effects can also be useful as the trace() function can be used to embed enhanced debugging calls during development, and these can be stripped out automatically on production.

To remove trace statements from an output SWF movie, set the value of the configuration property, kinesis.actionscript.removeTraceStatements to false. This property can be set can be set either in the KineticFusion configuration file ($INSTALL_DIR/config/KineticFusion.properties) or on the command line.

9.5.6.2 Trace Statement Replacement

While the trace() function is a very common way of adding debug information to ActionScript the output is restricted to the Macromedia Flash development environment and trace output cannot normally be caught from a running SWF movie. Thankfully there are a growing number of powerful third-party logging components and debugging tools available that provide superior functionality.

KineticFusion 3.0 can now replace all trace() statements at compile-time with a user-specified ActionScript fragment that will reroute all tracing calls to the debugging library of choice for the user. A new configuration property, kinesis.actionscript.replaceTraceStatement, has been introduced to define the script fragment and this can be set either in the KineticFusion configuration file ($INSTALL_DIR/config/KineticFusion.properties) or on the command line.

The code fragment is normally a single line of code but it can also contain compound and multiple statements separated by semicolons. For example, in the KineticFusion.properties file, the trace fragment can be defined as:

kinesis.actionscript.replaceTraceStatement=Debug.trace( __ARG, Debug.trace);

kinesis.actionscript.replaceTraceStatement= if ( Debug.traceEnabled) Debug.trace( __ARG, Debug.trace);

In order to ensure that this feature is fully compatible with the Macromedia compiler, the trace statement that is replaced is case-insensitive and must have a single argument. To pass compound information into the trace function, a new object can be created that contains all the required arguments. For example:

trace( "Column List", myColumns); // This is illegal and will not be accepted by the Macromedia compiler

Instead, write:

trace( {heading:"Column List", data:myColumns}); // Single argument is always OK

The script fragment used to replace the trace statements supports placeholder identifiers so that arbitrary parameters can be passed to the logging system. The following placeholder identifiers are currently supported:

__ARG: The single argument to the original trace statement
__CLASS: The name of the class containing the trace statement. This is a String constant.
__METHOD: The name of the class method containing the trace statement. This is a String constant.
__FILE: The name of the file containing the trace statement. This is a String constant.
__LINE: The line on which the trace statement was defined. This is a Number constant.

For example, to replace all trace() calls to call to a static method if a logging class, the trace statement could be represented as:

kinesis.actionscript.replaceTraceStatement=Logger.log( __CLASS, __ARG, __LINE);

The Logger class can then dispatch the incoming trace call based on the calling class and the specified arguments.

Care should be taken that the code that performs the tracing functionality does not, itself, contain a trace() statement as this can cause an infinite loop.

9.5.6.3 Tracing Alternatives

Developers have a choice of how they wish to continue to add tracing statements to an application. Obviously, once a Logger wrapper class has been developed, there is no need to rewrite any logging code in order to change the logging framework implementation. This change is easily encapsulated in the Logger class itself. However, an advantage of using trace() function replacement is that trace statements can be completely removed from an output SWF using the kinesis.actionscript.removeTraceStatements configuration option. This permits all trace statements to be permanently removed from an output SWF. If you use your own Logger class as an wrapper around your chosen logging system, these statements would all have to be removed from your code manually.



Previous 9.5.5 Augmenting Class definitions with Metadata	Home Up One Level