library/log4php/LoggerNDC.php
author Markus Broeker<broeker.markus@googlemail.com>
Sun, 14 Feb 2016 16:49:42 +0100
changeset 41 08414729c5b4
parent 0 4869aea77e21
permissions -rw-r--r--
Formulare umgestylt
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
0
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
     1
<?php
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
     2
/**
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
     3
 * Licensed to the Apache Software Foundation (ASF) under one or more
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
     4
 * contributor license agreements. See the NOTICE file distributed with
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
     5
 * this work for additional information regarding copyright ownership.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
     6
 * The ASF licenses this file to You under the Apache License, Version 2.0
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
     7
 * (the "License"); you may not use this file except in compliance with
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
     8
 * the License. You may obtain a copy of the License at
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
     9
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    10
 *       http://www.apache.org/licenses/LICENSE-2.0
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    11
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    12
 * Unless required by applicable law or agreed to in writing, software
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    13
 * distributed under the License is distributed on an "AS IS" BASIS,
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    14
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    15
 * See the License for the specific language governing permissions and
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    16
 * limitations under the License.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    17
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    18
 * @package log4php
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    19
 */
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    20
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    21
/**
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    22
 * The NDC class implements <i>nested diagnostic contexts</i>.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    23
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    24
 * NDC was defined by Neil Harrison in the article "Patterns for Logging
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    25
 * Diagnostic Messages" part of the book <i>"Pattern Languages of
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    26
 * Program Design 3"</i> edited by Martin et al.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    27
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    28
 * A Nested Diagnostic Context, or NDC in short, is an instrument
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    29
 * to distinguish interleaved log output from different sources. Log
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    30
 * output is typically interleaved when a server handles multiple
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    31
 * clients near-simultaneously.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    32
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    33
 * This class is similar to the {@link LoggerMDC} class except that it is
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    34
 * based on a stack instead of a map.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    35
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    36
 * Interleaved log output can still be meaningful if each log entry
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    37
 * from different contexts had a distinctive stamp. This is where NDCs
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    38
 * come into play.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    39
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    40
 * <b>Note that NDCs are managed on a per thread basis</b>.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    41
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    42
 * NDC operations such as {@link push()}, {@link pop()},
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    43
 * {@link clear()}, {@link getDepth()} and {@link setMaxDepth()}
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    44
 * affect the NDC of the <i>current</i> thread only. NDCs of other
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    45
 * threads remain unaffected.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    46
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    47
 * For example, a servlet can build a per client request NDC
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    48
 * consisting the clients host name and other information contained in
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    49
 * the the request. <i>Cookies</i> are another source of distinctive
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    50
 * information. To build an NDC one uses the {@link push()}
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    51
 * operation.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    52
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    53
 * Simply put,
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    54
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    55
 * - Contexts can be nested.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    56
 * - When entering a context, call <kbd>LoggerNDC::push()</kbd>
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    57
 *     As a side effect, if there is no nested diagnostic context for the
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    58
 *     current thread, this method will create it.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    59
 * - When leaving a context, call <kbd>LoggerNDC::pop()</kbd>
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    60
 * - <b>When exiting a thread make sure to call {@link remove()}</b>
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    61
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    62
 * There is no penalty for forgetting to match each
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    63
 * <kbd>push</kbd> operation with a corresponding <kbd>pop</kbd>,
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    64
 * except the obvious mismatch between the real application context
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    65
 * and the context set in the NDC.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    66
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    67
 * If configured to do so, {@link LoggerPatternLayout} and {@link LoggerLayoutTTCC}
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    68
 * instances automatically retrieve the nested diagnostic
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    69
 * context for the current thread without any user intervention.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    70
 * Hence, even if a servlet is serving multiple clients
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    71
 * simultaneously, the logs emanating from the same code (belonging to
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    72
 * the same category) can still be distinguished because each client
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    73
 * request will have a different NDC tag.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    74
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    75
 * Example:
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    76
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    77
 * {@example ../../examples/php/ndc.php 19}<br>
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    78
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    79
 * With the properties file:
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    80
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    81
 * {@example ../../examples/resources/ndc.properties 18}<br>
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    82
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    83
 * Will result in the following (notice the conn and client ids):
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    84
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    85
 * <pre>
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    86
 * 2009-09-13 19:04:27 DEBUG root conn=1234: just received a new connection in src/examples/php/ndc.php at 23
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    87
 * 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
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    88
 * 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
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    89
 * 2009-09-13 19:04:27 DEBUG root : back and waiting for new connections in src/examples/php/ndc.php at 29
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    90
 * </pre>
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    91
 *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    92
 * @version $Revision: 1350602 $
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    93
 * @package log4php
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    94
 * @since 0.3
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    95
 */
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    96
class LoggerNDC {
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    97
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    98
    /** This is the repository of NDC stack */
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
    99
    private static $stack = array();
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   100
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   101
    /**
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   102
     * Clear any nested diagnostic information if any. This method is
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   103
     * useful in cases where the same thread can be potentially used
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   104
     * over and over in different unrelated contexts.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   105
     *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   106
     * <p>This method is equivalent to calling the {@link setMaxDepth()}
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   107
     * method with a zero <var>maxDepth</var> argument.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   108
     */
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   109
    public static function clear() {
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   110
        self::$stack = array();
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   111
    }
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   112
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   113
    /**
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   114
     * Never use this method directly, use the {@link LoggerLoggingEvent::getNDC()} method instead.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   115
     * @return array
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   116
     */
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   117
    public static function get() {
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   118
        return implode(' ', self::$stack);
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   119
    }
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   120
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   121
    /**
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   122
     * Get the current nesting depth of this diagnostic context.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   123
     *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   124
     * @see setMaxDepth()
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   125
     * @return integer
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   126
     */
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   127
    public static function getDepth() {
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   128
        return count(self::$stack);
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   129
    }
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   130
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   131
    /**
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   132
     * Clients should call this method before leaving a diagnostic
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   133
     * context.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   134
     *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   135
     * <p>The returned value is the value that was pushed last. If no
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   136
     * context is available, then the empty string "" is returned.</p>
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   137
     *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   138
     * @return string The innermost diagnostic context.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   139
     */
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   140
    public static function pop() {
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   141
        if (count(self::$stack) > 0) {
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   142
            return array_pop(self::$stack);
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   143
        } else {
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   144
            return '';
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   145
        }
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   146
    }
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   147
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   148
    /**
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   149
     * Looks at the last diagnostic context at the top of this NDC
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   150
     * without removing it.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   151
     *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   152
     * <p>The returned value is the value that was pushed last. If no
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   153
     * context is available, then the empty string "" is returned.</p>
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   154
     * @return string The innermost diagnostic context.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   155
     */
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   156
    public static function peek() {
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   157
        if (count(self::$stack) > 0) {
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   158
            return end(self::$stack);
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   159
        } else {
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   160
            return '';
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   161
        }
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   162
    }
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   163
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   164
    /**
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   165
     * Push new diagnostic context information for the current thread.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   166
     *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   167
     * <p>The contents of the <var>message</var> parameter is
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   168
     * determined solely by the client.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   169
     *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   170
     * @param string $message The new diagnostic context information.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   171
     */
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   172
    public static function push($message) {
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   173
        array_push(self::$stack, (string)$message);
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   174
    }
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   175
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   176
    /**
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   177
     * Remove the diagnostic context for this thread.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   178
     */
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   179
    public static function remove() {
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   180
        LoggerNDC::clear();
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   181
    }
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   182
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   183
    /**
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   184
     * Set maximum depth of this diagnostic context. If the current
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   185
     * depth is smaller or equal to <var>maxDepth</var>, then no
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   186
     * action is taken.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   187
     *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   188
     * <p>This method is a convenient alternative to multiple
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   189
     * {@link pop()} calls. Moreover, it is often the case that at
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   190
     * the end of complex call sequences, the depth of the NDC is
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   191
     * unpredictable. The {@link setMaxDepth()} method circumvents
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   192
     * this problem.
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   193
     *
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   194
     * @param integer $maxDepth
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   195
     * @see getDepth()
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   196
     */
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   197
    public static function setMaxDepth($maxDepth) {
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   198
        $maxDepth = (int)$maxDepth;
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   199
        if (LoggerNDC::getDepth() > $maxDepth) {
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   200
            self::$stack = array_slice(self::$stack, 0, $maxDepth);
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   201
        }
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   202
    }
4869aea77e21 Bröker-Framework BFW-1
Markus Bröker <broeker.markus@googlemail.com>
parents:
diff changeset
   203
}