[Sommaire] [Imprimer]

   1  <?php
   2  /**
   3   * log4php is a PHP port of the log4j java logging package.
   4   * 
   5   * <p>This framework is based on log4j (see {@link http://jakarta.apache.org/log4j log4j} for details).</p>
   6   * <p>Design, strategies and part of the methods documentation are developed by log4j team 
   7   * (Ceki Gülcü as log4j project founder and 
   8   * {@link http://jakarta.apache.org/log4j/docs/contributors.html contributors}).</p>
   9   *
  10   * <p>PHP port, extensions and modifications by VxR. All rights reserved.<br>
  11   * For more information, please see {@link http://www.vxr.it/log4php/}.</p>
  12   *
  13   * <p>This software is published under the terms of the LGPL License
  14   * a copy of which has been included with this distribution in the LICENSE file.</p>
  15   * 
  16   * @package log4php
  17   */
  18  
  19  /**
  20   * @ignore 
  21   */
  22  if (!defined('LOG4PHP_DIR')) define('LOG4PHP_DIR', dirname(__FILE__)); 
  23   
  24  /**
  25   */
  26  require_once (LOG4PHP_DIR . '/LoggerLog.php');
  27  
  28  define('LOGGER_NDC_HT_SIZE', 7);
  29  
  30  /**
  31   * This is the global repository of NDC stack
  32   */
  33  $GLOBALS['log4php.LoggerNDC.ht'] = array();
  34  
  35  /**
  36   * This is the max depth of NDC stack
  37   */
  38  $GLOBALS['log4php.LoggerNDC.maxDepth'] = LOGGER_NDC_HT_SIZE;
  39  
  40  
  41  /**
  42   * The NDC class implements <i>nested diagnostic contexts</i> as
  43   * defined by Neil Harrison in the article "Patterns for Logging
  44   * Diagnostic Messages" part of the book "<i>Pattern Languages of
  45   * Program Design 3</i>" edited by Martin et al.
  46   *
  47   * <p>A Nested Diagnostic Context, or NDC in short, is an instrument
  48   * to distinguish interleaved log output from different sources. Log
  49   * output is typically interleaved when a server handles multiple
  50   * clients near-simultaneously.
  51   *
  52   * <p>Interleaved log output can still be meaningful if each log entry
  53   * from different contexts had a distinctive stamp. This is where NDCs
  54   * come into play.
  55   *
  56   * <p><i><b>Note that NDCs are managed on a per thread
  57   * basis</b></i>. NDC operations such as {@link push()}, {@link pop()}, 
  58   * {@link clear()}, {@link getDepth()} and {@link setMaxDepth()}
  59   * affect the NDC of the <i>current</i> thread only. NDCs of other
  60   * threads remain unaffected.
  61   *
  62   * <p>For example, a servlet can build a per client request NDC
  63   * consisting the clients host name and other information contained in
  64   * the the request. <i>Cookies</i> are another source of distinctive
  65   * information. To build an NDC one uses the {@link push()}
  66   * operation.</p>
  67   * 
  68   * Simply put,
  69   *
  70   * - Contexts can be nested.
  71   * - When entering a context, call 
  72   *   <code>LoggerNDC::push()</code>
  73   *   As a side effect, if there is no nested diagnostic context for the
  74   *   current thread, this method will create it.
  75   * - When leaving a context, call 
  76   *   <code>LoggerNDC::pop()</code>
  77   * - <b>When exiting a thread make sure to call {@link remove()}</b>
  78   *   
  79   * <p>There is no penalty for forgetting to match each
  80   * <code>push</code> operation with a corresponding <code>pop</code>,
  81   * except the obvious mismatch between the real application context
  82   * and the context set in the NDC.</p>
  83   *
  84   * <p>If configured to do so, {@link LoggerPatternLayout} and {@link LoggerLayoutTTCC} 
  85   * instances automatically retrieve the nested diagnostic
  86   * context for the current thread without any user intervention.
  87   * Hence, even if a servlet is serving multiple clients
  88   * simultaneously, the logs emanating from the same code (belonging to
  89   * the same category) can still be distinguished because each client
  90   * request will have a different NDC tag.</p>
  91   *
  92   *  
  93   * @author VxR <vxr@vxr.it>
  94   * @version $Revision: 1.5 $
  95   * @package log4php 
  96   * @since 0.3
  97   */
  98  class LoggerNDC {
  99  
 100      /**
 101       * Clear any nested diagnostic information if any. This method is
 102       * useful in cases where the same thread can be potentially used
 103       * over and over in different unrelated contexts.
 104       *
 105       * <p>This method is equivalent to calling the {@link setMaxDepth()}
 106       * method with a zero <var>maxDepth</var> argument.
 107       *
 108       * @static  
 109       */
 110      function clear()
 111      {
 112          LoggerLog::debug("LoggerNDC::clear()");
 113          
 114          $GLOBALS['log4php.LoggerNDC.ht'] = array();
 115      }
 116  
 117      /**
 118       * Never use this method directly, use the {@link LoggerLoggingEvent::getNDC()} method instead.
 119       * @static
 120       * @return array
 121       */
 122      function get()
 123      {
 124          LoggerLog::debug("LoggerNDC::get()");
 125      
 126          return $GLOBALS['log4php.LoggerNDC.ht'];
 127      }
 128    
 129      /**
 130       * Get the current nesting depth of this diagnostic context.
 131       *
 132       * @see setMaxDepth()
 133       * @return integer
 134       * @static
 135       */
 136      function getDepth()
 137      {
 138          LoggerLog::debug("LoggerNDC::getDepth()");
 139      
 140          return sizeof($GLOBALS['log4php.LoggerNDC.ht']);      
 141      }
 142  
 143      /**
 144       * Clients should call this method before leaving a diagnostic
 145       * context.
 146       *
 147       * <p>The returned value is the value that was pushed last. If no
 148       * context is available, then the empty string "" is returned.</p>
 149       *
 150       * @return string The innermost diagnostic context.
 151       * @static
 152       */
 153      function pop()
 154      {
 155          LoggerLog::debug("LoggerNDC::pop()");
 156      
 157          if (sizeof($GLOBALS['log4php.LoggerNDC.ht']) > 0) {
 158              return array_pop($GLOBALS['log4php.LoggerNDC.ht']);
 159          } else {
 160              return '';
 161          }
 162      }
 163  
 164      /**
 165       * Looks at the last diagnostic context at the top of this NDC
 166       * without removing it.
 167       *
 168       * <p>The returned value is the value that was pushed last. If no
 169       * context is available, then the empty string "" is returned.</p>
 170       * @return string The innermost diagnostic context.
 171       * @static
 172       */
 173      function peek()
 174      {
 175          LoggerLog::debug("LoggerNDC::peek()");
 176      
 177          if (sizeof($GLOBALS['log4php.LoggerNDC.ht']) > 0) {
 178              return end($GLOBALS['log4php.LoggerNDC.ht']);
 179          } else {
 180              return '';
 181          }
 182      }
 183    
 184      /**
 185       * Push new diagnostic context information for the current thread.
 186       *
 187       * <p>The contents of the <var>message</var> parameter is
 188       * determined solely by the client.
 189       *  
 190       * @param string $message The new diagnostic context information.
 191       * @static  
 192       */
 193      function push($message)
 194      {
 195          LoggerLog::debug("LoggerNDC::push()");
 196      
 197          array_push($GLOBALS['log4php.LoggerNDC.ht'], (string)$message);
 198      }
 199  
 200      /**
 201       * Remove the diagnostic context for this thread.
 202       * @static
 203       */
 204      function remove()
 205      {
 206          LoggerLog::debug("LoggerNDC::remove()");
 207      
 208          LoggerNDC::clear();
 209      }
 210  
 211      /**
 212       * Set maximum depth of this diagnostic context. If the current
 213       * depth is smaller or equal to <var>maxDepth</var>, then no
 214       * action is taken.
 215       *
 216       * <p>This method is a convenient alternative to multiple 
 217       * {@link pop()} calls. Moreover, it is often the case that at 
 218       * the end of complex call sequences, the depth of the NDC is
 219       * unpredictable. The {@link setMaxDepth()} method circumvents
 220       * this problem.
 221       *
 222       * @param integer $maxDepth
 223       * @see getDepth()
 224       * @static
 225       */
 226      function setMaxDepth($maxDepth)
 227      {
 228          LoggerLog::debug("LoggerNDC::setMaxDepth() maxDepth='$maxDepth'");
 229      
 230          $maxDepth = (int)$maxDepth;
 231          if ($maxDepth <= LOGGER_NDC_HT_SIZE) {
 232              if (LoggerNDC::getDepth() > $maxDepth) {
 233                  $GLOBALS['log4php.LoggerNDC.ht'] = array_slice($GLOBALS['log4php.LoggerNDC.ht'], $maxDepth);
 234              }
 235              $GLOBALS['log4php.LoggerNDC.maxDepth'] = $maxDepth;            
 236          }
 237      }
 238    
 239  }
 240  ?>