Packagecom.threerings.util
Classpublic class Log

A simple logging mechanism. Log instances are created for modules, and the logging level can be configured per module in a hierarchical fashion. Typically, you should create a module name based on the full path to a class: calling getLog() and passing an object or Class will do this. Alternattely, you may create a Log to share in several classes in a package, in which case the module name can be like "com.foocorp.games.bunnywar". Finally, you can just create made-up module names like "mygame" or "util", but this is not recommended. You really should name things based on your packages, and your packages should be named according to Sun's recommendations for Java packages. Typical usage for creating a Log to be used by the entire class would be: public class MyClass { private static const log :Log = Log.getLog(MyClass); ... OR, if you just need a one-off Log: protected function doStuff (thingy :Thingy) :void { if (!isValid(thingy)) { Log.getLog(this).warn("Invalid thingy specified", "thingy", thingy); ....


Protected Properties
 PropertyDefined by
  _levels : Object
[static] A cache of log levels, copied from _setLevels.
Log
  _module : String
The module to which this log instance applies.
Log
  _setLevels : Object
[static] The configured log levels.
Log
  _targets : Array
[static] Other registered LogTargets, besides the trace log.
Log
Public Methods
 MethodDefined by
  
addTarget(target:LogTarget):void
[static] Add a logging target.
Log
  
debug(... args):void
Log a message with 'debug' priority.
Log
  
dumpStack(msg:String = "dumpStack"):void
[static] A convenience function for quickly printing a stack trace to the log, useful for debugging.
Log
  
error(... args):void
Log a message with 'error' priority.
Log
  
getLog(moduleSpec:*):Log
[static] Retrieve a Log for the specified module.
Log
  
info(... args):void
Log a message with 'info' priority.
Log
  
logStackTrace(error:Error):void
Log just a stack trace with 'warning' priority.
Log
  
removeTarget(target:LogTarget):void
[static] Remove a logging target.
Log
  
setLevel(module:String, level:int):void
[static] Set the log level for the specified module.
Log
  
setLevels(settingString:String):void
[static] Parses a String in the form of ":info;com.foo.game:debug;com.bar.util:warning" Semicolons separate modules, colons separate a module name from the log level.
Log
  
testing(... params):void
[static] A convenience function for quickly and easily inserting printy statements during application development.
Log
  
warning(... args):void
Log a message with 'warning' priority.
Log
Protected Methods
 MethodDefined by
  
argToString(arg:*):String
Safely format the argument to a String, calling the function if it is one.
Log
  
doLog(level:int, args:Array):void
Log
  
formatMessage(level:int, args:Array):String
Log
  
getLevel(module:String):int
[static] Get the logging level for the specified module.
Log
  
getTimeStamp():String
Log
  
stringToLevel(s:String):int
[static]
Log
Public Constants
 ConstantDefined by
  DEBUG : int = 0
[static] Log level constants.
Log
  ERROR : int = 3
[static]
Log
  INFO : int = 1
[static]
Log
  OFF : int = 4
[static]
Log
  WARNING : int = 2
[static]
Log
Protected Constants
 ConstantDefined by
  LEVEL_NAMES : Array
[static] The outputted names of each level.
Log
Property detail
_levelsproperty
protected static var _levels:Object

A cache of log levels, copied from _setLevels.

_moduleproperty 
protected var _module:String

The module to which this log instance applies.

_setLevelsproperty 
protected static var _setLevels:Object

The configured log levels.

_targetsproperty 
protected static var _targets:Array

Other registered LogTargets, besides the trace log.

Method detail
addTarget()method
public static function addTarget(target:LogTarget):void

Add a logging target.

Parameters
target:LogTarget
argToString()method 
protected function argToString(arg:*):String

Safely format the argument to a String, calling the function if it is one.

Parameters
arg:*

Returns
String
debug()method 
public function debug(... args):void

Log a message with 'debug' priority.

Parameters
... args — The first argument is the actual message to log. After that, each pair of parameters is printed in key/value form, the benefit being that if no log message is generated then toString() will not be called on the values. If any argument is a function, it is invoked with no args, so that you may avoid converting detailed data into a String unless the message is actually logged. A final parameter may be an Error, in which case the stack trace is printed.

