org.as3commons.logging.util.xml Details

Public Methods

	Function		Defined By
		xmlToSetup(xml:XML, targetTypes:Object, instances:Object = null):ILogSetup Creates a ILogSetup from a setup or rule nodes.	org.as3commons.logging.util.xml
		xmlToTarget(xml:XML, targetTypes:Object, targetInstances:Object = null):ILogTarget Creates a ILogTarget from a xml-target-node.	org.as3commons.logging.util.xml

Function detail

xmlToSetup

()

function

public function xmlToSetup(xml:XML, targetTypes:Object, instances:Object = null):ILogSetup

Since :

2.6

Creates a ILogSetup from a setup or rule nodes.

Important: nodes for this setups have to use the http://as3commons.org/logging1 namespace. A matching xml-schema can be found on our page and in the svn.

A setup node will be transformed into a MergedSetup of setups to be applied one after another.

A rule node will be transformed into various types of setups depending on the given attributes.

A setup-node merges rule nodes together much like RegExpSetup. This means you can define as many rule nodes within a setup as you want.

     var mergedSetup: ILogSetup = xmlToSetup(
       <setup xmlns="http://as3commons.org/logging/1">
         <rule />
         <rule />
       </setup>
       , {} // soon more to that
     );

It is also possible to define targets within a setup node.

     var mergedSetup: ILogSetup = xmlToSetup(
       <setup xmlns="http://as3commons.org/logging/1">
         <target type="trace" name="common"/>
         <rule />
         <rule />
       </setup>
       , {}
     );

Its will not work! The setup mechanism doesn't know how to link type with trace, so we have to tell it how to do it.

     var mergedSetup: ILogSetup = xmlToSetup(
       <setup xmlns="http://as3commons.org/logging/1">
         <target type="trace" name="common"/>
         <rule />
         <rule />
       </setup>
       , {trace: TraceTarget}
     );

That should do the trick. targets defined like this will not be used. For a target to be active it has to be used within a rule node.

     var mergedSetup: ILogSetup = xmlToSetup(
       <setup xmlns="http://as3commons.org/logging/1">
         <target type="trace" name="common"/>
         <rule>
           <target-ref ref="common" />
         </rule>
         <rule />
       </setup>
       , {trace: TraceTarget}
     );

This can also be writting by passing-in the target as instance!

     var mergedSetup: ILogSetup = xmlToSetup(
       <setup xmlns="http://as3commons.org/logging/1">
         <rule>
           <target-ref ref="common" />
         </rule>
         <rule />
       </setup>
       , {}, {common: new TraceTarget()}
     );

Now the first rule sends out to the trace target.But the second rule has no target defined, yet its signature is same as of the former rule so it will override the first rule with an null target.

It is possible to distinguish rules using 3 properties: level, name and person. In detail about it later

     var mergedSetup: ILogSetup = xmlToSetup(
       <setup xmlns="http://as3commons.org/logging/1">
         <rule>
           <target-ref ref="common" />
         </rule>
         <rule level="ERROR"/>
       </setup>
       , {}, {common: new TraceTarget()}
     );

Now just the ERROR and FATAL statements will be set to null. This can be simpler written like:

     var mergedSetup: ILogSetup = xmlToSetup(
       <setup xmlns="http://as3commons.org/logging/1">
         <rule level="DEBUG_ONLY|INFO_ONLY|WARN_ONLY">
           <target-ref ref="common" />
         </rule>
       </setup>
       , {}, {common: new TraceTarget()}
     );

Now the setup contains just one rule, so its also possible to just parse the rule.

     var mergedSetup: ILogSetup = xmlToSetup(
       <rule level="DEBUG_ONLY|INFO_ONLY|WARN_ONLY" xmlns="http://as3commons.org/logging/1">
         <target-ref ref="common" />
       </rule>
       , {}, {common: new TraceTarget()}
     );

The Level in detail. You can define a level traditionally using:

