Reorganised the Logger class:
authorIvan Habunek <ihabunek@apache.org>
Thu, 12 Jan 2012 13:33:03 +0000 (13:33 +0000)
committerIvan Habunek <ihabunek@apache.org>
Thu, 12 Jan 2012 13:33:03 +0000 (13:33 +0000)
- improved phpdoc
- grouped static methods and properties together
- added missing isXxxxEnabled() methods
- no significant functionality changes

git-svn-id: https://svn.apache.org/repos/asf/logging/log4php/trunk@1230522 13f79535-47bb-0310-9956-ffa450edef68

src/main/php/Logger.php

index 0ec9057..0533fb4 100644 (file)
@@ -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