+Show TOC
×Hide TOC

Logger

Kind of class:	class
Inherits from:	none
Version:	1.0
Author:	Francis Bourre
Classpath:	com.bourre.log.Logger
File last modified:	Wednesday, 31 October 2007, 07:35:29

► View source

▼ Hide source

/*
 * Copyright the original author or authors.
 * 
 * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.mozilla.org/MPL/MPL-1.1.html
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
/**
 * {@code Logger} defines based class/method for Logging API.
 * 
 * <p>Use {@link Logger.LOG} / {@link #log} methods to log messages
 * throw all registred {@link LogListener} listeners.
 * 
 * <p>{@link #addLogListener} and {@link #removeLogListener} allow to add / remove
 * log listeners (tracer) from logger repository.
 * 
 * <p>Messages can be filtered by differents {@link LogLevel} level and using some
 * {@link LogChannel} definition.
 * 
 * <p>Take a look at {@link com.bourre.utils} to see all available {@link LogListener}
 * concrete implementation. (cf SosTracer & LuminicTracer)  
 *   
 * <p>Example
 * <code>
 *      //Log all internal messages from Pixlib framework
 *   var oLogger : Logger = Logger.getInstance();
 *   oLogger.addLogListener( SosTracer.getInstance(), PixlibDebug.channel );
 *   
 *   oLogger.log("Logging API ready", LogLevel.INFO);
 * </code>
 * 
 * @author Francis Bourre
 * @version 1.0
 */

import com.bourre.events.EventBroadcaster;
import com.bourre.log.LogChannel;
import com.bourre.log.LogEvent;
import com.bourre.log.LogLevel;
import com.bourre.log.LogListener;
import com.bourre.log.PixlibStringifier;

class com.bourre.log.Logger
{
    //-------------------------------------------------------------------------
    // Private properties
    //-------------------------------------------------------------------------
    
    private static var _oI:Logger;
    private var _oLevel:LogLevel;
    private var _oEB : EventBroadcaster;
    
    
    //-------------------------------------------------------------------------
    // Public API
    //-------------------------------------------------------------------------
    
    public static function getInstance() : Logger
    {
        return (_oI != undefined) ? _oI : Logger._init();
    }
    
    
    /**
     * Sends message to logging API.
     * 
     * <p>Messages are send to all {@link LogListener} instances added 
     * with {@code #addLogListener} method.
     * 
     * <p>Level filter can be defined with {@link #SETLEVEL} / {@link #GETLEVEL}
     * methods
     * 
     * @param o Log message
     * @param oLevel (optional) A {@link LogLevel} instance (log level)
     * @param channel (optional) A {@link LogChannel} instance (log filter)
     */
    public static function LOG( o, oLevel:LogLevel, channel:LogChannel ) : Void
    {
        getInstance().log( o, oLevel, channel );
    }
    
    /**
     * Defines log level filter.
     * 
     * <p>All listed values for level are available : 
     * <ul>
     *   <li>{@link LogLevel.DEBUG}</li>
     *   <li>{@link LogLevel.INFO}</li>
     *   <li>{@link LogLevel.WARN}</li>
     *   <li>{@link LogLevel.ERROR}</li>
     *   <li>{@link LogLevel.FATAL}</li>
     * </ul>
     * 
     *  @param oLevel A {@link LogLevel} instance
     */
    public static function SETLEVEL( oLevel:LogLevel ) : Void
    {
        getInstance()._oLevel =  oLevel;
    }
    
    /**
     * Returns current log level filter.
     * 
     * @return A {@link LogLevel} instance
     */
    public static function GETLEVEL() : LogLevel
    {
        return getInstance()._oLevel;
    }
    
    /**
     * Adds passed-in {@code listener} to {@code Logger} event.
     * 
     * <p>Uses passed-in {@code channel} to filter message.
     * 
     * @param listener A {@code LogListener} instance
     * @param channel (optional) log channel filter
     */
    public function addLogListener( listener : LogListener, channel:LogChannel ) : Void
    {
        if ( !channel )
        {
            _oEB.addListener( listener, listener.onLog );
        } else
        {
            _oEB.addEventListener( channel, listener, listener.onLog );
        }
    }
    
    /**
     * Removes passed-in {@code listener} for receiving {@code Logger} events.
     * 
     * @param listener A {@code LogListener} instance
     * @param channel (optional) log channel filter
     */
    public function removeLogListener( listener : LogListener, channel : LogChannel ) : Void
    {
        if ( !channel )
        {
            _oEB.removeListener( listener );
        } else
        {
            _oEB.removeEventListener( channel, listener );
        }
    }
    
