13 Logging Configuration

Since logging configuration changes very often (depending on deployment scenario and depending on personal settings of developers) it is often best to keep them in external XML configuration files. For that reason Parsley offers a set of XML tags for logging configuration.

For Flex Application you can use XML tags to build standard Flex LogTargets. For Flash Applications Parsley includes a separate set of tags that build Loggers for the Spicelib Logging Framework instead. In the final section we'll demonstrate how you can configure the internal log output of Parsley Framework classes.

13.1 Logging Configuration for Flex

If you want to use the Flex Logging API you have two options: You can configure LogTargets in MXML with the builtin MXML tags - in this case no Parsley integration is required. For details on using the Flex Loggin API see the Flex LiveDocs.

If you prefer using external XML files for your logging configuration you can use an XML tag extension of Parsley that creates LogTargets:

<objects 
    xmlns="http://www.spicefactory.org/parsley"
    xmlns:log="http://www.spicefactory.org/parsley/flex/logging"
    
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.spicefactory.org/parsley 
      http://www.spicefactory.org/parsley/schema/2.0/parsley-core.xsd 
    http://www.spicefactory.org/parsley/flex/logging 
      http://www.spicefactory.org/parsley/schema/2.0/parsley-logging-flex.xsd"
    >
    
    <log:target level="error">
        <log:filter>org.spicefactory.*</log:filter>        
    </log:target>
    <log:target level="debug">
        <log:filter>com.bookstore.*</log:filter>    
        <log:filter>com.mycompany.util.*</log:filter>    
    </log:target>
    
    <!-- other object definitions -->
    
</objects>

With the example configuration above you will see only error from internal logs of Spicefactory framework classes while seeing all debug logs from your own application classes.

The default target type created by this tag is a TraceTarget. You can explicitly declare other target types:

<log:target level="debug" type="com.bookstore.util.CustomLogTarget">
    <log:filter>com.bookstore.*</log:filter>        
</log:target>

Since this is an extension it has to be initialized explicitly before using the XmlContextBuilder:

FlexLoggingXmlSupport.initialize();

13.2 Logging Configuration for Flash

For Flash Applications Spicelib offers its own Logging Framework. For details on how to use it see 20 Logging for Flash Applications in the Spicelib Manual. Parsley includes an XML tag extension that you can use to configure loggers for that framework:

<objects 
    xmlns="http://www.spicefactory.org/parsley"
    xmlns:log="http://www.spicefactory.org/parsley/flash/logging"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.spicefactory.org/parsley 
      http://www.spicefactory.org/parsley/schema/2.0/parsley-core.xsd 
    http://www.spicefactory.org/parsley/flash/logging 
      http://www.spicefactory.org/parsley/schema/2.0/parsley-logging-flash.xsd"
    >
    
    <log:factory id="logFactory">
        <log:appender ref="appender" threshold="trace"/>
        <log:logger name="org.spicefactory" level="warn"/>
        <log:logger name="com.bookstore" level="debug"/>
    </log:factory>
    
    <object id="appender" type="org.spicefactory.lib.flash.logging.impl.TraceAppender"/>
    
</objects>

The Appenders that the Logging Framework should use can be defined with regular Parsley object tags. You can then refer to these definitions in the log:appender tag. You can add any number of loggers to the configuration and set their level individually. Note that the names always lead to a hierarchical logger structure, you don't have to specify an '*' at the end of logger names like with the Flex Logging API.

You always have to add at least one Appender, because a Logger only dispatches LogEvents, which all Appenders listen to. Those Appenders then route the messages to a final destination (console, socket, file, etc.). In the example above we just use the builtin TraceAppender which uses the Flash Players trace function for log output.

There is also a second Appender released with the Spicelib: SOSAppender. This Appender routes messages to SOS (http://sos.powerflasher.com/), a free logging tool from Powerflasher, that allows to colorize and filter log messages.

In the example above we set the threshold for the TraceAppender to TRACE. This threshold is a second level of filtering. All messages that were not filtered by the log level of the individual logger will again be checked against the threshold of the Appender. In this case we chose the TRACE level which is the lowest rank of all levels so all messages will pass.

Since this is an extension it has to be initialized explicitly before using the XmlContextBuilder:

FlashLoggingXmlSupport.initialize();

13.3 Configuration for Parsley Framework Logs

Finally you may want to see the output by Parsleys (and Spicelibs) internal loggers which might help with debugging. For the internal logs we had to tackle the problem that Parsley and Spicelib can be used in Flex and Flash Applications, and thus with the Flex Logging API or the Spicelib Logging Framework. So we created a log wrapper, similar to Commons Logging in the Java world, that would delegate the actual log output to any log delegate we feed it with.

You can obtain such a delegating logger through the LogContext class:

LogContext.getLogger(MyClass);

You may even use those delegating loggers in your own code. It's not very useful for building applications, since they are either Flex or Flash Applications so you can simply decide which Logging API to use. But if you create reusable libraries that you might want to use with or without Flex, this delegate might come in handy.

Finally the actual delegate must be initialized, depending on the environment.

Setting the delegate for the Flex Logging API

In most cases the delegates will be initialized automatically. That happens if you either use one of the static entry point methods of the FlexContextBuilder class or if you use the XML configuration extension tags as shown in 13.1 Logging Configuration for Flex.

If you are using neither of those you have to initialize the delegate manually:

LogContext.factory = new FlexLogFactory();

Setting the delegate for the Spicelib Logging Framework

For Spicelib Logging the delegate will be set automatically when you use the custom XML configuration tags as shown in 13.2 Logging Configuration for Flash.

If you are not using XML configuration you can read 20.3.4 Programmatic Configuration. There is an code example where the last line sets the delegate:

LogContext.factory = factory;