Code	Meaning
DEBUG or ALL	All messages will be displayed.
INFO	Only debug messages will be hidden
WARN	Info and Debug messages will be hidden.
ERROR	Only Error and Fatal messages will be shown.
FATAL	Only Fatal messages will be shown.
NONE	No messages will be shown.

But its also possible to choose just certain levels.

Code	Meaning
DEBUG_ONLY	Just debug messages will be shown.
INFO_ONLY	Just info messages will be shown.
WARN_ONLY	Just warn messages will be shown.
ERROR_ONLY	Just error messages will be shown.
FATAL_ONLY	Just fatal messages will be shown.

With a "|" (or) you can mix the levels you want to display.

Code	Meaning
DEBUG_ONLY\|INFO_ONLY	Show info and debug message.
ERROR\|DEBUG_ONLY	Show error, fatal and debug message.
FATAL_ONLY\|WARN_ONLY\|DEBUG_ONLY	Show fatal, warn and debug message.

The name and the person properties can be used to filter just loggers of certain names.

     var mergedSetup: ILogSetup = xmlToSetup(
       <rule name="/^org\\.as3commons" xmlns="http://as3commons.org/logging/1">
         <target-ref ref="common" />
       </rule>
       , {}, {common: new TraceTarget()}
     );
     getLogger("org.as3commons.test").info("hi"); // will be traced
     getLogger("my.company").info("hi"); // will NOT be traced

Make sure that you use double escaping with "\\".

Parameters

	`xml:XML` — `setup` or `rule` from the xml-definition.

	`targetTypes:Object` — Class lookup to be used for `target` nodes.

	`instances:Object` (default = `null`) — Instance lookup to be used for `target-ref` nodes.

Returns

ILogSetup — a new setup to be used for logging.

xmlToTarget

()

function

public function xmlToTarget(xml:XML, targetTypes:Object, targetInstances:Object = null):ILogTarget

Since :

2.6

Creates a ILogTarget from a xml-target-node.

The as3commons logging setup process allows to define targets to be generated.

     <target xmlns="http://as3commons.org/logging/1" type="SOS"/>

The types allowed in the "type" field are passed in to the method (so: there is no fixed set of types allowed, which reduces the effective .swf size as you allow just the targets you need.

Targets can have primitive constructor parameters.

     <target xmlns="http://as3commons.org/logging/1" type="SOS">
       <arg value="{message} / {logLevel}"/>
     </target>

Those parameters will be passed to the the classes constructor function.

It automatically converts strings to int/Boolean/Number values if they are equal.

Besides primitive types it is also possible to pass-in other targets.

     <target xmlns="http://as3commons.org/logging/1" type="FrameBufferTarget">
       <arg>
         <target type="TraceTarget"/>
       </arg>
     </target>

If a value is given it will always take the value!

It is also possible to pass-in target references like:

     <target xmlns="http://as3commons.org/logging/1" type="FrameBufferTarget">
       <arg>
         <target-ref ref="console-text-field"/>
       </arg>
     </target>

You have to use eighter a target reference or a target, both are not allowed.

We have a limit of maximum 14 constructor arguments that you can pass-in.

Much like constructor arguments its possible to set properties on the targets like this:

     <target xmlns="http://as3commons.org/logging/1" type="TraceTarget">
       <property name="format" value="{message}" />
     </target>

If a constructor throws an error for which reason soever null will be returned. If a property throws an error it will be just ignored. Any problems that occur during initation get send to the as3commons logging system.

Parameters

	`xml:XML` — XML Node to be parsed

	`targetTypes:Object` — Class lookup to be used for `target` nodes.

	`targetInstances:Object` (default = `null`) — Instance lookup to be used for `target-ref` nodes.

Returns

ILogTarget — ILogTarget instance if the instance was evaluatable for a target-node, else null

API Documentation	All Packages \| All Classes \| Index \| Frames No Frames
Package	Functions