Example 
        log.debug("Message", "key1", value1, "key2", value2, optionalError);

doLog()method 
protected function doLog(level:int, args:Array):voidParameters
level:int
 
args:Array
dumpStack()method 
public static function dumpStack(msg:String = "dumpStack"):void

A convenience function for quickly printing a stack trace to the log, useful for debugging.

Parameters
msg:String (default = "dumpStack")
error()method 
public function error(... args):void

Log a message with 'error' priority.

Parameters
... args — The first argument is the actual message to log. After that, each pair of parameters is printed in key/value form, the benefit being that if no log message is generated then toString() will not be called on the values. If any argument is a function, it is invoked with no args, so that you may avoid converting detailed data into a String unless the message is actually logged. A final parameter may be an Error, in which case the stack trace is printed.

Example 
        log.error("Message", "key1", value1, "key2", value2, optionalError);

formatMessage()method 
protected function formatMessage(level:int, args:Array):StringParameters
level:int
 
args:Array

Returns
String
getLevel()method 
protected static function getLevel(module:String):int

Get the logging level for the specified module.

Parameters
module:String

Returns
int
getLog()method 
public static function getLog(moduleSpec:*):Log

Retrieve a Log for the specified module.

Parameters
moduleSpec:* — can be a String of the module name, or any Object or Class to have the module name be the full package and name of the class (recommended).

Returns
Log
getTimeStamp()method 
protected function getTimeStamp():String

Returns
String
info()method 
public function info(... args):void

Log a message with 'info' priority.

Parameters
... args — The first argument is the actual message to log. After that, each pair of parameters is printed in key/value form, the benefit being that if no log message is generated then toString() will not be called on the values. If any argument is a function, it is invoked with no args, so that you may avoid converting detailed data into a String unless the message is actually logged. A final parameter may be an Error, in which case the stack trace is printed.

Example 
        log.info("Message", "key1", value1, "key2", value2, optionalError);

logStackTrace()method 
public function logStackTrace(error:Error):void

Log just a stack trace with 'warning' priority. Deprecated, sorta. Just use warning("Message", error);

Parameters
error:Error
removeTarget()method 
public static function removeTarget(target:LogTarget):void

Remove a logging target.

Parameters
target:LogTarget
setLevel()method 
public static function setLevel(module:String, level:int):void

Set the log level for the specified module.

Parameters
module:String — The smallest prefix desired to configure a log level. For example, you can set the global level with Log.setLevel("", Log.INFO); Then you can Log.setLevel("com.foo.game", Log.DEBUG). Now, everything logs at INFO level except for modules within com.foo.game, which is at DEBUG.
 
level:int
setLevels()method 
public static function setLevels(settingString:String):void

Parses a String in the form of ":info;com.foo.game:debug;com.bar.util:warning" Semicolons separate modules, colons separate a module name from the log level. An empty string specifies the top-level (global) module.

Parameters
settingString:String
stringToLevel()method 
protected static function stringToLevel(s:String):intParameters
s:String

Returns
int
testing()method 
public static function testing(... params):void

A convenience function for quickly and easily inserting printy statements during application development.

Parameters
... params
warning()method 
public function warning(... args):void

Log a message with 'warning' priority.

Parameters
... args — The first argument is the actual message to log. After that, each pair of parameters is printed in key/value form, the benefit being that if no log message is generated then toString() will not be called on the values. If any argument is a function, it is invoked with no args, so that you may avoid converting detailed data into a String unless the message is actually logged. A final parameter may be an Error, in which case the stack trace is printed.

Example 
        log.warning("Message", "key1", value1, "key2", value2, optionalError);

Constant detail
DEBUGconstant
public static const DEBUG:int = 0

Log level constants.

ERRORconstant 
public static const ERROR:int = 3
INFOconstant 
public static const INFO:int = 1
LEVEL_NAMESconstant 
protected static const LEVEL_NAMES:Array

The outputted names of each level. The last one isn't used, it corresponds with OFF.

OFFconstant 
public static const OFF:int = 4
WARNINGconstant 
public static const WARNING:int = 2



Copyright © 2007-2009 Three Rings Design, Inc.