    /**
     * Sends message to logging API.
     * 
     * <p>Messages are send to all {@link LogListener} instances added 
     * with {@code #addLogListener} method.
     * 
     * <p>Level filter can be defined with {@link #SETLEVEL} / {@link #GETLEVEL}
     * methods
     * 
     * @param o Log message
     * @param oLevel (optional) A{@link LogLevel} instance (log level)
     * @param channel (optional) A {@link LogChannel} instance (log filter)
     */
    public function log( logContent, oLevel:LogLevel, channel:LogChannel ) : Void
    {    
        if (oLevel == undefined) oLevel = LogLevel.DEBUG;
        if (oLevel.isEnabled()) _oEB.broadcastEvent( new LogEvent( oLevel, logContent, channel ) );
    }
    
    /**
     * Returns the string representation of this instance.
     * @return the string representation of this instance
     */
    public function toString() : String 
    {
        return PixlibStringifier.stringify( this );
    }
    
    
    //-------------------------------------------------------------------------
    // Private implementation
    //-------------------------------------------------------------------------
    
    /**
     * Inits a new {@code Logger} instance and properties.
     * 
     * <p>Used by {@link #getInstance} method to build
     * a new {@code Logger} instance.
     * 
     * @return A {@code Logger} instance
     */
    private static function _init() : Logger
    {
        _oI = new Logger();
        return _oI;
    }
    
    /**
     * Constructs a new {@code Logger} instance.
     * 
     * <p>Constructor is private, uses {@link #getInstance) method
     * for {@code Logger} instanciation.
     */
    private function Logger()
    {
        _oEB = new EventBroadcaster( this );
        _oLevel = LogLevel.DEBUG;
    }
}

Logger defines based class/method for Logging API.

Use Logger.LOG / log methods to log messages
throw all registred LogListener listeners.

addLogListener and removeLogListener allow to add / remove
log listeners (tracer) from logger repository.

Messages can be filtered by differents LogLevel level and using some
LogChannel definition.

Take a look at com.bourre.utils to see all available LogListener
concrete implementation. (cf SosTracer & LuminicTracer)

Example

//Log all internal messages from Pixlib framework
var oLogger : Logger = Logger.getInstance();
oLogger.addLogListener( SosTracer.getInstance(), PixlibDebug.channel );

oLogger.log("Logging API ready", LogLevel.INFO);

Summary

Class methods

getInstance
LOG
SETLEVEL
GETLEVEL

Instance methods

addLogListener
removeLogListener
log
toString

Class methods

getInstance

static function getInstance (

) : Logger

GETLEVEL

static function GETLEVEL (

) : LogLevel

Returns current log level filter.

Returns:

A LogLevel instance

LOG

static function LOG (

oLevel:LogLevel, channel:LogChannel) : Void

Sends message to logging API.

Messages are send to all LogListener instances added
with #addLogListener method.

Level filter can be defined with SETLEVEL / GETLEVEL
methods

Parameters:

o :

Log message

oLevel :

(optional) A LogLevel instance (log level)

channel:

(optional) A LogChannel instance (log filter)

SETLEVEL

static function SETLEVEL (

oLevel:LogLevel) : Void

Defines log level filter.

All listed values for level are available :

LogLevel.DEBUG
LogLevel.INFO
LogLevel.WARN
LogLevel.ERROR
LogLevel.FATAL

Parameters:

oLevel:

A LogLevel instance

Instance methods

addLogListener

function addLogListener (

listener:LogListener, channel:LogChannel) : Void

Adds passed-in listener to Logger event.

Uses passed-in channel to filter message.

Parameters:

listener:

A LogListener instance

channel :

(optional) log channel filter

log

function log (

oLevel:LogLevel, channel:LogChannel) : Void

Sends message to logging API.

Messages are send to all LogListener instances added
with #addLogListener method.

Level filter can be defined with SETLEVEL / GETLEVEL
methods

Parameters:

o :

Log message

oLevel :

(optional) ALogLevel instance (log level)

channel:

(optional) A LogChannel instance (log filter)

removeLogListener

function removeLogListener (

listener:LogListener, channel:LogChannel) : Void

Removes passed-in listener for receiving Logger events.

Parameters:

listener:

A LogListener instance

channel :

(optional) log channel filter

toString

function toString (

) : String

Returns the string representation of this instance.

Returns:

the string representation of this instance