| <?xml version="1.0" encoding="iso-8859-1"?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <!-- template designed by Marco Von Ballmoos --> |
| <title>Docs For Class LoggerNDC</title> |
| <link rel="stylesheet" href="../media/stylesheet.css" /> |
| <script src="../media/lib/classTree.js"></script> |
| <script language="javascript" type="text/javascript"> |
| var imgPlus = new Image(); |
| var imgMinus = new Image(); |
| imgPlus.src = "../media/images/plus.png"; |
| imgMinus.src = "../media/images/minus.png"; |
| |
| function showNode(Node){ |
| switch(navigator.family){ |
| case 'nn4': |
| // Nav 4.x code fork... |
| var oTable = document.layers["span" + Node]; |
| var oImg = document.layers["img" + Node]; |
| break; |
| case 'ie4': |
| // IE 4/5 code fork... |
| var oTable = document.all["span" + Node]; |
| var oImg = document.all["img" + Node]; |
| break; |
| case 'gecko': |
| // Standards Compliant code fork... |
| var oTable = document.getElementById("span" + Node); |
| var oImg = document.getElementById("img" + Node); |
| break; |
| } |
| oImg.src = imgMinus.src; |
| oTable.style.display = "block"; |
| } |
| |
| function hideNode(Node){ |
| switch(navigator.family){ |
| case 'nn4': |
| // Nav 4.x code fork... |
| var oTable = document.layers["span" + Node]; |
| var oImg = document.layers["img" + Node]; |
| break; |
| case 'ie4': |
| // IE 4/5 code fork... |
| var oTable = document.all["span" + Node]; |
| var oImg = document.all["img" + Node]; |
| break; |
| case 'gecko': |
| // Standards Compliant code fork... |
| var oTable = document.getElementById("span" + Node); |
| var oImg = document.getElementById("img" + Node); |
| break; |
| } |
| oImg.src = imgPlus.src; |
| oTable.style.display = "none"; |
| } |
| |
| function nodeIsVisible(Node){ |
| switch(navigator.family){ |
| case 'nn4': |
| // Nav 4.x code fork... |
| var oTable = document.layers["span" + Node]; |
| break; |
| case 'ie4': |
| // IE 4/5 code fork... |
| var oTable = document.all["span" + Node]; |
| break; |
| case 'gecko': |
| // Standards Compliant code fork... |
| var oTable = document.getElementById("span" + Node); |
| break; |
| } |
| return (oTable && oTable.style.display == "block"); |
| } |
| |
| function toggleNodeVisibility(Node){ |
| if (nodeIsVisible(Node)){ |
| hideNode(Node); |
| }else{ |
| showNode(Node); |
| } |
| } |
| </script> |
| </head> |
| <body> |
| <div class="page-body"> |
| <h2 class="class-name">Class LoggerNDC</h2> |
| |
| <a name="sec-description"></a> |
| <div class="info-box"> |
| <div class="info-box-title">Description</div> |
| <div class="nav-bar"> |
| <span class="disabled">Description</span> | |
| <a href="#sec-var-summary">Vars</a> (<a href="#sec-vars">details</a>) |
| | <a href="#sec-method-summary">Methods</a> (<a href="#sec-methods">details</a>) |
| |
| </div> |
| <div class="info-box-body"> |
| <!-- ========== Info from phpDoc block ========= --> |
| <p class="short-description">The NDC class implements <em>nested diagnostic contexts</em>.</p> |
| <p class="description"><p>NDC was defined by Neil Harrison in the article "Patterns for Logging Diagnostic Messages" part of the book <em>"Pattern Languages of |
| Program Design 3"</em> edited by Martin et al.</p><p>A Nested Diagnostic Context, or NDC in short, is an instrument to distinguish interleaved log output from different sources. Log output is typically interleaved when a server handles multiple clients near-simultaneously.</p><p>This class is similar to the <a href="../log4php/LoggerMDC.html">LoggerMDC</a> class except that it is based on a stack instead of a map.</p><p>Interleaved log output can still be meaningful if each log entry from different contexts had a distinctive stamp. This is where NDCs come into play.</p><p><strong>Note that NDCs are managed on a per thread basis</strong>.</p><p>NDC operations such as <a href="../log4php/LoggerNDC.html#methodpush">push()</a>, <a href="../log4php/LoggerNDC.html#methodpop">pop()</a>, <a href="../log4php/LoggerNDC.html#methodclear">clear()</a>, <a href="../log4php/LoggerNDC.html#methodgetDepth">getDepth()</a> and <a href="../log4php/LoggerNDC.html#methodsetMaxDepth">setMaxDepth()</a> affect the NDC of the <em>current</em> thread only. NDCs of other threads remain unaffected.</p><p>For example, a servlet can build a per client request NDC consisting the clients host name and other information contained in the the request. <em>Cookies</em> are another source of distinctive information. To build an NDC one uses the <a href="../log4php/LoggerNDC.html#methodpush">push()</a> operation.</p><p>Simply put,</p><p><ul><li>Contexts can be nested.</li><li>When entering a context, call <kbd>LoggerNDC::push()</kbd> |
| As a side effect, if there is no nested diagnostic context for the |
| current thread, this method will create it.</li><li>When leaving a context, call <kbd>LoggerNDC::pop()</kbd></li><li><strong>When exiting a thread make sure to call <a href="../log4php/LoggerNDC.html#methodremove">remove()</a></strong></li></ul> There is no penalty for forgetting to match each <kbd>push</kbd> operation with a corresponding <kbd>pop</kbd>, except the obvious mismatch between the real application context and the context set in the NDC.</p><p>If configured to do so, LoggerPatternLayout and <a href="../log4php/layouts/LoggerLayoutTTCC.html">LoggerLayoutTTCC</a> instances automatically retrieve the nested diagnostic context for the current thread without any user intervention. Hence, even if a servlet is serving multiple clients simultaneously, the logs emanating from the same code (belonging to the same category) can still be distinguished because each client request will have a different NDC tag.</p><p>Example:</p><p><div class="src-code"><ol><li><div class="src-line"><span class="src-inc">require_once </span><span class="src-id">dirname</span><span class="src-sym">(</span>__FILE__<span class="src-sym">)</span>.<span class="src-str">'/../../main/php/Logger.php'</span><span class="src-sym">;</span></div></li> |
| <li><div class="src-line"><span class="src-id"><a href="../log4php/Logger.html">Logger</a></span><span class="src-sym">::</span><a href="../log4php/Logger.html#methodconfigure">configure</a><span class="src-sym">(</span><a href="http://www.php.net/dirname">dirname</a><span class="src-sym">(</span>__FILE__<span class="src-sym">)</span>.<span class="src-str">'/../resources/ndc.properties'</span><span class="src-sym">)</span><span class="src-sym">;</span></div></li> |
| <li><div class="src-line"><span class="src-var">$logger </span>= <span class="src-id"><a href="../log4php/Logger.html">Logger</a></span><span class="src-sym">::</span><a href="../log4php/Logger.html#methodgetRootLogger">getRootLogger</a><span class="src-sym">(</span><span class="src-sym">)</span><span class="src-sym">;</span></div></li> |
| <li><div class="src-line"> </div></li> |
| <li><div class="src-line"><span class="src-id"><a href="../log4php/LoggerNDC.html">LoggerNDC</a></span><span class="src-sym">::</span><a href="../log4php/LoggerNDC.html#methodpush">push</a><span class="src-sym">(</span><span class="src-str">'conn=1234'</span><span class="src-sym">)</span><span class="src-sym">;</span></div></li> |
| <li><div class="src-line"><span class="src-var">$logger</span><span class="src-sym">-></span><span class="src-id">debug</span><span class="src-sym">(</span><span class="src-str">"just received a new connection"</span><span class="src-sym">)</span><span class="src-sym">;</span></div></li> |
| <li><div class="src-line"><span class="src-id"><a href="../log4php/LoggerNDC.html">LoggerNDC</a></span><span class="src-sym">::</span><a href="../log4php/LoggerNDC.html#methodpush">push</a><span class="src-sym">(</span><span class="src-str">'client=ab23'</span><span class="src-sym">)</span><span class="src-sym">;</span></div></li> |
| <li><div class="src-line"><span class="src-var">$logger</span><span class="src-sym">-></span><span class="src-id">debug</span><span class="src-sym">(</span><span class="src-str">"some more messages that can"</span><span class="src-sym">)</span><span class="src-sym">;</span></div></li> |
| <li><div class="src-line"><span class="src-var">$logger</span><span class="src-sym">-></span><span class="src-id">debug</span><span class="src-sym">(</span><span class="src-str">"now related to a client"</span><span class="src-sym">)</span><span class="src-sym">;</span></div></li> |
| <li><div class="src-line"><span class="src-id"><a href="../log4php/LoggerNDC.html">LoggerNDC</a></span><span class="src-sym">::</span><a href="../log4php/LoggerNDC.html#methodpop">pop</a><span class="src-sym">(</span><span class="src-sym">)</span><span class="src-sym">;</span></div></li> |
| <li><div class="src-line"><span class="src-id"><a href="../log4php/LoggerNDC.html">LoggerNDC</a></span><span class="src-sym">::</span><a href="../log4php/LoggerNDC.html#methodpop">pop</a><span class="src-sym">(</span><span class="src-sym">)</span><span class="src-sym">;</span></div></li> |
| <li><div class="src-line"><span class="src-var">$logger</span><span class="src-sym">-></span><span class="src-id">debug</span><span class="src-sym">(</span><span class="src-str">"back and waiting for new connections"</span><span class="src-sym">)</span><span class="src-sym">;</span></div></li> |
| </ol></div><br /></p><p>With the properties file:</p><p><div class="src-code"><ol><li><div class="src-line">log4php.appender.default = LoggerAppenderEcho</div></li> |
| <li><div class="src-line">log4php.appender.default.layout = LoggerLayoutPattern</div></li> |
| <li><div class="src-line">log4php.appender.default.layout.conversionPattern="%d{Y-m-d H:i:s} %-5p %c %x: %m in %F at %L%n"</div></li> |
| <li><div class="src-line">log4php.rootLogger = DEBUG, default</div></li> |
| </ol></div><br /></p><p>Will result in the following (notice the conn and client ids):</p><p><pre> 2009-09-13 19:04:27 DEBUG root conn=1234: just received a new connection in src/examples/php/ndc.php at 23 |
| 2009-09-13 19:04:27 DEBUG root conn=1234 client=ab23: some more messages that can in src/examples/php/ndc.php at 25 |
| 2009-09-13 19:04:27 DEBUG root conn=1234 client=ab23: now related to a client in src/examples/php/ndc.php at 26 |
| 2009-09-13 19:04:27 DEBUG root : back and waiting for new connections in src/examples/php/ndc.php at 29</pre></p></p> |
| <ul class="tags"> |
| <li><span class="field">version:</span> $Revision: 1166187 $</li> |
| <li><span class="field">since:</span> 0.3</li> |
| </ul> |
| <p class="notes"> |
| Located in <a class="field" href="_LoggerNDC.php.html">/LoggerNDC.php</a> (line <span class="field">96</span>) |
| </p> |
| |
| |
| <pre></pre> |
| |
| </div> |
| </div> |
| |
| |
| |
| <a name="sec-var-summary"></a> |
| <div class="info-box"> |
| <div class="info-box-title">Variable Summary</span></div> |
| <div class="nav-bar"> |
| <a href="#sec-description">Description</a> | |
| <span class="disabled">Vars</span> (<a href="#sec-vars">details</a>) |
| | |
| <a href="#sec-method-summary">Methods</a> (<a href="#sec-methods">details</a>) |
| |
| </div> |
| <div class="info-box-body"> |
| <div class="var-summary"> |
| <div class="var-title"> |
| static <span class="var-type">mixed</span> |
| <a href="#$stack" title="details" class="var-name">$stack</a> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <a name="sec-method-summary"></a> |
| <div class="info-box"> |
| <div class="info-box-title">Method Summary</span></div> |
| <div class="nav-bar"> |
| <a href="#sec-description">Description</a> | |
| <a href="#sec-var-summary">Vars</a> (<a href="#sec-vars">details</a>) |
| |
| | |
| <span class="disabled">Methods</span> (<a href="#sec-methods">details</a>) |
| </div> |
| <div class="info-box-body"> |
| <div class="method-summary"> |
| |
| <div class="method-definition"> |
| static <span class="method-result">void</span> |
| <a href="#clear" title="details" class="method-name">clear</a> |
| () |
| </div> |
| |
| <div class="method-definition"> |
| static <span class="method-result">array</span> |
| <a href="#get" title="details" class="method-name">get</a> |
| () |
| </div> |
| |
| <div class="method-definition"> |
| static <span class="method-result">integer</span> |
| <a href="#getDepth" title="details" class="method-name">getDepth</a> |
| () |
| </div> |
| |
| <div class="method-definition"> |
| static <span class="method-result">string</span> |
| <a href="#peek" title="details" class="method-name">peek</a> |
| () |
| </div> |
| |
| <div class="method-definition"> |
| static <span class="method-result">string</span> |
| <a href="#pop" title="details" class="method-name">pop</a> |
| () |
| </div> |
| |
| <div class="method-definition"> |
| static <span class="method-result">void</span> |
| <a href="#push" title="details" class="method-name">push</a> |
| (<span class="var-type">string</span> <span class="var-name">$message</span>) |
| </div> |
| |
| <div class="method-definition"> |
| static <span class="method-result">void</span> |
| <a href="#remove" title="details" class="method-name">remove</a> |
| () |
| </div> |
| |
| <div class="method-definition"> |
| static <span class="method-result">void</span> |
| <a href="#setMaxDepth" title="details" class="method-name">setMaxDepth</a> |
| (<span class="var-type">integer</span> <span class="var-name">$maxDepth</span>) |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <a name="sec-vars"></a> |
| <div class="info-box"> |
| <div class="info-box-title">Variables</div> |
| <div class="nav-bar"> |
| <a href="#sec-description">Description</a> | |
| <a href="#sec-var-summary">Vars</a> (<span class="disabled">details</span>) |
| |
| |
| | |
| <a href="#sec-method-summary">Methods</a> (<a href="#sec-methods">details</a>) |
| |
| </div> |
| <div class="info-box-body"> |
| <a name="var$stack" id="$stack"><!-- --></A> |
| <div class="oddrow"> |
| |
| <div class="var-header"> |
| <span class="var-title"> |
| static <span class="var-type">mixed</span> |
| <span class="var-name">$stack</span> |
| = <span class="var-default">array()</span> (line <span class="line-number">99</span>) |
| </span> |
| </div> |
| |
| <!-- ========== Info from phpDoc block ========= --> |
| <p class="short-description">This is the repository of NDC stack</p> |
| <ul class="tags"> |
| <li><span class="field">access:</span> private</li> |
| </ul> |
| |
| |
| |
| |
| |
| </div> |
| |
| </div> |
| </div> |
| |
| <a name="sec-methods"></a> |
| <div class="info-box"> |
| <div class="info-box-title">Methods</div> |
| <div class="nav-bar"> |
| <a href="#sec-description">Description</a> | |
| <a href="#sec-var-summary">Vars</a> (<a href="#sec-vars">details</a>) |
| <a href="#sec-method-summary">Methods</a> (<span class="disabled">details</span>) |
| |
| </div> |
| <div class="info-box-body"> |
| <A NAME='method_detail'></A> |
| <a name="methodclear" id="clear"><!-- --></a> |
| <div class="evenrow"> |
| |
| <div class="method-header"> |
| <span class="method-title">static clear</span> (line <span class="line-number">109</span>) |
| </div> |
| |
| <!-- ========== Info from phpDoc block ========= --> |
| <p class="short-description">Clear any nested diagnostic information if any. This method is useful in cases where the same thread can be potentially used over and over in different unrelated contexts.</p> |
| <p class="description"><p>This method is equivalent to calling the <a href="../log4php/LoggerNDC.html#methodsetMaxDepth">setMaxDepth()</a> method with a zero <var>maxDepth</var> argument.</p></p> |
| <ul class="tags"> |
| <li><span class="field">access:</span> public</li> |
| </ul> |
| |
| <div class="method-signature"> |
| static <span class="method-result">void</span> |
| <span class="method-name"> |
| clear |
| </span> |
| () |
| </div> |
| |
| |
| |
| </div> |
| <a name="methodget" id="get"><!-- --></a> |
| <div class="oddrow"> |
| |
| <div class="method-header"> |
| <span class="method-title">static get</span> (line <span class="line-number">117</span>) |
| </div> |
| |
| <!-- ========== Info from phpDoc block ========= --> |
| <p class="short-description">Never use this method directly, use the <a href="../log4php/LoggerLoggingEvent.html#methodgetNDC">LoggerLoggingEvent::getNDC()</a> method instead.</p> |
| <ul class="tags"> |
| <li><span class="field">access:</span> public</li> |
| </ul> |
| |
| <div class="method-signature"> |
| static <span class="method-result">array</span> |
| <span class="method-name"> |
| get |
| </span> |
| () |
| </div> |
| |
| |
| |
| </div> |
| <a name="methodgetDepth" id="getDepth"><!-- --></a> |
| <div class="evenrow"> |
| |
| <div class="method-header"> |
| <span class="method-title">static getDepth</span> (line <span class="line-number">127</span>) |
| </div> |
| |
| <!-- ========== Info from phpDoc block ========= --> |
| <p class="short-description">Get the current nesting depth of this diagnostic context.</p> |
| <ul class="tags"> |
| <li><span class="field">see:</span> <a href="../log4php/LoggerNDC.html#methodsetMaxDepth">LoggerNDC::setMaxDepth()</a></li> |
| <li><span class="field">access:</span> public</li> |
| </ul> |
| |
| <div class="method-signature"> |
| static <span class="method-result">integer</span> |
| <span class="method-name"> |
| getDepth |
| </span> |
| () |
| </div> |
| |
| |
| |
| </div> |
| <a name="methodpeek" id="peek"><!-- --></a> |
| <div class="oddrow"> |
| |
| <div class="method-header"> |
| <span class="method-title">static peek</span> (line <span class="line-number">156</span>) |
| </div> |
| |
| <!-- ========== Info from phpDoc block ========= --> |
| <p class="short-description">Looks at the last diagnostic context at the top of this NDC without removing it.</p> |
| <p class="description"><p>The returned value is the value that was pushed last. If no context is available, then the empty string "" is returned.</p></p> |
| <ul class="tags"> |
| <li><span class="field">return:</span> The innermost diagnostic context.</li> |
| <li><span class="field">access:</span> public</li> |
| </ul> |
| |
| <div class="method-signature"> |
| static <span class="method-result">string</span> |
| <span class="method-name"> |
| peek |
| </span> |
| () |
| </div> |
| |
| |
| |
| </div> |
| <a name="methodpop" id="pop"><!-- --></a> |
| <div class="evenrow"> |
| |
| <div class="method-header"> |
| <span class="method-title">static pop</span> (line <span class="line-number">140</span>) |
| </div> |
| |
| <!-- ========== Info from phpDoc block ========= --> |
| <p class="short-description">Clients should call this method before leaving a diagnostic context.</p> |
| <p class="description"><p>The returned value is the value that was pushed last. If no context is available, then the empty string "" is returned.</p><p></p></p> |
| <ul class="tags"> |
| <li><span class="field">return:</span> The innermost diagnostic context.</li> |
| <li><span class="field">access:</span> public</li> |
| </ul> |
| |
| <div class="method-signature"> |
| static <span class="method-result">string</span> |
| <span class="method-name"> |
| pop |
| </span> |
| () |
| </div> |
| |
| |
| |
| </div> |
| <a name="methodpush" id="push"><!-- --></a> |
| <div class="oddrow"> |
| |
| <div class="method-header"> |
| <span class="method-title">static push</span> (line <span class="line-number">172</span>) |
| </div> |
| |
| <!-- ========== Info from phpDoc block ========= --> |
| <p class="short-description">Push new diagnostic context information for the current thread.</p> |
| <p class="description"><p>The contents of the <var>message</var> parameter is determined solely by the client.</p></p> |
| <ul class="tags"> |
| <li><span class="field">access:</span> public</li> |
| </ul> |
| |
| <div class="method-signature"> |
| static <span class="method-result">void</span> |
| <span class="method-name"> |
| push |
| </span> |
| (<span class="var-type">string</span> <span class="var-name">$message</span>) |
| </div> |
| |
| <ul class="parameters"> |
| <li> |
| <span class="var-type">string</span> |
| <span class="var-name">$message</span><span class="var-description">: The new diagnostic context information.</span> </li> |
| </ul> |
| |
| |
| </div> |
| <a name="methodremove" id="remove"><!-- --></a> |
| <div class="evenrow"> |
| |
| <div class="method-header"> |
| <span class="method-title">static remove</span> (line <span class="line-number">179</span>) |
| </div> |
| |
| <!-- ========== Info from phpDoc block ========= --> |
| <p class="short-description">Remove the diagnostic context for this thread.</p> |
| <ul class="tags"> |
| <li><span class="field">access:</span> public</li> |
| </ul> |
| |
| <div class="method-signature"> |
| static <span class="method-result">void</span> |
| <span class="method-name"> |
| remove |
| </span> |
| () |
| </div> |
| |
| |
| |
| </div> |
| <a name="methodsetMaxDepth" id="setMaxDepth"><!-- --></a> |
| <div class="oddrow"> |
| |
| <div class="method-header"> |
| <span class="method-title">static setMaxDepth</span> (line <span class="line-number">197</span>) |
| </div> |
| |
| <!-- ========== Info from phpDoc block ========= --> |
| <p class="short-description">Set maximum depth of this diagnostic context. If the current depth is smaller or equal to <var>maxDepth</var>, then no action is taken.</p> |
| <p class="description"><p>This method is a convenient alternative to multiple <a href="../log4php/LoggerNDC.html#methodpop">pop()</a> calls. Moreover, it is often the case that at the end of complex call sequences, the depth of the NDC is unpredictable. The <a href="../log4php/LoggerNDC.html#methodsetMaxDepth">setMaxDepth()</a> method circumvents this problem.</p></p> |
| <ul class="tags"> |
| <li><span class="field">see:</span> <a href="../log4php/LoggerNDC.html#methodgetDepth">LoggerNDC::getDepth()</a></li> |
| <li><span class="field">access:</span> public</li> |
| </ul> |
| |
| <div class="method-signature"> |
| static <span class="method-result">void</span> |
| <span class="method-name"> |
| setMaxDepth |
| </span> |
| (<span class="var-type">integer</span> <span class="var-name">$maxDepth</span>) |
| </div> |
| |
| <ul class="parameters"> |
| <li> |
| <span class="var-type">integer</span> |
| <span class="var-name">$maxDepth</span> </li> |
| </ul> |
| |
| |
| </div> |
| |
| </div> |
| </div> |
| |
| |
| <p class="notes" id="credit"> |
| Documentation generated on Sat, 18 Feb 2012 22:32:26 +0000 by <a href="http://www.phpdoc.org" target="_blank">phpDocumentor 1.4.3</a> |
| </p> |
| </div></body> |
| </html> |
