Mailing-List: contact commits-help@logging.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@logging.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1230522 - /logging/log4php/trunk/src/main/php/Logger.php
Date: Thu, 12 Jan 2012 13:33:03 -0000
To: commits@logging.apache.org
From: ihabunek@apache.org
Message-Id: <20120112133303.9751A2388A56@eris.apache.org>

Author: ihabunek
Date: Thu Jan 12 13:33:03 2012
New Revision: 1230522

URL: http://svn.apache.org/viewvc?rev=1230522&view=rev
Log:
Reorganised the Logger class:
- improved phpdoc
- grouped static methods and properties together
- added missing isXxxxEnabled() methods
- no significant functionality changes

Modified:
    logging/log4php/trunk/src/main/php/Logger.php

Modified: logging/log4php/trunk/src/main/php/Logger.php
URL: http://svn.apache.org/viewvc/logging/log4php/trunk/src/main/php/Logger.php?rev=1230522&r1=1230521&r2=1230522&view=diff
==============================================================================
--- logging/log4php/trunk/src/main/php/Logger.php (original)
+++ logging/log4php/trunk/src/main/php/Logger.php Thu Jan 12 13:33:03 2012
@@ -48,7 +48,10 @@ class Logger {
 	 */
 	private $additive = true;
 	
-	/** The Logger's fully qualified class name. */
+	/** 
+	 * The Logger's fully qualified class name.
+	 * TODO: Determine if this is useful. 
+	 */
 	private $fqcn = 'Logger';
 
 	/** The assigned Logger level. */
@@ -60,24 +63,9 @@ class Logger {
 	/** The parent logger. Set to null if this is the root logger. */
 	private $parent;
 	
-	/**
-	 * A collection of appenders associated with this logger.
-	 * @see LoggerAppender
-	 */
+	/** A collection of appenders linked to this logger. */
 	private $appenders = array();
 
-	/** The logger hierarchy used by log4php. */
-	private static $hierarchy;
-	
-	/** 
-	 * Holds the configurator. 
-	 * @var LoggerConfigurator 
-	 */
-	private static $configurator;
-	
-	/** Inidicates if log4php has been initialized */
-	private static $initialized = false;
-	
 	/**
 	 * Constructor.
 	 * @param string $name Name of the logger.	  
@@ -102,23 +90,10 @@ class Logger {
 		return $this->parent;
 	}
 	
-	/**
-	 * Returns the hierarchy used by this Logger.
-	 * Caution: do not use this hierarchy unless you have called initialize().
-	 * To get Loggers, use the Logger::getLogger and Logger::getRootLogger methods
-	 * instead of operating on on the hierarchy directly.
-	 * 
-	 * @deprecated - will be moved to private
-	 * @return LoggerHierarchy
-	 */
-	public static function getHierarchy() {
-		if(!isset(self::$hierarchy)) {
-			self::$hierarchy = new LoggerHierarchy(new LoggerRoot());
-		}
-		return self::$hierarchy;
-	}
+	// ******************************************
+	// *** Logging methods                    ***
+	// ******************************************
 	
-	/* Logging methods */
 	/**
 	 * Log a message object with the TRACE level.
 	 *
@@ -141,7 +116,6 @@ class Logger {
 		$this->log(LoggerLevel::getLevelDebug(), $message, $throwable);
 	} 
 
-
 	/**
 	 * Log a message object with the INFO Level.
 	 *
@@ -185,6 +159,33 @@ class Logger {
 	public function fatal($message, $throwable = null) {
 		$this->log(LoggerLevel::getLevelFatal(), $message, $throwable);
 	}
+
+	/**
+	 * Log a message using the provided logging level.
+	 *
+	 * @param LoggerLevel $level The logging level.
+	 * @param mixed $message Message to log.
+ 	 * @param Exception $throwable Optional throwable information to include 
+	 *   in the logging event.
+	 */
+	public function log(LoggerLevel $level, $message, $throwable = null) {
+		if($this->isEnabledFor($level)) {
+			$this->forcedLog($this->fqcn, $throwable, $level, $message);
+		}
+	}
+	
+	/**
+	 * If assertion parameter evaluates as false, then logs the message 
+	 * using the ERROR level.
+	 *
+	 * @param bool $assertion
+	 * @param string $msg message to log
+	 */
+	public function assertLog($assertion = true, $msg = '') {
+		if($assertion == false) {
+			$this->error($msg);
+		}
+	}
 	
 	/**
 	 * This method creates a new logging event and logs the event without 
@@ -201,29 +202,41 @@ class Logger {
 	 * @param mixed $message message to log
 	 */
 	public function forcedLog($fqcn, $throwable, LoggerLevel $level, $message) {
-		$throwable = ($throwable !== null && $throwable instanceof Exception) ? $throwable : null;
-		
+		if (!($throwable instanceof Exception)) {
+			$throwable = null;
+		}
 		$this->callAppenders(new LoggerLoggingEvent($fqcn, $this, $level, $message, null, $throwable));
 	} 
 	
+	// ******************************************
+	// *** Checker methods                    ***
+	// ******************************************
 	
 	/**
-	 * Check whether this Logger is enabled for the DEBUG Level.
-	 * @return boolean
-	 */
-	public function isDebugEnabled() {
-		return $this->isEnabledFor(LoggerLevel::getLevelDebug());
-	}		
-
-	/**
 	 * Check whether this Logger is enabled for a given Level passed as parameter.
 	 *
 	 * @param LoggerLevel level
 	 * @return boolean
 	 */
 	public function isEnabledFor(LoggerLevel $level) {
-		return (bool)($level->isGreaterOrEqual($this->getEffectiveLevel()));
-	} 
+		return $level->isGreaterOrEqual($this->getEffectiveLevel());
+	}
+	
+	/**
+	 * Check whether this Logger is enabled for the TRACE Level.
+	 * @return boolean
+	 */
+	public function isTraceEnabled() {
+		return $this->isEnabledFor(LoggerLevel::getLevelTrace());
+	}
+	
+	/**
+	 * Check whether this Logger is enabled for the DEBUG Level.
+	 * @return boolean
+	 */
+	public function isDebugEnabled() {
+		return $this->isEnabledFor(LoggerLevel::getLevelDebug());
+	}
 
 	/**
 	 * Check whether this Logger is enabled for the INFO Level.
@@ -231,67 +244,38 @@ class Logger {
 	 */
 	public function isInfoEnabled() {
 		return $this->isEnabledFor(LoggerLevel::getLevelInfo());
-	} 
-
-	/**
-	 * Log a message using the provided logging level.
-	 *
-	 * @param LoggerLevel $level The logging level.
-	 * @param mixed $message Message to log.
- 	 * @param Exception $throwable Optional throwable information to include 
-	 *   in the logging event.
-	 */
-	public function log(LoggerLevel $level, $message, $throwable = null) {
-		if($this->isEnabledFor($level)) {
-			$this->forcedLog($this->fqcn, $throwable, $level, $message);
-		}
 	}
 	
 	/**
-	 * If assertion parameter is false, then logs the message as an error.
-	 *
-	 * @param bool $assertion
-	 * @param string $msg message to log
+	 * Check whether this Logger is enabled for the WARN Level.
+	 * @return boolean
 	 */
-	public function assertLog($assertion = true, $msg = '') {
-		if($assertion == false) {
-			$this->error($msg);
-		}
+	public function isWarnEnabled() {
+		return $this->isEnabledFor(LoggerLevel::getLevelWarn());
 	}
 	
-	/* Factory methods */ 
-	
 	/**
-	 * Returns a Logger by name. 
-	 * 
-	 * If it does not exist, it will be created.
-	 * 
-	 * @param string $name logger name
-	 * @return Logger
+	 * Check whether this Logger is enabled for the ERROR Level.
+	 * @return boolean
 	 */
-	public static function getLogger($name) {
-		if(!self::isInitialized()) {
-			self::configure();
-		}
-		return self::getHierarchy()->getLogger($name);
+	public function isErrorEnabled() {
+		return $this->isEnabledFor(LoggerLevel::getLevelError());
 	}
 	
 	/**
-	 * Returns the Root Logger.
-	 * @return LoggerRoot
-	 */	   
-	public static function getRootLogger() {
-		if(!self::isInitialized()) {
-			self::configure();
-		}
-		return self::getHierarchy()->getRootLogger();	  
+	 * Check whether this Logger is enabled for the FATAL Level.
+	 * @return boolean
+	 */
+	public function isFatalEnabled() {
+		return $this->isEnabledFor(LoggerLevel::getLevelFatal());
 	}
 	
-	/* Configuration methods */
+	// ******************************************
+	// *** Configuration methods              ***
+	// ******************************************
 	
 	/**
-	 * Add a new appender to the Logger.
-	 *
+	 * Adds a new appender to the Logger.
 	 * @param LoggerAppender $appender The appender to add.
 	 */
 	public function addAppender($appender) {
@@ -299,9 +283,7 @@ class Logger {
 		$this->appenders[$appenderName] = $appender;
 	}
 	
-	/**
-	 * Remove all previously added appenders from the Logger.
-	 */
+	/** Removes all appenders from the Logger. */
 	public function removeAllAppenders() {
 		foreach($this->appenders as $name => $appender) {
 			$this->removeAppender($name);
@@ -310,8 +292,7 @@ class Logger {
 			
 	/**
 	 * Remove the appender passed as parameter form the Logger.
-	 *
-	 * @param string|LoggerAppender $appender an appender name or a {@link LoggerAppender} instance.
+	 * @param mixed $appender an appender name or a {@link LoggerAppender} instance.
 	 */
 	public function removeAppender($appender) {
 		if($appender instanceof LoggerAppender) {
@@ -321,42 +302,50 @@ class Logger {
 			$this->appenders[$appender]->close();
 			unset($this->appenders[$appender]);
 		}
-	} 
-			
+	}
+	
 	/**
-	 * Forwards the given logging event to all appenders associated with the 
-	 * Logger.
-	 *
+	 * Forwards the given logging event to all linked appenders.
 	 * @param LoggerLoggingEvent $event 
 	 */
 	public function callAppenders($event) {
+		// Forward the event to each linked appender
 		foreach($this->appenders as $appender) {
 			$appender->doAppend($event);
 		}
 		
-		if($this->parent != null and $this->getAdditivity()) {
+		// Forward the event upstream if additivity is turned on
+		if(isset($this->parent) && $this->getAdditivity()) {
 			$this->parent->callAppenders($event);
 		}
 	}
 	
 	/**
-	 * Get the appenders contained in this logger as an array.
+	 * Returns the appenders linked to this logger as an array.
 	 * @return array collection of appender names
 	 */
 	public function getAllAppenders() {
-		return array_values($this->appenders);
+		return $this->appenders;
 	}
 	
 	/**
-	 * Get an appender by name.
+	 * Returns a linked appender by name.
 	 * @return LoggerAppender
 	 */
 	public function getAppender($name) {
 		return $this->appenders[$name];
 	}
+
+	/**
+	 * Sets the additivity flag.
+	 * @param boolean $additive
+	 */
+	public function setAdditivity($additive) {
+		$this->additive = (bool)$additive;
+	}
 	
 	/**
-	 * Get the additivity flag.
+	 * Returns the additivity flag.
 	 * @return boolean
 	 */
 	public function getAdditivity() {
@@ -369,12 +358,11 @@ class Logger {
 	 * @return LoggerLevel or null
 	 */
 	public function getEffectiveLevel() {
-		for($c = $this; $c != null; $c = $c->parent) {
-			if($c->getLevel() !== null) {
-				return $c->getLevel();
+		for($logger = $this; $logger !== null; $logger = $logger->getParent()) {
+			if($logger->getLevel() !== null) {
+				return $logger->getLevel();
 			}
 		}
-		return null;
 	}
   
 	/**
@@ -395,11 +383,80 @@ class Logger {
 	}
 	
 	/**
+	 * Checks whether an appender is attached to this logger instance.
+	 *
+	 * @param LoggerAppender $appender
+	 * @return boolean
+	 */
+	public function isAttached(LoggerAppender $appender) {
+		return isset($this->appenders[$appender->getName()]);
+	} 
+		   
+
+	/**
+	 * Sets the parent logger.
+	 * @param Logger $logger
+	 */
+	public function setParent(Logger $logger) {
+		$this->parent = $logger;
+	} 
+	
+	// ******************************************
+	// *** Static methods and properties      ***
+	// ******************************************
+	
+	/** The logger hierarchy used by log4php. */
+	private static $hierarchy;
+	
+	/** Inidicates if log4php has been initialized */
+	private static $initialized = false;
+	
+	/**
+	 * Returns the hierarchy used by this Logger.
+	 *
+	 * Caution: do not use this hierarchy unless you have called initialize().
+	 * To get Loggers, use the Logger::getLogger and Logger::getRootLogger
+	 * methods instead of operating on on the hierarchy directly.
+	 *
+	 * @return LoggerHierarchy
+	 */
+	public static function getHierarchy() {
+		if(!isset(self::$hierarchy)) {
+			self::$hierarchy = new LoggerHierarchy(new LoggerRoot());
+		}
+		return self::$hierarchy;
+	}
+	
+	/**
+	 * Returns a Logger by name. If it does not exist, it will be created.
+	 *
+	 * @param string $name The logger name
+	 * @return Logger
+	 */
+	public static function getLogger($name) {
+		if(!self::isInitialized()) {
+			self::configure();
+		}
+		return self::getHierarchy()->getLogger($name);
+	}
+	
+	/**
+	 * Returns the Root Logger.
+	 * @return LoggerRoot
+	 */
+	public static function getRootLogger() {
+		if(!self::isInitialized()) {
+			self::configure();
+		}
+		return self::getHierarchy()->getRootLogger();
+	}
+	
+	/**
 	 * Clears all Logger definitions from the logger hierarchy.
-	 * @return boolean 
+	 * @return boolean
 	 */
 	public static function clear() {
-		return self::getHierarchy()->clear();	 
+		return self::getHierarchy()->clear();
 	}
 	
 	/**
@@ -410,20 +467,20 @@ class Logger {
 		self::getHierarchy()->clear(); // TODO: clear or not?
 		self::$initialized = false;
 	}
-
+	
 	/**
 	 * Safely close all appenders.
 	 * @deprecated This is no longer necessary due the appenders shutdown via
 	 * destructors.
 	 */
 	public static function shutdown() {
-		return self::getHierarchy()->shutdown();	   
+		return self::getHierarchy()->shutdown();
 	}
 	
 	/**
 	 * check if a given logger exists.
-	 * 
-	 * @param string $name logger name 
+	 *
+	 * @param string $name logger name
 	 * @return boolean
 	 */
 	public static function exists($name) {
@@ -440,32 +497,6 @@ class Logger {
 	}
 	
 	/**
-	 * Checks whether an appender is attached to this logger instance.
-	 *
-	 * @param LoggerAppender $appender
-	 * @return boolean
-	 */
-	public function isAttached(LoggerAppender $appender) {
-		return isset($this->appenders[$appender->getName()]);
-	} 
-		   
-	/**
-	 * Sets the additivity flag.
-	 * @param boolean $additive
-	 */
-	public function setAdditivity($additive) {
-		$this->additive = (bool)$additive;
-	}
-
-	/**
-	 * Sets the parent logger.
-	 * @param Logger $logger
-	 */
-	public function setParent(Logger $logger) {
-		$this->parent = $logger;
-	} 
-	
-	/**
 	 * Configures log4php.
 	 * 
 	 * This method needs to be called before the first logging event has