Siobhan Tully | e18b344 | 2014-02-23 14:23:34 -0500 | [diff] [blame] | 1 | <?xml version="1.0"?>
|
| 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
| 3 | <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
|
| 4 | <head>
|
| 5 | <title>log4javascript 1.4 manual</title>
|
| 6 | <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
|
| 7 | <meta name="author" content="Tim Down - tim@log4javascript.org" />
|
| 8 | <meta name="description" content="log4javascript, a logging framework for JavaScript based on log4j" />
|
| 9 | <meta name="robots" content="all" />
|
| 10 | <link rel="stylesheet" type="text/css" media="screen,print" href="../main.css" title="Default" />
|
| 11 | </head>
|
| 12 | <body>
|
| 13 | <div id="container" class="nonav">
|
| 14 | <div id="header">
|
| 15 | <h1><a href="index.html">log4javascript</a></h1>
|
| 16 | </div>
|
| 17 | <div id="content">
|
| 18 | <div id="nav">
|
| 19 | <a class="navitem" href="../index.html">home</a>
|
| 20 | | <a class="navitem" href="http://sourceforge.net/projects/log4javascript" target="_blank" title="Download (opens in new window)">download</a>
|
| 21 | | <a class="navitem" href="index.html">docs</a>
|
| 22 | | <a class="navitem" href="quickstart.html">quick start</a>
|
| 23 | | <a class="navitem" href="../demos/index.html">demos</a>
|
| 24 | | <a class="navitem" href="http://log4javascript.org" target="_blank">website</a>
|
| 25 | | <a class="navitem" href="http://www.timdown.co.uk" target="_blank">timdown.co.uk</a>
|
| 26 | </div>
|
| 27 | <h1>log4javascript 1.4 manual</h1>
|
| 28 | <h2>Contents</h2>
|
| 29 | <ul>
|
| 30 | <li><a href="#intro">Introduction</a></li>
|
| 31 | <li><a href="#noteaboutlog4javascript">Note about the log4javascript object</a></li>
|
| 32 | <li>
|
| 33 | <a href="#loggersappenderslayoutslevels">Loggers, appenders, layouts and levels</a>
|
| 34 | <ul>
|
| 35 | <li><a href="#configuration">Configuring appenders</a></li>
|
| 36 | <li><a href="#loggersappenderslayoutslevelsexample">Example</a></li>
|
| 37 | </ul>
|
| 38 | </li>
|
| 39 | <li><a href="#log4javascript">log4javascript static properties/methods</a></li>
|
| 40 | <li><a href="#levels">Levels</a></li>
|
| 41 | <li><a href="#loggers">Loggers</a></li>
|
| 42 | <li>
|
| 43 | <a href="#appenders">Appenders</a>
|
| 44 | <ul>
|
| 45 | <li><a href="#appender">Appender</a></li>
|
| 46 | <li><a href="#alertappender">AlertAppender</a></li>
|
| 47 | <li><a href="#ajaxappender">AjaxAppender</a></li>
|
| 48 | <li><a href="#popupappender">PopUpAppender</a></li>
|
| 49 | <li><a href="#inpageappender">InPageAppender</a></li>
|
| 50 | <li><a href="#browserconsoleappender">BrowserConsoleAppender</a></li>
|
| 51 | </ul>
|
| 52 | </li>
|
| 53 | <li>
|
| 54 | <a href="#layouts">Layouts</a>
|
| 55 | <ul>
|
| 56 | <li><a href="#layout">Layout</a></li>
|
| 57 | <li><a href="#nulllayout">NullLayout</a></li>
|
| 58 | <li><a href="#simplelayout">SimpleLayout</a></li>
|
| 59 | <li><a href="#patternlayout">PatternLayout</a></li>
|
| 60 | <li><a href="#xmllayout">XmlLayout</a></li>
|
| 61 | <li><a href="#jsonlayout">JsonLayout</a></li>
|
| 62 | <li><a href="#httppostdatalayout">HttpPostDataLayout</a></li>
|
| 63 | </ul>
|
| 64 | </li>
|
| 65 | <li><a href="#enabling">Enabling / disabling log4javascript</a></li>
|
| 66 | <li>
|
| 67 | <a href="#errorhandling">log4javascript error handling</a>
|
| 68 | <ul>
|
| 69 | <li><a href="#loglog">LogLog</a></li>
|
| 70 | </ul>
|
| 71 | </li>
|
| 72 | <li><a href="#differences">Differences between log4javascript and log4j</a></li>
|
| 73 | </ul>
|
| 74 | <div id="intro">
|
| 75 | <h2>Introduction</h2>
|
| 76 | <p>
|
| 77 | Anyone who has done a reasonable amount of JavaScript development will be
|
| 78 | familiar with <code>alert</code> as a means of debugging. For
|
| 79 | a small script, it works fine. But for anything of greater complexity than,
|
| 80 | say, a rollover script its shortcomings become apparent. The most obvious problem
|
| 81 | is the endless clicking of 'OK'. Another problem is that for a page
|
| 82 | heavily reliant on events generated from user actions, alerts
|
| 83 | can actually alter the way the page behaves. One final problem is infinite loops:
|
| 84 | without alerts, the browser will notice that the script has messed
|
| 85 | up and will offer the user the chance to stop the script running. With an
|
| 86 | alert inside an infinite loop, you're forced to kill the browser.
|
| 87 | </p>
|
| 88 | <p>
|
| 89 | At the other end of the scale there is
|
| 90 | <a href="http://www.mozilla.org/projects/venkman/" target="_blank">Venkman</a>,
|
| 91 | a full-on JavaScript debugger for Mozilla-based browsers such as Firefox. Here
|
| 92 | I have to confess that I simply have not put in the time to learn how to make
|
| 93 | it work well for me and I suspect I am not alone.
|
| 94 | </p>
|
| 95 | <p>
|
| 96 | Nowadays, easily the best option for day-to-day JavaScript development is the brilliant
|
| 97 | <a href="http://www.getfirebug.com" title="Firebug home page (opens in new window)"
|
| 98 | target="_blank">Firebug</a>, a Firefox plugin with built-in debugger, console, logging,
|
| 99 | and profiler. It's a seriously impressive tool but by its very nature as a Firefox
|
| 100 | plugin can only be used in one of the typical target browsers for mainstream web
|
| 101 | development.
|
| 102 | </p>
|
| 103 | <p>
|
| 104 | log4javascript was originally written as a cross-browser tool to ease the pain of JavaScript
|
| 105 | debugging without the time investment required to use a debugger effectively. It requires
|
| 106 | only a JavaScript include and one line of code to initialize with default settings.
|
| 107 | Having for several years used log4j and its .NET port log4net, it was natural for me to
|
| 108 | base it on log4j.
|
| 109 | </p>
|
| 110 | <p>
|
| 111 | log4javascript is by no means the only JavaScript logging framework out there.
|
| 112 | It is not even the only JavaScript implementation of log4j. It turns out the name
|
| 113 | log4javascript is used by another JavaScript logging framework, and that the name log4js is
|
| 114 | used by at least two other pieces of software; this version of log4javascript is unrelated
|
| 115 | to any of those.
|
| 116 | </p>
|
| 117 | <p class="linktotop">
|
| 118 | <a href="#container">Top</a>
|
| 119 | </p>
|
| 120 | </div>
|
| 121 | <div id="noteaboutlog4javascript">
|
| 122 | <h2>Note about the log4javascript object</h2>
|
| 123 | <p>
|
| 124 | All of log4javascript's instantiable classes are accessible via the log4javascript object, which
|
| 125 | acts as a namespace. Therefore references to all class names must be preceded with "log4javascript.".
|
| 126 | For example:
|
| 127 | </p>
|
| 128 | <p>
|
| 129 | <code>var popUpAppender = new log4javascript.PopUpAppender();</code>
|
| 130 | </p>
|
| 131 | <p class="linktotop">
|
| 132 | <a href="#container">Top</a>
|
| 133 | </p>
|
| 134 | </div>
|
| 135 | <div id="loggersappenderslayoutslevels">
|
| 136 | <h2>Loggers, Appenders, Layouts and Levels</h2>
|
| 137 | <p>
|
| 138 | A <em>logger</em> in log4javascript is the object on which log calls are
|
| 139 | made. A logger may be assigned zero or more <em>appenders</em>.
|
| 140 | An appender is an object that actually does the logging: for example,
|
| 141 | a <code><a href="#popupappender">PopUpAppender</a></code> logs messages to
|
| 142 | a pop-up console window while an <code><a href="#ajaxappender">AjaxAppender</a></code>
|
| 143 | uses HTTP to send log messages back to the server. Each appender is assigned
|
| 144 | a <em>layout</em>, which is responsible for formatting log messages that
|
| 145 | are passed to an appender.
|
| 146 | </p>
|
| 147 | <p>
|
| 148 | Every log message has a <em>level</em>. This is the severity of the message.
|
| 149 | Available levels are <code>TRACE</code>, <code>DEBUG</code>, <code>INFO</code>,
|
| 150 | <code>WARN</code>, <code>ERROR</code> and <code>FATAL</code> - these correspond to
|
| 151 | the logging methods <code>trace</code>, <code>debug</code>, <code>info</code>,
|
| 152 | <code>warn</code>, <code>error</code> and <code>fatal</code> of <code>Logger</code>.
|
| 153 | Levels are ordered as follows: <code>TRACE</code> < <code>DEBUG</code> <
|
| 154 | <code>INFO</code> < <code>WARN</code> < <code>ERROR</code> <
|
| 155 | <code>FATAL</code>. This means the <code>FATAL</code> is the most severe and
|
| 156 | <code>TRACE</code> the least. Also included are levels called <code>ALL</code>
|
| 157 | and <code>OFF</code> intended to enable or disable all logging respectively.
|
| 158 | </p>
|
| 159 | <p>
|
| 160 | Both loggers and appenders also have threshold levels (by default, <code>DEBUG</code>
|
| 161 | for loggers and <code>ALL</code> for appenders).
|
| 162 | Setting a level to either a logger or an appender disables log messages of severity
|
| 163 | lower than that level. For instance, if a level of <code>INFO</code> is set on a
|
| 164 | logger then only log messages of severity <code>INFO</code> or greater will be logged,
|
| 165 | meaning <code>DEBUG</code> and <code>TRACE</code> messages will not be logged. If the
|
| 166 | same logger had two appenders, one of level <code>DEBUG</code> and one of level
|
| 167 | <code>WARN</code> then the first appender will still only log messages of
|
| 168 | <code>INFO</code> or greater while the second appender will only log messages of level
|
| 169 | <code>WARN</code> or greater.
|
| 170 | </p>
|
| 171 | <p>
|
| 172 | This allows the developer fine control over which messages get logged where.
|
| 173 | </p>
|
| 174 | <div id="configuration">
|
| 175 | <h3>Configuring appenders</h3>
|
| 176 | <p>
|
| 177 | From version 1.4, <strong>configuring appenders is only possible via configuration
|
| 178 | methods</strong>. As the number of configuration options increases it becomes increasingly
|
| 179 | undesirable to use constructor parameters, so support for it has been dropped.
|
| 180 | </p>
|
| 181 | </div>
|
| 182 | <div id="loggersappenderslayoutslevelsexample">
|
| 183 | <h3>Example</h3>
|
| 184 | <p>
|
| 185 | <strong>NB.</strong> The Ajax side of this example relies on having
|
| 186 | server-side processing in place.
|
| 187 | </p>
|
| 188 | <p>
|
| 189 | First, log4javascript is initialized, and a logger (actually the
|
| 190 | anonymous logger) is assigned to a variable called <code>log</code>:
|
| 191 | </p>
|
| 192 | <pre class="code">
|
| 193 | <script type="text/javascript" src="log4javascript.js"></script>
|
| 194 | <script type="text/javascript">
|
| 195 | //<![CDATA[
|
| 196 | var log = log4javascript.getLogger();
|
| 197 | </pre>
|
| 198 | <p>
|
| 199 | <code>log</code> does not yet have any appenders, so a call to <code>log.debug()</code>
|
| 200 | will do nothing as yet. For this example we will use a
|
| 201 | <code><a href="#popupappender">PopUpAppender</a></code> for debugging purposes.
|
| 202 | Since the lifespan of the messages displayed in the pop-up is only going to be the
|
| 203 | same as that of the window, a <code><a href="#patternlayout">PatternLayout</a></code>
|
| 204 | is used that displays the time of the message and not the date (note that this is
|
| 205 | also true of PopUpAppender's default layout). The format of the string passed into
|
| 206 | PatternLayout is explained <a href="#patternlayout">below</a>.
|
| 207 | </p>
|
| 208 | <pre class="code">
|
| 209 | var popUpAppender = new log4javascript.PopUpAppender();
|
| 210 | var popUpLayout = new log4javascript.PatternLayout("%d{HH:mm:ss} %-5p - %m%n");
|
| 211 | popUpAppender.setLayout(popUpLayout);
|
| 212 | log.addAppender(popUpAppender);
|
| 213 | </pre>
|
| 214 | <p>
|
| 215 | Suppose that we also want to send log messages to the server, but limited to
|
| 216 | error messages only. To achieve this we use an
|
| 217 | <code><a href="#ajaxappender">AjaxAppender</a></code>. Note that if no layout is
|
| 218 | specified then for convenience a default layout is used; in the case of
|
| 219 | AjaxAppender, that is <code><a href="#httppostdatalayout">HttpPostDataLayout</a></code>,
|
| 220 | which formats log messages as a standard HTTP POST string from which a simple
|
| 221 | server-side script (not provided with log4javascript) will be able to extract
|
| 222 | posted parameters. This is fine for our purposes:
|
| 223 | </p>
|
| 224 | <pre class="code">
|
| 225 | var ajaxAppender = new log4javascript.AjaxAppender("myloggingservlet.do");
|
| 226 | ajaxAppender.setThreshold(log4javascript.Level.<code>ERROR</code>);
|
| 227 | log.addAppender(ajaxAppender);
|
| 228 | </pre>
|
| 229 | <p>
|
| 230 | Finally, some test log messages and the closing script tag:
|
| 231 | </p>
|
| 232 | <pre class="code">
|
| 233 | log.debug("Debugging message (appears in pop-up)");
|
| 234 | log.error("Error message (appears in pop-up and in server log)");
|
| 235 | //]]>
|
| 236 | </script>
|
| 237 | </pre>
|
| 238 | <p>
|
| 239 | The full script:
|
| 240 | </p>
|
| 241 | <pre class="code">
|
| 242 | <script type="text/javascript" src="log4javascript.js"></script>
|
| 243 | <script type="text/javascript">
|
| 244 | //<![CDATA[
|
| 245 | var log = log4javascript.getLogger();
|
| 246 | var popUpAppender = new log4javascript.PopUpAppender();
|
| 247 | var popUpLayout = new log4javascript.PatternLayout("%d{HH:mm:ss} %-5p - %m%n");
|
| 248 | popUpAppender.setLayout(popUpLayout);
|
| 249 | log.addAppender(popUpAppender);
|
| 250 | var ajaxAppender = new log4javascript.AjaxAppender("myloggingservlet.do");
|
| 251 | ajaxAppender.setThreshold(log4javascript.Level.ERROR);
|
| 252 | log.addAppender(ajaxAppender);
|
| 253 | log.debug("Debugging message (appears in pop-up)");
|
| 254 | log.error("Error message (appears in pop-up and in server log)");
|
| 255 | //]]>
|
| 256 | </script>
|
| 257 | </pre>
|
| 258 | <p>
|
| 259 | <a href="../examples/example_manual.html" title="View example (opens in new window)"
|
| 260 | target="_blank">See this example in action</a> (opens in new window)
|
| 261 | </p>
|
| 262 | </div>
|
| 263 | <p class="linktotop">
|
| 264 | <a href="#container">Top</a>
|
| 265 | </p>
|
| 266 | </div>
|
| 267 | <div id="log4javascript">
|
| 268 | <h2>log4javascript static properties/methods</h2>
|
| 269 | <h4>Properties</h4>
|
| 270 | <ul class="propertieslist">
|
| 271 | <li class="property">
|
| 272 | <div class="name">version</div>
|
| 273 | <div class="summary">
|
| 274 | The version number of your copy of log4javascript.
|
| 275 | </div>
|
| 276 | </li>
|
| 277 | <li class="property">
|
| 278 | <div class="name">edition</div>
|
| 279 | <div class="summary">
|
| 280 | The edition of your copy of log4javascript.
|
| 281 | </div>
|
| 282 | </li>
|
| 283 | <li class="property">
|
| 284 | <div class="name">logLog</div>
|
| 285 | <div class="summary">
|
| 286 | log4javascript's internal logging object. <a href="#loglog">See below for more details</a>.
|
| 287 | </div>
|
| 288 | </li>
|
| 289 | </ul>
|
| 290 | <h4>Methods</h4>
|
| 291 | <ul class="propertieslist">
|
| 292 | <li class="method">
|
| 293 | <div class="name">getLogger</div>
|
| 294 | <div class="methodsignature"><code>Logger <strong>getLogger</strong>([String <em>loggerName</em>])</code></div>
|
| 295 | <div class="paramsheading">Parameters:</div>
|
| 296 | <ul class="params">
|
| 297 | <li class="param">
|
| 298 | <code class="paramname">loggerName</code>
|
| 299 | [<em>optional</em>]
|
| 300 | </li>
|
| 301 | </ul>
|
| 302 | <div class="summary">
|
| 303 | <p>
|
| 304 | Returns a logger with the specified name, creating it if a logger with that name does not
|
| 305 | already exist. If no name is specified, a logger is returned with name <code>[anonymous]</code>, and
|
| 306 | subsequent calls to <code>getLogger()</code> (with no logger name specified) will return
|
| 307 | this same logger object.
|
| 308 | </p>
|
| 309 | <p>
|
| 310 | Note that the names <code>[anonymous]</code>, <code>[default]</code>, <code>[null]</code>
|
| 311 | and <code>root</code> are reserved for
|
| 312 | the anonymous logger, default logger, null logger and root logger respectively.
|
| 313 | </p>
|
| 314 | </div>
|
| 315 | </li>
|
| 316 | <li class="method">
|
| 317 | <div class="name">getDefaultLogger</div>
|
| 318 | <div class="methodsignature"><code>Logger <strong>getDefaultLogger</strong>()</code></div>
|
| 319 | <div class="summary">
|
| 320 | Convenience method that returns the default logger. The default logger
|
| 321 | has a single appender: a <code><a href="#popupappender">PopUpAppender</a></code>
|
| 322 | with the default layout, width and height, and with <code>focusPopUp</code> set to false
|
| 323 | and <code>lazyInit</code>, <code>useOldPopUp</code> and
|
| 324 | <code>complainAboutPopUpBlocking</code> all set to true.
|
| 325 | </div>
|
| 326 | </li>
|
| 327 | <li class="method">
|
| 328 | <div class="name">getNullLogger</div>
|
| 329 | <div class="methodsignature"><code>Logger <strong>getNullLogger</strong>()</code></div>
|
| 330 | <div class="summary">
|
| 331 | Returns an empty logger with no appenders. Useful for disabling all logging.
|
| 332 | </div>
|
| 333 | </li>
|
| 334 | <li class="method">
|
| 335 | <div class="name">getRootLogger</div>
|
| 336 | <div class="methodsignature"><code>Logger <strong>getRootLogger</strong>()</code></div>
|
| 337 | <div class="summary">
|
| 338 | Returns the root logger from which all other loggers derive.
|
| 339 | </div>
|
| 340 | </li>
|
| 341 | <li class="method">
|
| 342 | <div class="name">resetConfiguration</div>
|
| 343 | <div class="methodsignature"><code>void <strong>resetConfiguration</strong>()</code></div>
|
| 344 | <div class="summary">
|
| 345 | Resets the all loggers to their default level.
|
| 346 | </div>
|
| 347 | </li>
|
| 348 | <li class="method">
|
| 349 | <div class="name">setEnabled</div>
|
| 350 | <div class="methodsignature"><code>void <strong>setEnabled</strong>(Boolean <em>enabled</em>)</code></div>
|
| 351 | <div class="paramsheading">Parameters:</div>
|
| 352 | <ul class="params">
|
| 353 | <li class="param">
|
| 354 | <code class="paramname">enabled</code>
|
| 355 | </li>
|
| 356 | </ul>
|
| 357 | <div class="summary">
|
| 358 | Enables or disables all logging, depending on <code>enabled</code>.
|
| 359 | </div>
|
| 360 | </li>
|
| 361 | <li class="method">
|
| 362 | <div class="name">isEnabled</div>
|
| 363 | <div class="methodsignature"><code>Boolean <strong>isEnabled</strong>()</code></div>
|
| 364 | <div class="summary">
|
| 365 | Returns true or false depending on whether logging is enabled.
|
| 366 | </div>
|
| 367 | </li>
|
| 368 | <li class="method" id="log4javascriptaddeventlistener">
|
| 369 | <div class="name">addEventListener</div>
|
| 370 | <div class="methodsignature"><code>void <strong>addEventListener</strong>(String <em>eventType</em>, Function <em>listener</em>)</code></div>
|
| 371 | <div class="paramsheading">Parameters:</div>
|
| 372 | <ul class="params">
|
| 373 | <li class="param">
|
| 374 | <code class="paramname">eventType</code>
|
| 375 | </li>
|
| 376 | <li class="param">
|
| 377 | <code class="paramname">listener</code>
|
| 378 | </li>
|
| 379 | </ul>
|
| 380 | <div class="summary">
|
| 381 | <p>
|
| 382 | Adds a function to be called when an event of the type specified occurs in log4javascript.
|
| 383 | Supported event types are <code>load</code> (occurs once the page has loaded) and
|
| 384 | <code>error</code>.
|
| 385 | </p>
|
| 386 | <p>
|
| 387 | Each listener is pased three paramaters:
|
| 388 | </p>
|
| 389 | <ul>
|
| 390 | <li><code>sender</code>. The object that raised the event (i.e. the log4javascript object);</li>
|
| 391 | <li><code>eventType</code>. The type of the event;</li>
|
| 392 | <li>
|
| 393 | <code>eventArgs</code>. An object containing of event-specific arguments. For the <code>error</code> event,
|
| 394 | this is an object with properties <code>message</code> and <code>exception</code>. For the <code>load</code>
|
| 395 | event this is an empty object.
|
| 396 | </li>
|
| 397 | </ul>
|
| 398 | </div>
|
| 399 | </li>
|
| 400 | <li class="method">
|
| 401 | <div class="name">removeEventListener</div>
|
| 402 | <div class="methodsignature"><code>void <strong>removeEventListener</strong>(String <em>eventType</em>, Function <em>listener</em>)</code></div>
|
| 403 | <div class="paramsheading">Parameters:</div>
|
| 404 | <ul class="params">
|
| 405 | <li class="param">
|
| 406 | <code class="paramname">eventType</code>
|
| 407 | </li>
|
| 408 | <li class="param">
|
| 409 | <code class="paramname">listener</code>
|
| 410 | </li>
|
| 411 | </ul>
|
| 412 | <div class="summary">
|
| 413 | Removes the event listener function supplied for the event of the type specified.
|
| 414 | </div>
|
| 415 | </li>
|
| 416 | <li class="method">
|
| 417 | <div class="name">dispatchEvent</div>
|
| 418 | <div class="methodsignature"><code>void <strong>dispatchEvent</strong>(String <em>eventType</em>, Object <em>eventArgs</em>)</code></div>
|
| 419 | <div class="paramsheading">Parameters:</div>
|
| 420 | <ul class="params">
|
| 421 | <li class="param">
|
| 422 | <code class="paramname">eventType</code>
|
| 423 | </li>
|
| 424 | <li class="param">
|
| 425 | <code class="paramname">eventArgs</code>
|
| 426 | </li>
|
| 427 | </ul>
|
| 428 | <div class="summary">
|
| 429 | Raises an event of type <code>eventType</code> on the <code>log4javascript</code> object.
|
| 430 | Each of the listeners for this type of event (registered via <code>addEventListener</code>)
|
| 431 | is called and passed <code>eventArgs</code> as the third parameter.
|
| 432 | </div>
|
| 433 | </li>
|
| 434 | <li class="method">
|
| 435 | <div class="name">setEventTypes</div>
|
| 436 | <div class="methodsignature"><code>void <strong>setEventTypes</strong>(Array <em>eventTypes</em>)</code></div>
|
| 437 | <div class="paramsheading">Parameters:</div>
|
| 438 | <ul class="params">
|
| 439 | <li class="param">
|
| 440 | <code class="paramname">eventTypes</code>
|
| 441 | </li>
|
| 442 | </ul>
|
| 443 | <div class="summary">
|
| 444 | Used internally to specify the types of events that the <code>log4javascript</code> object can raise.
|
| 445 | </div>
|
| 446 | </li>
|
| 447 | <li class="method">
|
| 448 | <div class="name">setShowStackTraces</div>
|
| 449 | <div class="methodsignature"><code>void <strong>setShowStackTraces</strong>(Boolean <em>show</em>)</code></div>
|
| 450 | <div class="paramsheading">Parameters:</div>
|
| 451 | <ul class="params">
|
| 452 | <li class="param">
|
| 453 | <code class="paramname">show</code>
|
| 454 | </li>
|
| 455 | </ul>
|
| 456 | <div class="summary">
|
| 457 | Enables or disables displaying of error stack traces, depending on <code>show</code>.
|
| 458 | By default, stack traces are not displayed. (Only works in Firefox)
|
| 459 | </div>
|
| 460 | </li>
|
| 461 | <li class="method">
|
| 462 | <div class="name">evalInScope</div>
|
| 463 | <div class="methodsignature"><code>Object <strong>evalInScope</strong>(String <em>expr</em>)</code></div>
|
| 464 | <div class="paramsheading">Parameters:</div>
|
| 465 | <ul class="params">
|
| 466 | <li class="param">
|
| 467 | <code class="paramname">expr</code>
|
| 468 | </li>
|
| 469 | </ul>
|
| 470 | <div class="summary">
|
| 471 | This evaluates the given expression in the log4javascript scope, thus allowing
|
| 472 | scripts to access internal log4javascript variables and functions. This was written
|
| 473 | for the purposes of automated testing but could be used by custom extensions to
|
| 474 | log4javascript.
|
| 475 | </div>
|
| 476 | </li>
|
| 477 | </ul>
|
| 478 | <p class="linktotop">
|
| 479 | <a href="#container">Top</a>
|
| 480 | </p>
|
| 481 | </div>
|
| 482 | <div id="levels">
|
| 483 | <h2>Levels</h2>
|
| 484 | <p>
|
| 485 | Levels are available as static properties of the <code>log4javascript.Level</code>
|
| 486 | object. In ascending order of severity:
|
| 487 | </p>
|
| 488 | <ol>
|
| 489 | <li><code>log4javascript.Level.ALL</code></li>
|
| 490 | <li><code>log4javascript.Level.TRACE</code></li>
|
| 491 | <li><code>log4javascript.Level.DEBUG</code></li>
|
| 492 | <li><code>log4javascript.Level.INFO</code></li>
|
| 493 | <li><code>log4javascript.Level.WARN</code></li>
|
| 494 | <li><code>log4javascript.Level.ERROR</code></li>
|
| 495 | <li><code>log4javascript.Level.FATAL</code></li>
|
| 496 | <li><code>log4javascript.Level.OFF</code></li>
|
| 497 | </ol>
|
| 498 | <p class="linktotop">
|
| 499 | <a href="#container">Top</a>
|
| 500 | </p>
|
| 501 | </div>
|
| 502 | <div id="loggers">
|
| 503 | <h2>Loggers</h2>
|
| 504 | <p>
|
| 505 | It is possible to have multiple loggers in log4javascript. For example, you
|
| 506 | may wish to have a logger for debugging purposes that logs messages to a
|
| 507 | pop-up window and a separate logger that reports any client-side application
|
| 508 | errors to the server via Ajax.
|
| 509 | </p>
|
| 510 | <div id="loggerhierarchy">
|
| 511 | <h3>Logger hierarchy and appender additivity</h3>
|
| 512 | <p>
|
| 513 | From version 1.4, log4javascript has hierarchical loggers, implemented in the same way
|
| 514 | as log4j. In summary, you specify a logger's parent logger by means of a dot between the
|
| 515 | parent logger name and the child logger name. Therefore the logger <code>tim.app.security</code>
|
| 516 | inherits from <code>tim.app</code>, which in turn inherits from <code>tim</code> which,
|
| 517 | finally, inherits from the root logger.
|
| 518 | </p>
|
| 519 | <p>
|
| 520 | What inheritance means for a logger is that in the absence of a threshold level set
|
| 521 | specifically on the logger it inherits its level from its parent; also, a logger inherits
|
| 522 | all its parent's appenders (this is known as <em>appender additivity</em> in log4j. This
|
| 523 | behaviour can be enabled or disabled via <code>setAdditivity()</code>. See below). In the
|
| 524 | above example, if the root logger has a level of <code>DEBUG</code> and one appender,
|
| 525 | each of the loggers <code>tim.app.security</code>, <code>tim.app</code> and <code>tim</code> would
|
| 526 | inherit the root level's appender. If, say, <code>tim.app</code>'s threshold level was set
|
| 527 | to <code>WARN</code>, <code>tim</code>'s effective level would remain at <code>DEBUG</code>
|
| 528 | (inherited from the root logger) while <code>tim.app.security</code>'s effective level would
|
| 529 | be <code>WARN</code>, inherited from <code>tim.app</code>. The important thing to note is
|
| 530 | that appenders accumulate down the logger hierarchy while levels are simply inherited from
|
| 531 | the nearest ancestor with a threshold level set.
|
| 532 | </p>
|
| 533 | <p>
|
| 534 | For a detailed explanation of the logger hierarchy, see the
|
| 535 | <a href="http://logging.apache.org/log4j/docs/manual.html" target="_blank"
|
| 536 | title="Log4j manual (opens in new window)">log4j manual</a>.
|
| 537 | </p>
|
| 538 | </div>
|
| 539 | <p><strong>Notes</strong></p>
|
| 540 | <ul>
|
| 541 | <li>
|
| 542 | It is not possible to instantiate loggers directly. Instead you must use
|
| 543 | one of the methods of the <code>log4javascript</code> object: <code>getLogger</code>,
|
| 544 | <code>getRootLogger</code>, <code>getDefaultLogger</code> or <code>getNullLogger</code>.
|
| 545 | </li>
|
| 546 | </ul>
|
| 547 | <h4>Logger methods</h4>
|
| 548 | <ul class="propertieslist">
|
| 549 | <li class="method">
|
| 550 | <div class="name">addAppender</div>
|
| 551 | <div class="methodsignature"><code>void <strong>addAppender</strong>(Appender <em>appender</em>)</code></div>
|
| 552 | <div class="paramsheading">Parameters:</div>
|
| 553 | <ul class="params">
|
| 554 | <li class="param">
|
| 555 | <code class="paramname">appender</code>
|
| 556 | </li>
|
| 557 | </ul>
|
| 558 | <div class="summary">
|
| 559 | Adds the given appender.
|
| 560 | </div>
|
| 561 | </li>
|
| 562 | <li class="method">
|
| 563 | <div class="name">removeAppender</div>
|
| 564 | <div class="methodsignature"><code>void <strong>removeAppender</strong>(Appender <em>appender</em>)</code></div>
|
| 565 | <div class="paramsheading">Parameters:</div>
|
| 566 | <ul class="params">
|
| 567 | <li class="param">
|
| 568 | <code class="paramname">appender</code>
|
| 569 | </li>
|
| 570 | </ul>
|
| 571 | <div class="summary">
|
| 572 | Removes the given appender.
|
| 573 | </div>
|
| 574 | </li>
|
| 575 | <li class="method">
|
| 576 | <div class="name">removeAllAppenders</div>
|
| 577 | <div class="methodsignature"><code>void <strong>removeAllAppenders</strong>()</code></div>
|
| 578 | <div class="summary">
|
| 579 | Clears all appenders for the current logger.
|
| 580 | </div>
|
| 581 | </li>
|
| 582 | <li class="method">
|
| 583 | <div class="name">setLevel</div>
|
| 584 | <div class="methodsignature"><code>void <strong>setLevel</strong>(Level <em>level</em>)</code></div>
|
| 585 | <div class="paramsheading">Parameters:</div>
|
| 586 | <ul class="params">
|
| 587 | <li class="param">
|
| 588 | <code class="paramname">level</code>
|
| 589 | </li>
|
| 590 | </ul>
|
| 591 | <div class="summary">
|
| 592 | Sets the level. Log messages of a lower level than <code>level</code> will not be logged.
|
| 593 | Default value is <code>DEBUG</code>.
|
| 594 | </div>
|
| 595 | </li>
|
| 596 | <li class="method">
|
| 597 | <div class="name">getLevel</div>
|
| 598 | <div class="methodsignature"><code>Level <strong>getLevel</strong>()</code></div>
|
| 599 | <div class="summary">
|
| 600 | Returns the level explicitly set for this logger or <code>null</code> if none has been set.
|
| 601 | </div>
|
| 602 | </li>
|
| 603 | <li class="method">
|
| 604 | <div class="name">getEffectiveLevel</div>
|
| 605 | <div class="methodsignature"><code>Level <strong>getEffectiveLevel</strong>()</code></div>
|
| 606 | <div class="summary">
|
| 607 | Returns the level at which the logger is operating. This is either the level explicitly
|
| 608 | set on the logger or, if no level has been set, the effective level of the logger's parent.
|
| 609 | </div>
|
| 610 | </li>
|
| 611 | <li class="method">
|
| 612 | <div class="name">setAdditivity</div>
|
| 613 | <div class="methodsignature"><code>void <strong>setAdditivity</strong>(Boolean <em>additivity</em>)</code></div>
|
| 614 | <div class="paramsheading">Parameters:</div>
|
| 615 | <ul class="params">
|
| 616 | <li class="param">
|
| 617 | <code class="paramname">additivity</code>
|
| 618 | </li>
|
| 619 | </ul>
|
| 620 | <div class="summary">
|
| 621 | <p>
|
| 622 | Sets whether appender additivity is enabled (the default) or disabled. If set to false, this
|
| 623 | particular logger will not inherit any appenders form its ancestors. Any descendant of this
|
| 624 | logger, however, will inherit from its ancestors as normal, unless its own additivity is
|
| 625 | explicitly set to false.
|
| 626 | </p>
|
| 627 | <p>
|
| 628 | Default value is <code>true</code>.
|
| 629 | </p>
|
| 630 | </div>
|
| 631 | </li>
|
| 632 | <li class="method">
|
| 633 | <div class="name">getAdditivity</div>
|
| 634 | <div class="methodsignature"><code>Level <strong>getLevel</strong>()</code></div>
|
| 635 | <div class="summary">
|
| 636 | Returns whether additivity is enabled for this logger.
|
| 637 | </div>
|
| 638 | </li>
|
| 639 | <li class="method">
|
| 640 | <div class="name">log</div>
|
| 641 | <div class="methodsignature"><code>void <strong>log</strong>(Level <em>level</em>, Object <em>params</em>)</code></div>
|
| 642 | <div class="paramsheading">Parameters:</div>
|
| 643 | <ul class="params">
|
| 644 | <li class="param">
|
| 645 | <code class="paramname">level</code>
|
| 646 | </li>
|
| 647 | <li class="param">
|
| 648 | <code class="paramname">params</code>
|
| 649 | </li>
|
| 650 | </ul>
|
| 651 | <div class="summary">
|
| 652 | Generic logging method used by wrapper methods such as <code>debug</code>,
|
| 653 | <code>error</code> etc.
|
| 654 | </div>
|
| 655 | <p><strong>Notes</strong></p>
|
| 656 | <ul>
|
| 657 | <li>
|
| 658 | The signature of this method has changed in 1.4.
|
| 659 | </li>
|
| 660 | </ul>
|
| 661 | </li>
|
| 662 | <li class="method">
|
| 663 | <div class="name">trace</div>
|
| 664 | <div class="methodsignature"><code>void <strong>trace</strong>(Object <em>message1</em>[, Object <em>message2</em>, ... ][, Error <em>exception</em>])</code></div>
|
| 665 | <div class="paramsheading">Parameters:</div>
|
| 666 | <ul class="params">
|
| 667 | <li class="param">
|
| 668 | <code class="paramname">message1[, message2...]</code>
|
| 669 | </li>
|
| 670 | <li class="param">
|
| 671 | <code class="paramname">exception</code>
|
| 672 | [<em>optional</em>]
|
| 673 | </li>
|
| 674 | </ul>
|
| 675 | <div class="summary">
|
| 676 | Logs one or more messages and optionally an error at level <code>TRACE</code>.
|
| 677 | </div>
|
| 678 | <p><strong>Notes</strong></p>
|
| 679 | <ul>
|
| 680 | <li>
|
| 681 | Logging of multiple messages in one call is new in 1.4.
|
| 682 | </li>
|
| 683 | </ul>
|
| 684 | </li>
|
| 685 | <li class="method">
|
| 686 | <div class="name">debug</div>
|
| 687 | <div class="methodsignature"><code>void <strong>debug</strong>(Object <em>message1</em>[, Object <em>message2</em>, ... ][, Error <em>exception</em>])</code></div>
|
| 688 | <div class="paramsheading">Parameters:</div>
|
| 689 | <ul class="params">
|
| 690 | <li class="param">
|
| 691 | <code class="paramname">message1[, message2...]</code>
|
| 692 | </li>
|
| 693 | <li class="param">
|
| 694 | <code class="paramname">exception</code>
|
| 695 | [<em>optional</em>]
|
| 696 | </li>
|
| 697 | </ul>
|
| 698 | <div class="summary">
|
| 699 | Logs one or more messages and optionally an error at level <code>DEBUG</code>.
|
| 700 | </div>
|
| 701 | <p><strong>Notes</strong></p>
|
| 702 | <ul>
|
| 703 | <li>
|
| 704 | Logging of multiple messages in one call is new in 1.4.
|
| 705 | </li>
|
| 706 | </ul>
|
| 707 | </li>
|
| 708 | <li class="method">
|
| 709 | <div class="name">info</div>
|
| 710 | <div class="methodsignature"><code>void <strong>info</strong>(Object <em>message1</em>[, Object <em>message2</em>, ... ][, Error <em>exception</em>])</code></div>
|
| 711 | <div class="paramsheading">Parameters:</div>
|
| 712 | <ul class="params">
|
| 713 | <li class="param">
|
| 714 | <code class="paramname">message1[, message2...]</code>
|
| 715 | </li>
|
| 716 | <li class="param">
|
| 717 | <code class="paramname">exception</code>
|
| 718 | [<em>optional</em>]
|
| 719 | </li>
|
| 720 | </ul>
|
| 721 | <div class="summary">
|
| 722 | Logs one or more messages and optionally an error at level <code>INFO</code>.
|
| 723 | </div>
|
| 724 | <p><strong>Notes</strong></p>
|
| 725 | <ul>
|
| 726 | <li>
|
| 727 | Logging of multiple messages in one call is new in 1.4.
|
| 728 | </li>
|
| 729 | </ul>
|
| 730 | </li>
|
| 731 | <li class="method">
|
| 732 | <div class="name">warn</div>
|
| 733 | <div class="methodsignature"><code>void <strong>warn</strong>(Object <em>message1</em>[, Object <em>message2</em>, ... ][, Error <em>exception</em>])</code></div>
|
| 734 | <div class="paramsheading">Parameters:</div>
|
| 735 | <ul class="params">
|
| 736 | <li class="param">
|
| 737 | <code class="paramname">message1[, message2...]</code>
|
| 738 | </li>
|
| 739 | <li class="param">
|
| 740 | <code class="paramname">exception</code>
|
| 741 | [<em>optional</em>]
|
| 742 | </li>
|
| 743 | </ul>
|
| 744 | <div class="summary">
|
| 745 | Logs one or more messages and optionally an error at level <code>WARN</code>.
|
| 746 | </div>
|
| 747 | <p><strong>Notes</strong></p>
|
| 748 | <ul>
|
| 749 | <li>
|
| 750 | Logging of multiple messages in one call is new in 1.4.
|
| 751 | </li>
|
| 752 | </ul>
|
| 753 | </li>
|
| 754 | <li class="method">
|
| 755 | <div class="name">error</div>
|
| 756 | <div class="methodsignature"><code>void <strong>error</strong>(Object <em>message1</em>[, Object <em>message2</em>, ... ][, Error <em>exception</em>])</code></div>
|
| 757 | <div class="paramsheading">Parameters:</div>
|
| 758 | <ul class="params">
|
| 759 | <li class="param">
|
| 760 | <code class="paramname">message1[, message2...]</code>
|
| 761 | </li>
|
| 762 | <li class="param">
|
| 763 | <code class="paramname">exception</code>
|
| 764 | [<em>optional</em>]
|
| 765 | </li>
|
| 766 | </ul>
|
| 767 | <div class="summary">
|
| 768 | Logs one or more messages and optionally an error at level <code>ERROR</code>.
|
| 769 | </div>
|
| 770 | <p><strong>Notes</strong></p>
|
| 771 | <ul>
|
| 772 | <li>
|
| 773 | Logging of multiple messages in one call is new in 1.4.
|
| 774 | </li>
|
| 775 | </ul>
|
| 776 | </li>
|
| 777 | <li class="method">
|
| 778 | <div class="name">fatal</div>
|
| 779 | <div class="methodsignature"><code>void <strong>fatal</strong>(Object <em>message1</em>[, Object <em>message2</em>, ... ][, Error <em>exception</em>])</code></div>
|
| 780 | <div class="paramsheading">Parameters:</div>
|
| 781 | <ul class="params">
|
| 782 | <li class="param">
|
| 783 | <code class="paramname">message1[, message2...]</code>
|
| 784 | </li>
|
| 785 | <li class="param">
|
| 786 | <code class="paramname">exception</code>
|
| 787 | [<em>optional</em>]
|
| 788 | </li>
|
| 789 | </ul>
|
| 790 | <div class="summary">
|
| 791 | Logs one or more messages and optionally an error at level <code>FATAL</code>.
|
| 792 | </div>
|
| 793 | <p><strong>Notes</strong></p>
|
| 794 | <ul>
|
| 795 | <li>
|
| 796 | Logging of multiple messages in one call is new in 1.4.
|
| 797 | </li>
|
| 798 | </ul>
|
| 799 | </li>
|
| 800 | <li class="method">
|
| 801 | <div class="name">isEnabledFor</div>
|
| 802 | <div class="methodsignature"><code>Boolean <strong>isEnabledFor</strong>(Level <em>level</em>, Error <em>exception</em>)</code></div>
|
| 803 | <div class="paramsheading">Parameters:</div>
|
| 804 | <ul class="params">
|
| 805 | <li class="param">
|
| 806 | <code class="paramname">level</code>
|
| 807 | </li>
|
| 808 | </ul>
|
| 809 | <div class="summary">
|
| 810 | Returns whether the logger is enabled for the specified level.
|
| 811 | </div>
|
| 812 | </li>
|
| 813 | <li class="method">
|
| 814 | <div class="name">isTraceEnabled</div>
|
| 815 | <div class="methodsignature"><code>Boolean <strong>isTraceEnabled</strong>()</code></div>
|
| 816 | <div class="summary">
|
| 817 | Returns whether the logger is enabled for <code>TRACE</code> messages.
|
| 818 | </div>
|
| 819 | </li>
|
| 820 | <li class="method">
|
| 821 | <div class="name">isDebugEnabled</div>
|
| 822 | <div class="methodsignature"><code>Boolean <strong>isDebugEnabled</strong>()</code></div>
|
| 823 | <div class="summary">
|
| 824 | Returns whether the logger is enabled for <code>DEBUG</code> messages.
|
| 825 | </div>
|
| 826 | </li>
|
| 827 | <li class="method">
|
| 828 | <div class="name">isInfoEnabled</div>
|
| 829 | <div class="methodsignature"><code>Boolean <strong>isInfoEnabled</strong>()</code></div>
|
| 830 | <div class="summary">
|
| 831 | Returns whether the logger is enabled for <code>INFO</code> messages.
|
| 832 | </div>
|
| 833 | </li>
|
| 834 | <li class="method">
|
| 835 | <div class="name">isWarnEnabled</div>
|
| 836 | <div class="methodsignature"><code>Boolean <strong>isWarnEnabled</strong>()</code></div>
|
| 837 | <div class="summary">
|
| 838 | Returns whether the logger is enabled for <code>WARN</code> messages.
|
| 839 | </div>
|
| 840 | </li>
|
| 841 | <li class="method">
|
| 842 | <div class="name">isErrorEnabled</div>
|
| 843 | <div class="methodsignature"><code>Boolean <strong>isErrorEnabled</strong>()</code></div>
|
| 844 | <div class="summary">
|
| 845 | Returns whether the logger is enabled for <code>ERROR</code> messages.
|
| 846 | </div>
|
| 847 | </li>
|
| 848 | <li class="method">
|
| 849 | <div class="name">isFatalEnabled</div>
|
| 850 | <div class="methodsignature"><code>Boolean <strong>isFatalEnabled</strong>()</code></div>
|
| 851 | <div class="summary">
|
| 852 | Returns whether the logger is enabled for <code>FATAL</code> messages.
|
| 853 | </div>
|
| 854 | </li>
|
| 855 | <li class="method">
|
| 856 | <div class="name">group</div>
|
| 857 | <div class="methodsignature"><code>void <strong>group</strong>(String <em>name</em>, Boolean <em>initiallyExpanded</em>)</code></div>
|
| 858 | <div class="paramsheading">Parameters:</div>
|
| 859 | <ul class="params">
|
| 860 | <li class="param">
|
| 861 | <code class="paramname">name</code>
|
| 862 | </li>
|
| 863 | <li class="param">
|
| 864 | <code class="paramname">initiallyExpanded</code>
|
| 865 | [<em>optional</em>]
|
| 866 | </li>
|
| 867 | </ul>
|
| 868 | <div class="summary">
|
| 869 | Starts a new group of log messages. In appenders that support grouping (currently
|
| 870 | <code><a href="#popupappender">PopUpAppender</a></code> and
|
| 871 | <code><a href="#inpageappender">InPageAppender</a></code>), a group appears as an expandable
|
| 872 | section in the console, labelled with the <code>name</code> specified.
|
| 873 | Specifying <code>initiallyExpanded</code> determines whether the
|
| 874 | group starts off expanded (the default is <code>true</code>). Groups may be nested.
|
| 875 | </div>
|
| 876 | </li>
|
| 877 | <li class="method">
|
| 878 | <div class="name">groupEnd</div>
|
| 879 | <div class="methodsignature"><code>void <strong>groupEnd</strong>()</code></div>
|
| 880 | <div class="summary">
|
| 881 | Ends the current group. If there is no group then this function has no effect.
|
| 882 | </div>
|
| 883 | </li>
|
| 884 | <li class="method">
|
| 885 | <div class="name">time</div>
|
| 886 | <div class="methodsignature"><code>void <strong>time</strong>(String <em>name</em>, Level <em>level</em>)</code></div>
|
| 887 | <div class="paramsheading">Parameters:</div>
|
| 888 | <ul class="params">
|
| 889 | <li class="param">
|
| 890 | <code class="paramname">name</code>
|
| 891 | </li>
|
| 892 | <li class="param">
|
| 893 | <code class="paramname">level</code>
|
| 894 | [<em>optional</em>]
|
| 895 | </li>
|
| 896 | </ul>
|
| 897 | <div class="summary">
|
| 898 | Starts a timer with name <code>name</code>. When the timer is ended with a
|
| 899 | call to <code>timeEnd</code> using the same name, the amount of time that
|
| 900 | has elapsed in milliseconds since the timer was started is logged at level
|
| 901 | <code>level</code>. If not level is supplied, the level defaults to <code>INFO</code>.
|
| 902 | </div>
|
| 903 | </li>
|
| 904 | <li class="method">
|
| 905 | <div class="name">timeEnd</div>
|
| 906 | <div class="methodsignature"><code>void <strong>timeEnd</strong>(String <em>name</em>)</code></div>
|
| 907 | <div class="paramsheading">Parameters:</div>
|
| 908 | <ul class="params">
|
| 909 | <li class="param">
|
| 910 | <code class="paramname">name</code>
|
| 911 | </li>
|
| 912 | </ul>
|
| 913 | <div class="summary">
|
| 914 | Ends the timer with name <code>name</code> and logs the time elapsed.
|
| 915 | </div>
|
| 916 | </li>
|
| 917 | <li class="method">
|
| 918 | <div class="name">assert</div>
|
| 919 | <div class="methodsignature"><code>void <strong>assert</strong>(Object <em>expr</em>)</code></div>
|
| 920 | <div class="paramsheading">Parameters:</div>
|
| 921 | <ul class="params">
|
| 922 | <li class="param">
|
| 923 | <code class="paramname">expr</code>
|
| 924 | </li>
|
| 925 | </ul>
|
| 926 | <div class="summary">
|
| 927 | Asserts the given expression is <code>true</code> or evaluates to <code>true</code>.
|
| 928 | If so, nothing is logged. If not, an error is logged at the <code>ERROR</code> level.
|
| 929 | </div>
|
| 930 | </li>
|
| 931 | </ul>
|
| 932 | <p class="linktotop">
|
| 933 | <a href="#container">Top</a>
|
| 934 | </p>
|
| 935 | </div>
|
| 936 | <div id="appenders">
|
| 937 | <h2>Appenders</h2>
|
| 938 | <div id="appender">
|
| 939 | <h3>Appender</h3>
|
| 940 | <p>
|
| 941 | There are methods common to all appenders, as listed below.
|
| 942 | </p>
|
| 943 | <h4>Methods</h4>
|
| 944 | <ul class="propertieslist">
|
| 945 | <li class="method">
|
| 946 | <div class="name">doAppend</div>
|
| 947 | <div class="methodsignature"><code>void <strong>doAppend</strong>(LoggingEvent <em>loggingEvent</em>)</code></div>
|
| 948 | <div class="paramsheading">Parameters:</div>
|
| 949 | <ul class="params">
|
| 950 | <li class="param">
|
| 951 | <code class="paramname">loggingEvent</code>
|
| 952 | </li>
|
| 953 | </ul>
|
| 954 | <div class="summary">
|
| 955 | <p>
|
| 956 | Checks the logging event's level is at least as severe as the appender's
|
| 957 | threshold and calls the appender's <code>append</code> method if so.
|
| 958 | </p>
|
| 959 | <p>
|
| 960 | This method should not in general be used directly or overridden.
|
| 961 | </p>
|
| 962 | </div>
|
| 963 | </li>
|
| 964 | <li class="method">
|
| 965 | <div class="name">append</div>
|
| 966 | <div class="methodsignature"><code>void <strong>append</strong>(LoggingEvent <em>loggingEvent</em>)</code></div>
|
| 967 | <div class="paramsheading">Parameters:</div>
|
| 968 | <ul class="params">
|
| 969 | <li class="param">
|
| 970 | <code class="paramname">loggingEvent</code>
|
| 971 | </li>
|
| 972 | </ul>
|
| 973 | <div class="summary">
|
| 974 | Appender-specific method to append a log message. Every appender object should implement
|
| 975 | this method.
|
| 976 | </div>
|
| 977 | </li>
|
| 978 | <li class="method">
|
| 979 | <div class="name">setLayout</div>
|
| 980 | <div class="methodsignature"><code>void <strong>setLayout</strong>(Layout <em>layout</em>)</code></div>
|
| 981 | <div class="paramsheading">Parameters:</div>
|
| 982 | <ul class="params">
|
| 983 | <li class="param">
|
| 984 | <code class="paramname">layout</code>
|
| 985 | </li>
|
| 986 | </ul>
|
| 987 | <div class="summary">
|
| 988 | Sets the appender's layout.
|
| 989 | </div>
|
| 990 | </li>
|
| 991 | <li class="method">
|
| 992 | <div class="name">getLayout</div>
|
| 993 | <div class="methodsignature"><code>Layout <strong>getLayout</strong>()</code></div>
|
| 994 | <div class="summary">
|
| 995 | Returns the appender's layout.
|
| 996 | </div>
|
| 997 | </li>
|
| 998 | <li class="method">
|
| 999 | <div class="name">setThreshold</div>
|
| 1000 | <div class="methodsignature"><code>void <strong>setThreshold</strong>(Level <em>level</em>)</code></div>
|
| 1001 | <div class="paramsheading">Parameters:</div>
|
| 1002 | <ul class="params">
|
| 1003 | <li class="param">
|
| 1004 | <code class="paramname">level</code>
|
| 1005 | </li>
|
| 1006 | </ul>
|
| 1007 | <div class="summary">
|
| 1008 | Sets the appender's threshold. Log messages of level less severe than this
|
| 1009 | threshold will not be logged.
|
| 1010 | </div>
|
| 1011 | </li>
|
| 1012 | <li class="method">
|
| 1013 | <div class="name">getThreshold</div>
|
| 1014 | <div class="methodsignature"><code>Level <strong>getThreshold</strong>()</code></div>
|
| 1015 | <div class="summary">
|
| 1016 | Returns the appender's threshold.
|
| 1017 | </div>
|
| 1018 | </li>
|
| 1019 | <li class="method">
|
| 1020 | <div class="name">toString</div>
|
| 1021 | <div class="methodsignature"><code>string <strong>toString</strong>()</code></div>
|
| 1022 | <div class="summary">
|
| 1023 | Returns a string representation of the appender. Every appender object should implement
|
| 1024 | this method.
|
| 1025 | </div>
|
| 1026 | </li>
|
| 1027 | </ul>
|
| 1028 | <p class="linktotop">
|
| 1029 | <a href="#container">Top</a>
|
| 1030 | </p>
|
| 1031 | </div>
|
| 1032 | <div id="alertappender">
|
| 1033 | <h3>AlertAppender</h3>
|
| 1034 | <p class="editions">Editions: <strong>Standard</strong></p>
|
| 1035 | <p>
|
| 1036 | Displays a log message as a JavaScript alert.
|
| 1037 | </p>
|
| 1038 | <h4>Constructor</h4>
|
| 1039 | <ul class="propertieslist">
|
| 1040 | <li class="method">
|
| 1041 | <div class="name">AlertAppender</div>
|
| 1042 | <div class="methodsignature"><code><strong>AlertAppender</strong>()</code></div>
|
| 1043 | </li>
|
| 1044 | </ul>
|
| 1045 | <p class="linktotop">
|
| 1046 | <a href="#container">Top</a>
|
| 1047 | </p>
|
| 1048 | </div>
|
| 1049 | <div id="ajaxappender">
|
| 1050 | <h3>AjaxAppender</h3>
|
| 1051 | <p class="editions">Editions: <strong>Standard, Production</strong></p>
|
| 1052 | <p>
|
| 1053 | A flexible appender that asynchronously sends log messages to a server via HTTP
|
| 1054 | (Ajax, if you insist, though the 'x' of Ajax only comes into play in any form if you use an
|
| 1055 | <code><a href="#xmllayout">XmlLayout</a></code>).
|
| 1056 | </p>
|
| 1057 | <p>
|
| 1058 | The default configuration is to send each log message as a separate HTTP post
|
| 1059 | request to the server using an <code><a href="#httppostdatalayout">HttpPostDataLayout</a></code>,
|
| 1060 | without waiting for a response before sending any subsequent requests. However,
|
| 1061 | an <code>AjaxAppender</code> may be configured to do any one of or combinations of the following:
|
| 1062 | </p>
|
| 1063 | <ul>
|
| 1064 | <li>
|
| 1065 | send log messages in batches (if the selected layout supports it - particularly suited
|
| 1066 | to <code>AjaxAppender</code> are <code><a href="#jsonlayout">JsonLayout</a></code> and
|
| 1067 | <code><a href="#xmllayout">XmlLayout</a></code>, both of which allow batching);
|
| 1068 | </li>
|
| 1069 | <li>
|
| 1070 | wait for a response from a previous request before sending the next log message / batch
|
| 1071 | of messages;
|
| 1072 | </li>
|
| 1073 | <li>
|
| 1074 | send all queued log messages at timed intervals.
|
| 1075 | </li>
|
| 1076 | </ul>
|
| 1077 | <p><strong>Notes</strong></p>
|
| 1078 | <ul>
|
| 1079 | <li>
|
| 1080 | AjaxAppender relies on the <code>XMLHttpRequest</code> object. It also requires
|
| 1081 | the presence of correctly implemented <code>setRequestHeader</code> method on
|
| 1082 | this object, which rules out Opera prior to version 8.01. If your browser does not
|
| 1083 | support the necessary objects then one alert will display to explain why it
|
| 1084 | doesn't work, after which the appender will silently switch off.
|
| 1085 | </li>
|
| 1086 | <li>
|
| 1087 | In AjaxAppender only, <code>setLayout</code> may not be called after the first
|
| 1088 | message has been logged.
|
| 1089 | </li>
|
| 1090 | <li>
|
| 1091 | The default layout is <code><a href="#httppostdatalayout">HttpPostDataLayout</a></code>.
|
| 1092 | </li>
|
| 1093 | <li>
|
| 1094 | From version 1.4, log message data is always sent as one or more name/value pairs.
|
| 1095 | In the case of <code><a href="#httppostdatalayout">HttpPostDataLayout</a></code>, data
|
| 1096 | is sent the same as in previous versions. For other layouts such as
|
| 1097 | <code><a href="#jsonlayout">JsonLayout</a></code> and
|
| 1098 | <code><a href="#xmllayout">XmlLayout</a></code>, the formatted log message is posted as
|
| 1099 | the value of a parameter called <code>data</code>, though this may be changed via
|
| 1100 | <code>setPostVarName</code>.
|
| 1101 | </li>
|
| 1102 | <li>
|
| 1103 | From version 1.4, log message timestamps are sent as standard JavaScript times, i.e.
|
| 1104 | the number of milliseconds since 00:00:00 UTC on January 1, 1970.
|
| 1105 | </li>
|
| 1106 | <li>
|
| 1107 | <p>
|
| 1108 | Also from version 1.4, any outstanding log messages may optionally be sent when the
|
| 1109 | main page unloads (i.e. user follows a link, closes the window or refreshes the
|
| 1110 | page). This behaviour may be enabled using <code>setSendAllOnUnload</code>; see
|
| 1111 | below.
|
| 1112 | </p>
|
| 1113 | <p>
|
| 1114 | This behaviour is dependent on <code>window.onbeforeunload</code>; unfortunately,
|
| 1115 | Opera does not always raise this event, so this feature does not work reliably in
|
| 1116 | Opera.
|
| 1117 | </p>
|
| 1118 | </li>
|
| 1119 | </ul>
|
| 1120 | <h4>Constructor</h4>
|
| 1121 | <ul class="propertieslist">
|
| 1122 | <li class="method">
|
| 1123 | <div class="name">AjaxAppender</div>
|
| 1124 | <div class="methodsignature">
|
| 1125 | <code><strong>AjaxAppender</strong>(String <em>url</em>)</code>
|
| 1126 | </div>
|
| 1127 | <div class="paramsheading">Parameters:</div>
|
| 1128 | <ul class="params">
|
| 1129 | <li class="param">
|
| 1130 | <code class="paramname">url</code>
|
| 1131 | <div>
|
| 1132 | The URL to which log messages should be sent. Note that this is subject
|
| 1133 | to the usual Ajax restrictions: the URL should be in the same domain as that
|
| 1134 | of the page making the request.
|
| 1135 | </div>
|
| 1136 | </li>
|
| 1137 | </ul>
|
| 1138 | </li>
|
| 1139 | </ul>
|
| 1140 | <h4>Methods</h4>
|
| 1141 | <ul class="propertieslist">
|
| 1142 | <li class="method">
|
| 1143 | <div class="name">setSendAllOnUnload</div>
|
| 1144 | <div class="methodsignature"><code>void <strong>setSendAllOnUnload</strong>(Boolean <em>sendAllOnUnload</em>)</code></div>
|
| 1145 | <div class="summary">
|
| 1146 | <p>
|
| 1147 | [<em>not available after first message logged</em>]
|
| 1148 | </p>
|
| 1149 | <p>
|
| 1150 | Whether to send all remaining unsent log messages to the server when the page
|
| 1151 | unloads.
|
| 1152 | </p>
|
| 1153 | <p>
|
| 1154 | Since version 1.4.3, the default value is <code>false</code>. Previously the
|
| 1155 | default was <code>true</code>.
|
| 1156 | </p>
|
| 1157 | <p><strong>Notes</strong></p>
|
| 1158 | <ul>
|
| 1159 | <li>
|
| 1160 | This feature was found not to work prior to version 1.4.3 in WebKit
|
| 1161 | browsers (e.g. Google Chrome, Safari). As a result, a workaround was
|
| 1162 | implemented in 1.4.3 which has the unfortunate side effect of popping up a
|
| 1163 | confirmation dialog to the user if there are any log messages to send when
|
| 1164 | the page unloads. As a result, this feature is now obtrusive for the user
|
| 1165 | and is therefore disabled by default.
|
| 1166 | </li>
|
| 1167 | <li>
|
| 1168 | This feature does not work in any version of Opera.
|
| 1169 | </li>
|
| 1170 | </ul>
|
| 1171 | </div>
|
| 1172 | </li>
|
| 1173 | <li class="method">
|
| 1174 | <div class="name">isSendAllOnUnload</div>
|
| 1175 | <div class="methodsignature"><code>Boolean <strong>isSendAllOnUnload</strong>()</code></div>
|
| 1176 | <div class="summary">
|
| 1177 | Returns whether all remaining unsent log messages are sent to the server when the page unloads.
|
| 1178 | </div>
|
| 1179 | </li>
|
| 1180 | <li class="method">
|
| 1181 | <div class="name">setPostVarName</div>
|
| 1182 | <div class="methodsignature"><code>void <strong>setPostVarName</strong>(String <em>postVarName</em>)</code></div>
|
| 1183 | <div class="summary">
|
| 1184 | <p>
|
| 1185 | [<em>not available after first message logged</em>]
|
| 1186 | </p>
|
| 1187 | <p>
|
| 1188 | Sets the post variable name whose value will the formatted log message(s) for
|
| 1189 | each request.
|
| 1190 | </p>
|
| 1191 | <p>
|
| 1192 | Default value is <code>data</code>.
|
| 1193 | </p>
|
| 1194 | <p><strong>Notes</strong></p>
|
| 1195 | <ul>
|
| 1196 | <li>
|
| 1197 | This has no effect if the current layout is an
|
| 1198 | <code><a href="#httppostdatalayout">HttpPostDataLayout</a></code>.
|
| 1199 | </li>
|
| 1200 | </ul>
|
| 1201 | </div>
|
| 1202 | </li>
|
| 1203 | <li class="method">
|
| 1204 | <div class="name">getPostVarName</div>
|
| 1205 | <div class="methodsignature"><code>String <strong>getPostVarName</strong>()</code></div>
|
| 1206 | <div class="summary">
|
| 1207 | Returns the post variable name whose value will the formatted log message(s) for
|
| 1208 | each request.
|
| 1209 | </div>
|
| 1210 | </li>
|
| 1211 | <li class="method">
|
| 1212 | <div class="name">setTimed</div>
|
| 1213 | <div class="methodsignature"><code>void <strong>setTimed</strong>(Boolean <em>timed</em>)</code></div>
|
| 1214 | <div class="summary">
|
| 1215 | <p>
|
| 1216 | [<em>not available after first message logged</em>]
|
| 1217 | </p>
|
| 1218 | <p>
|
| 1219 | Whether to send log messages to the server at regular, timed intervals.
|
| 1220 | </p>
|
| 1221 | <p>
|
| 1222 | Default value is <code>false</code>.
|
| 1223 | </p>
|
| 1224 | </div>
|
| 1225 | </li>
|
| 1226 | <li class="method">
|
| 1227 | <div class="name">isTimed</div>
|
| 1228 | <div class="methodsignature"><code>Boolean <strong>isTimed</strong>()</code></div>
|
| 1229 | <div class="summary">
|
| 1230 | Returns whether log messages are sent to the server at regular, timed intervals.
|
| 1231 | </div>
|
| 1232 | </li>
|
| 1233 | <li class="method">
|
| 1234 | <div class="name">setWaitForResponse</div>
|
| 1235 | <div class="methodsignature"><code>void <strong>setWaitForResponse</strong>(Boolean <em>waitForResponse</em>)</code></div>
|
| 1236 | <div class="summary">
|
| 1237 | <p>
|
| 1238 | [<em>not available after first message logged</em>]
|
| 1239 | </p>
|
| 1240 | <p>
|
| 1241 | Sets whether to wait for a response from a previous HTTP request from this
|
| 1242 | appender before sending the next log message / batch of messages.
|
| 1243 | </p>
|
| 1244 | <p>
|
| 1245 | Default value is <code>false</code>.
|
| 1246 | </p>
|
| 1247 | </div>
|
| 1248 | </li>
|
| 1249 | <li class="method">
|
| 1250 | <div class="name">isWaitForResponse</div>
|
| 1251 | <div class="methodsignature"><code>Boolean <strong>isWaitForResponse</strong>()</code></div>
|
| 1252 | <div class="summary">
|
| 1253 | Returns whether the appender waits for a response from a previous HTTP request from this
|
| 1254 | appender before sending the next log message / batch of messages.
|
| 1255 | </div>
|
| 1256 | </li>
|
| 1257 | <li class="method">
|
| 1258 | <div class="name">setBatchSize</div>
|
| 1259 | <div class="methodsignature"><code>void <strong>setBatchSize</strong>(Number <em>batchSize</em>)</code></div>
|
| 1260 | <div class="summary">
|
| 1261 | <p>
|
| 1262 | [<em>not available after first message logged</em>]
|
| 1263 | </p>
|
| 1264 | <p>
|
| 1265 | Sets the number of log messages to send in each request. If not specified,
|
| 1266 | defaults to <code>1</code>.
|
| 1267 | </p>
|
| 1268 | <p><strong>Notes</strong></p>
|
| 1269 | <ul>
|
| 1270 | <li>
|
| 1271 | Setting this to a number greater than 1 means that the appender will wait
|
| 1272 | until it has forwarded that many valid log messages before sending any more.
|
| 1273 | This also means that if the page unloads for any reason and <code>sendAllOnUnload</code>
|
| 1274 | is not set to <code>true</code>, any log messages waiting in the queue will not be sent.
|
| 1275 | </li>
|
| 1276 | <li>
|
| 1277 | If batching is used in conjunction with timed sending of log messages,
|
| 1278 | messages will still be sent in batches of size <code>batchSize</code>,
|
| 1279 | regardless of how many log messages are queued by the time the timed
|
| 1280 | sending is invoked. Incomplete batches will not be sent except when the
|
| 1281 | page unloads, if <code>sendAllOnUnload</code> is set to <code>true</code>.
|
| 1282 | </li>
|
| 1283 | </ul>
|
| 1284 | </div>
|
| 1285 | </li>
|
| 1286 | <li class="method">
|
| 1287 | <div class="name">getBatchSize</div>
|
| 1288 | <div class="methodsignature"><code>Number <strong>getBatchSize</strong>()</code></div>
|
| 1289 | <div class="summary">
|
| 1290 | Returns the number of log messages sent in each request. See above for more details.
|
| 1291 | </div>
|
| 1292 | </li>
|
| 1293 | <li class="method">
|
| 1294 | <div class="name">setTimerInterval</div>
|
| 1295 | <div class="methodsignature"><code>void <strong>setTimerInterval</strong>(Number <em>timerInterval</em>)</code></div>
|
| 1296 | <div class="summary">
|
| 1297 | <p>
|
| 1298 | [<em>not available after first message logged</em>]
|
| 1299 | </p>
|
| 1300 | <p>
|
| 1301 | Sets the length of time in milliseconds between each sending of queued log
|
| 1302 | messages.
|
| 1303 | </p>
|
| 1304 | <p><strong>Notes</strong></p>
|
| 1305 | <ul>
|
| 1306 | <li>
|
| 1307 | <code>timerInterval</code> only has an effect in conjunction with
|
| 1308 | <code>timed</code> (set by <code>setTimed()</code>. If <code>timed</code>
|
| 1309 | is set to false then <code>timerInterval</code> has no effect.
|
| 1310 | </li>
|
| 1311 | <li>
|
| 1312 | Each time the queue of log messages or batches of messages is cleared,
|
| 1313 | the countdown to the next sending only starts once the final request
|
| 1314 | has been sent (and, if <code>waitForResponse</code> is set to <code>true</code>,
|
| 1315 | the final response received). This means that the actual interval at
|
| 1316 | which the queue of messages is cleared cannot be fixed.
|
| 1317 | </li>
|
| 1318 | </ul>
|
| 1319 | </div>
|
| 1320 | </li>
|
| 1321 | <li class="method">
|
| 1322 | <div class="name">getTimerInterval</div>
|
| 1323 | <div class="methodsignature"><code>Number <strong>getTimerInterval</strong>()</code></div>
|
| 1324 | <div class="summary">
|
| 1325 | Returns the length of time in milliseconds between each sending of queued log
|
| 1326 | messages. See above for more details.
|
| 1327 | </div>
|
| 1328 | </li>
|
| 1329 | <li class="method">
|
| 1330 | <div class="name">setRequestSuccessCallback</div>
|
| 1331 | <div class="methodsignature"><code>void <strong>setRequestSuccessCallback</strong>(Function <em>requestSuccessCallback</em>)</code></div>
|
| 1332 | <div class="summary">
|
| 1333 | <p>
|
| 1334 | Sets the function that is called whenever a successful request is made, called at the
|
| 1335 | point at which the response is received. This feature can be used to confirm
|
| 1336 | whether a request has been successful and act accordingly.
|
| 1337 | </p>
|
| 1338 | <p>
|
| 1339 | A single parameter, <code>xmlHttp</code>, is passed to the callback function.
|
| 1340 | This is the XMLHttpRequest object that performed the request.
|
| 1341 | </p>
|
| 1342 | </div>
|
| 1343 | </li>
|
| 1344 | <li class="method">
|
| 1345 | <div class="name">setFailCallback</div>
|
| 1346 | <div class="methodsignature"><code>void <strong>setFailCallback</strong>(Function <em>failCallback</em>)</code></div>
|
| 1347 | <div class="summary">
|
| 1348 | <p>
|
| 1349 | Sets the function that is called whenever any kind of failure occurs in the appender,
|
| 1350 | including browser deficiencies or configuration errors (e.g. supplying a
|
| 1351 | non-existent URL to the appender). This feature can be used to handle
|
| 1352 | AjaxAppender-specific errors.
|
| 1353 | </p>
|
| 1354 | <p>
|
| 1355 | A single parameter, <code>message</code>, is passed to the callback function.
|
| 1356 | This is the error-specific message that caused the failure.
|
| 1357 | </p>
|
| 1358 | </div>
|
| 1359 | </li>
|
| 1360 | <li class="method">
|
| 1361 | <div class="name">setSessionId</div>
|
| 1362 | <div class="methodsignature"><code>void <strong>setSessionId</strong>(String <em>sessionId</em>)</code></div>
|
| 1363 | <div class="summary">
|
| 1364 | Sets the session id sent to the server each time a request is made.
|
| 1365 | </div>
|
| 1366 | </li>
|
| 1367 | <li class="method">
|
| 1368 | <div class="name">getSessionId</div>
|
| 1369 | <div class="methodsignature"><code>String <strong>getSessionId</strong>()</code></div>
|
| 1370 | <div class="summary">
|
| 1371 | Returns the session id sent to the server each time a request is made.
|
| 1372 | </div>
|
| 1373 | </li>
|
| 1374 | <li class="method">
|
| 1375 | <div class="name">addHeader</div>
|
| 1376 | <div class="methodsignature"><code>void <strong>addHeader</strong>(String <em>name</em>,
|
| 1377 | String <em>value</em>)</code></div>
|
| 1378 | <div class="summary">
|
| 1379 | <p>
|
| 1380 | Adds an HTTP header that is sent with each request.
|
| 1381 | </p>
|
| 1382 | <p>
|
| 1383 | <strong>Since: 1.4.3</strong>
|
| 1384 | </p>
|
| 1385 | </div>
|
| 1386 | </li>
|
| 1387 | <li class="method">
|
| 1388 | <div class="name">getHeaders</div>
|
| 1389 | <div class="methodsignature"><code>Array <strong>getHeaders</strong>()</code></div>
|
| 1390 | <div class="summary">
|
| 1391 | Returns an array of the additional headers that are sent with each HTTP request.
|
| 1392 | Each array item is an object with properties <code>name</code> and
|
| 1393 | <code>value</code>.
|
| 1394 | <p>
|
| 1395 | <strong>Since: 1.4.3</strong>
|
| 1396 | </p>
|
| 1397 | </div>
|
| 1398 | </li>
|
| 1399 | <li class="method">
|
| 1400 | <div class="name">sendAll</div>
|
| 1401 | <div class="methodsignature"><code>void <strong>sendAll</strong>()</code></div>
|
| 1402 | <div class="summary">
|
| 1403 | Sends all log messages in the queue. If log messages are batched then only completed
|
| 1404 | batches are sent.
|
| 1405 | </div>
|
| 1406 | </li>
|
| 1407 | </ul>
|
| 1408 | <p class="linktotop">
|
| 1409 | <a href="#container">Top</a>
|
| 1410 | </p>
|
| 1411 | </div>
|
| 1412 | <div id="popupappender">
|
| 1413 | <h3>PopUpAppender</h3>
|
| 1414 | <p class="editions">Editions: <strong>Standard</strong></p>
|
| 1415 | <p>
|
| 1416 | Logs messages to a pop-up console window (note: you will need to disable pop-up
|
| 1417 | blockers to use it). The pop-up displays a list of all log messages, and has
|
| 1418 | the following features:
|
| 1419 | </p>
|
| 1420 | <ul>
|
| 1421 | <li>log messages are colour-coded by severity;</li>
|
| 1422 | <li>log messages are displayed in a monospace font to allow easy readability;</li>
|
| 1423 | <li>switchable wrap mode to allow wrapping of long lines</li>
|
| 1424 | <li>all whitespace in log messages is honoured (except in wrap mode);</li>
|
| 1425 | <li>filters to show and hide messages of a particular level;</li>
|
| 1426 | <li>
|
| 1427 | search facility that allows searching of log messages as you type, with the
|
| 1428 | following features:
|
| 1429 | <ul>
|
| 1430 | <li>supports regular expressions;</li>
|
| 1431 | <li>case sensitive or insensitive matching;</li>
|
| 1432 | <li>buttons to navigate through all the matches;</li>
|
| 1433 | <li>switch to highlight all matches;</li>
|
| 1434 | <li>switch to filter out all log messages that contain no matches;</li>
|
| 1435 | <li>switch to enable or disable the search;</li>
|
| 1436 | <li>search is dynamically applied to every log message as it is added to the console.</li>
|
| 1437 | </ul>
|
| 1438 | </li>
|
| 1439 | <li>switch to toggle between logging from the top down and from the bottom up;</li>
|
| 1440 | <li>switch to turn automatic scrolling when a new message is logged on and off;</li>
|
| 1441 | <li>switch to turn off all logging to the pop-up (useful if a timer is generating unwanted log messages);</li>
|
| 1442 | <li>optional configurable limit to the number of log message that are displayed. If
|
| 1443 | set and this limit is reached, each new log message will cause the oldest one to
|
| 1444 | be discarded;</li>
|
| 1445 | <li>grouped log messages. Groups may be nested and each has a button to show or hide the log messages in that group;</li>
|
| 1446 | <li>clear button to allow user to delete all current log messages.</li>
|
| 1447 | <li>
|
| 1448 | command prompt with up/down arrow history. Command line functions may be added
|
| 1449 | to the appender. Several command line functions are built in:
|
| 1450 | <ul class="propertieslist">
|
| 1451 | <li class="method">
|
| 1452 | <div class="methodsignature"><code><strong>$</strong>(String <em>id</em>)</code></div>
|
| 1453 | <div class="summary">
|
| 1454 | Prints a string representation of a single element with the id supplied.
|
| 1455 | </div>
|
| 1456 | </li>
|
| 1457 | <li class="method">
|
| 1458 | <div class="methodsignature"><code><strong>dir</strong>(Object <em>obj</em>)</code></div>
|
| 1459 | <div class="summary">
|
| 1460 | Prints a list of a properties of the object supplied.
|
| 1461 | </div>
|
| 1462 | </li>
|
| 1463 | <li class="method">
|
| 1464 | <div class="methodsignature"><code><strong>dirxml</strong>(HTMLElement <em>el</em>)</code></div>
|
| 1465 | <div class="summary">
|
| 1466 | Prints the XML source code of an HTML or XML element
|
| 1467 | </div>
|
| 1468 | </li>
|
| 1469 | <li class="method">
|
| 1470 | <div class="methodsignature"><code><strong>cd</strong>(Object <em>win</em>)</code></div>
|
| 1471 | <div class="summary">
|
| 1472 | Changes the scope of execution of commands to the named frame or window (either a
|
| 1473 | window/frame name or a reference to a window object may be supplied).
|
| 1474 | </div>
|
| 1475 | </li>
|
| 1476 | <li class="method">
|
| 1477 | <div class="methodsignature"><code><strong>clear</strong>()</code></div>
|
| 1478 | <div class="summary">
|
| 1479 | Clears the console.
|
| 1480 | </div>
|
| 1481 | </li>
|
| 1482 | <li class="method">
|
| 1483 | <div class="methodsignature"><code><strong>keys</strong>(Object <em>obj</em>)</code></div>
|
| 1484 | <div class="summary">
|
| 1485 | Prints a list of the names of all properties of the object supplied.
|
| 1486 | </div>
|
| 1487 | </li>
|
| 1488 | <li class="method">
|
| 1489 | <div class="methodsignature"><code><strong>values</strong>(Object <em>obj</em>)</code></div>
|
| 1490 | <div class="summary">
|
| 1491 | Prints a list of the values of all properties of the object supplied.
|
| 1492 | </div>
|
| 1493 | </li>
|
| 1494 | <li class="method">
|
| 1495 | <div class="methodsignature"><code><strong>expansionDepth</strong>(Number <em>depth</em>)</code></div>
|
| 1496 | <div class="summary">
|
| 1497 | Sets the number of levels of expansion of objects that are displayed by
|
| 1498 | the command line. The default value is 1.
|
| 1499 | </div>
|
| 1500 | </li>
|
| 1501 | </ul>
|
| 1502 | </li>
|
| 1503 | </ul>
|
| 1504 | <p><strong>Notes</strong></p>
|
| 1505 | <ul>
|
| 1506 | <li>
|
| 1507 | <p>
|
| 1508 | The default layout for this appender is <code><a href="#patternlayout">PatternLayout</a></code>
|
| 1509 | with pattern string
|
| 1510 | </p>
|
| 1511 | <p>
|
| 1512 | <code>%d{HH:mm:ss} %-5p - %m{1}%n</code>
|
| 1513 | </p>
|
| 1514 | </li>
|
| 1515 | </ul>
|
| 1516 | <h4>Constructor</h4>
|
| 1517 | <ul class="propertieslist">
|
| 1518 | <li class="method">
|
| 1519 | <div class="name">PopUpAppender</div>
|
| 1520 | <div class="methodsignature">
|
| 1521 | <code><strong>PopUpAppender</strong>([Boolean <em>lazyInit</em>,
|
| 1522 | Boolean <em>initiallyMinimized</em>, Boolean <em>useDocumentWrite</em>,
|
| 1523 | Number <em>width</em>, Number <em>height</em>])</code>
|
| 1524 | </div>
|
| 1525 | <div class="paramsheading">Parameters:</div>
|
| 1526 | <ul class="params">
|
| 1527 | <li class="param">
|
| 1528 | <code class="paramname">lazyInit</code>
|
| 1529 | [<em>optional</em>]
|
| 1530 | <div>
|
| 1531 | Set this to <code>true</code> to open the pop-up only when the first log
|
| 1532 | message reaches the appender. Otherwise, the pop-up window opens as soon as the
|
| 1533 | appender is created. If not specified, defaults to <code>false</code>.
|
| 1534 | </div>
|
| 1535 | </li>
|
| 1536 | <li class="param">
|
| 1537 | <code class="paramname">initiallyMinimized</code>
|
| 1538 | [<em>optional</em>]
|
| 1539 | <div>
|
| 1540 | <p>
|
| 1541 | Whether the console window should start off hidden / minimized.
|
| 1542 | If not specified, defaults to <code>false</code>.
|
| 1543 | </p>
|
| 1544 | </div>
|
| 1545 | </li>
|
| 1546 | <li class="param">
|
| 1547 | <code class="paramname">useDocumentWrite</code>
|
| 1548 | [<em>optional</em>]
|
| 1549 | <div>
|
| 1550 | <p>
|
| 1551 | Specifies how the console window is created. By default, the console window is
|
| 1552 | created dynamically using <code>document</code>'s <code>write</code> method. This has the
|
| 1553 | advantage of keeping all the code in one single JavaScript file. However, if your
|
| 1554 | page sets <code>document.domain</code> then the browser prevents script access to
|
| 1555 | a window unless it too has the same value set for <code>document.domain</code>. To
|
| 1556 | get round this issue, you can set <code>useDocumentWrite</code> to <code>false</code>
|
| 1557 | and log4javascript will instead use the external HTML file <code>console.html</code>
|
| 1558 | (or <code>console_uncompressed.html</code> if you're using an uncompressed version of
|
| 1559 | log4javascript.js), which must be placed in the same directory as your log4javascript.js file.
|
| 1560 | </p>
|
| 1561 | <p>
|
| 1562 | Note that if <code>useDocumentWrite</code> is set to <code>true</code>, the old pop-up
|
| 1563 | window will always be closed and a new one created whenever the page is refreshed, even
|
| 1564 | if <code>setUseOldPopUp(true)</code> has been called.
|
| 1565 | </p>
|
| 1566 | <p>
|
| 1567 | In general it's simpler to use the <code>document.write</code> method, so unless your
|
| 1568 | page needs to set <code>document.domain</code>, <code>useDocumentWrite</code> should
|
| 1569 | be set to <code>true</code>.
|
| 1570 | </p>
|
| 1571 | <p>
|
| 1572 | If not specified, defaults to <code>true</code>.
|
| 1573 | </p>
|
| 1574 | </div>
|
| 1575 | </li>
|
| 1576 | <li class="param">
|
| 1577 | <code class="paramname">width</code>
|
| 1578 | [<em>optional</em>]
|
| 1579 | <div>
|
| 1580 | The outer width in pixels of the pop-up window. If not specified,
|
| 1581 | defaults to <code>600</code>.
|
| 1582 | </div>
|
| 1583 | </li>
|
| 1584 | <li class="param">
|
| 1585 | <code class="paramname">height</code>
|
| 1586 | [<em>optional</em>]
|
| 1587 | <div>
|
| 1588 | The outer height in pixels of the pop-up window. If not specified,
|
| 1589 | defaults to <code>400</code>.
|
| 1590 | </div>
|
| 1591 | </li>
|
| 1592 | </ul>
|
| 1593 | </li>
|
| 1594 | </ul>
|
| 1595 | <h4>Methods</h4>
|
| 1596 | <ul class="propertieslist">
|
| 1597 | <li class="method">
|
| 1598 | <div class="name">isInitiallyMinimized</div>
|
| 1599 | <div class="methodsignature"><code>Boolean <strong>isInitiallyMinimized</strong>()</code></div>
|
| 1600 | <div class="summary">
|
| 1601 | Returns whether the console window starts off hidden / minimized.
|
| 1602 | </div>
|
| 1603 | </li>
|
| 1604 | <li class="method">
|
| 1605 | <div class="name">setInitiallyMinimized</div>
|
| 1606 | <div class="methodsignature"><code>void <strong>setInitiallyMinimized</strong>(Boolean <em>initiallyMinimized</em>)</code></div>
|
| 1607 | <div class="summary">
|
| 1608 | [<em>not available after initialization</em>]
|
| 1609 | <br />
|
| 1610 | Sets whether the console window should start off hidden / minimized.
|
| 1611 | </div>
|
| 1612 | </li>
|
| 1613 | <li class="method">
|
| 1614 | <div class="name">isFocusPopUp</div>
|
| 1615 | <div class="methodsignature"><code>Boolean <strong>isFocusPopUp</strong>()</code></div>
|
| 1616 | <div class="summary">
|
| 1617 | Returns whether the pop-up window is focussed (i.e. brought it to the front)
|
| 1618 | when a new log message is added. Default value is <code>false</code>.
|
| 1619 | </div>
|
| 1620 | </li>
|
| 1621 | <li class="method">
|
| 1622 | <div class="name">setFocusPopUp</div>
|
| 1623 | <div class="methodsignature"><code>void <strong>setFocusPopUp</strong>(Boolean <em>focusPopUp</em>)</code></div>
|
| 1624 | <div class="summary">
|
| 1625 | Sets whether to focus the pop-up window (i.e. bring it to the front)
|
| 1626 | when a new log message is added.
|
| 1627 | </div>
|
| 1628 | </li>
|
| 1629 | <li class="method">
|
| 1630 | <div class="name">isUseOldPopUp</div>
|
| 1631 | <div class="methodsignature"><code>Boolean <strong>isUseOldPopUp</strong>()</code></div>
|
| 1632 | <div class="summary">
|
| 1633 | <p>
|
| 1634 | Returns whether the same pop-up window is used if the main page is
|
| 1635 | reloaded. If set to <code>true</code>, when the page is reloaded
|
| 1636 | a line is drawn in the pop-up and subsequent log messages are added
|
| 1637 | to the same pop-up. Otherwise, a new pop-up window is created that
|
| 1638 | replaces the original pop-up. If not specified, defaults to
|
| 1639 | <code>true</code>.
|
| 1640 | </p>
|
| 1641 | <p><strong>Notes</strong></p>
|
| 1642 | <ul>
|
| 1643 | <li>
|
| 1644 | In Internet Explorer 5, the browser prevents this from working
|
| 1645 | properly, so a new pop-up window is always created when the main
|
| 1646 | page reloads. Also, the original pop-up does not get closed.
|
| 1647 | </li>
|
| 1648 | </ul>
|
| 1649 | </div>
|
| 1650 | </li>
|
| 1651 | <li class="method">
|
| 1652 | <div class="name">setUseOldPopUp</div>
|
| 1653 | <div class="methodsignature"><code>void <strong>setUseOldPopUp</strong>(Boolean <em>useOldPopUp</em>)</code></div>
|
| 1654 | <div class="summary">
|
| 1655 | [<em>not available after initialization</em>]
|
| 1656 | <br />
|
| 1657 | Sets whether to use the same pop-up window if the main page is reloaded.
|
| 1658 | See <code>isUseOldPopUp</code> above for details.
|
| 1659 | </div>
|
| 1660 | </li>
|
| 1661 | <li class="method">
|
| 1662 | <div class="name">isComplainAboutPopUpBlocking</div>
|
| 1663 | <div class="methodsignature"><code>Boolean <strong>isComplainAboutPopUpBlocking</strong>()</code></div>
|
| 1664 | <div class="summary">
|
| 1665 | Returns whether an alert is shown to the user when the pop-up window
|
| 1666 | cannot be created as a result of a pop-up blocker. Default value is <code>true</code>.
|
| 1667 | </div>
|
| 1668 | </li>
|
| 1669 | <li class="method">
|
| 1670 | <div class="name">setComplainAboutPopUpBlocking</div>
|
| 1671 | <div class="methodsignature"><code>void <strong>setComplainAboutPopUpBlocking</strong>(Boolean <em>complainAboutPopUpBlocking</em>)</code></div>
|
| 1672 | <div class="summary">
|
| 1673 | [<em>not available after initialization</em>]
|
| 1674 | <br />
|
| 1675 | Sets whether to announce to show an alert to the user when the pop-up window
|
| 1676 | cannot be created as a result of a pop-up blocker.
|
| 1677 | </div>
|
| 1678 | </li>
|
| 1679 | <li class="method">
|
| 1680 | <div class="name">isNewestMessageAtTop</div>
|
| 1681 | <div class="methodsignature"><code>Boolean <strong>isNewestMessageAtTop</strong>()</code></div>
|
| 1682 | <div class="summary">
|
| 1683 | Returns whether new log messages are displayed at the top of the pop-up window.
|
| 1684 | Default value is <code>false</code> (i.e. log messages are appended to the bottom of the window).
|
| 1685 | </div>
|
| 1686 | </li>
|
| 1687 | <li class="method">
|
| 1688 | <div class="name">setNewestMessageAtTop</div>
|
| 1689 | <div class="methodsignature"><code>void <strong>setNewestMessageAtTop</strong>(Boolean <em>newestMessageAtTop</em>)</code></div>
|
| 1690 | <div class="summary">
|
| 1691 | Sets whether to display new log messages at the top inside the pop-up window.
|
| 1692 | </div>
|
| 1693 | </li>
|
| 1694 | <li class="method">
|
| 1695 | <div class="name">isScrollToLatestMessage</div>
|
| 1696 | <div class="methodsignature"><code>Boolean <strong>isScrollToLatestMessage</strong>()</code></div>
|
| 1697 | <div class="summary">
|
| 1698 | Returns whether the pop-up window scrolls to display the latest log message when a new message
|
| 1699 | is logged. Default value is <code>true</code>.
|
| 1700 | </div>
|
| 1701 | </li>
|
| 1702 | <li class="method">
|
| 1703 | <div class="name">setScrollToLatestMessage</div>
|
| 1704 | <div class="methodsignature"><code>void <strong>setScrollToLatestMessage</strong>(Boolean <em>scrollToLatestMessage</em>)</code></div>
|
| 1705 | <div class="summary">
|
| 1706 | Sets whether to scroll the pop-up window to display the latest log message when a new message
|
| 1707 | is logged.
|
| 1708 | </div>
|
| 1709 | </li>
|
| 1710 | <li class="method">
|
| 1711 | <div class="name">isReopenWhenClosed</div>
|
| 1712 | <div class="methodsignature"><code>Boolean <strong>isReopenWhenClosed</strong>()</code></div>
|
| 1713 | <div class="summary">
|
| 1714 | Returns whether the pop-up window reopens automatically after being closed when a new log message is logged.
|
| 1715 | Default value is <code>false</code>.
|
| 1716 | </div>
|
| 1717 | </li>
|
| 1718 | <li class="method">
|
| 1719 | <div class="name">setReopenWhenClosed</div>
|
| 1720 | <div class="methodsignature"><code>void <strong>setReopenWhenClosed</strong>(Boolean <em>reopenWhenClosed</em>)</code></div>
|
| 1721 | <div class="summary">
|
| 1722 | Sets whether to reopen the pop-up window automatically after being closed when a new log message is logged.
|
| 1723 | </div>
|
| 1724 | </li>
|
| 1725 | <li class="method">
|
| 1726 | <div class="name">getWidth</div>
|
| 1727 | <div class="methodsignature"><code>Number <strong>getWidth</strong>()</code></div>
|
| 1728 | <div class="summary">
|
| 1729 | Returns the outer width in pixels of the pop-up window.
|
| 1730 | </div>
|
| 1731 | </li>
|
| 1732 | <li class="method">
|
| 1733 | <div class="name">setWidth</div>
|
| 1734 | <div class="methodsignature"><code>void <strong>setWidth</strong>(Number <em>width</em>)</code></div>
|
| 1735 | <div class="summary">
|
| 1736 | [<em>not available after initialization</em>]
|
| 1737 | <br />
|
| 1738 | Sets the outer width in pixels of the pop-up window.
|
| 1739 | </div>
|
| 1740 | </li>
|
| 1741 | <li class="method">
|
| 1742 | <div class="name">getHeight</div>
|
| 1743 | <div class="methodsignature"><code>Number <strong>getHeight</strong>()</code></div>
|
| 1744 | <div class="summary">
|
| 1745 | [<em>not available after initialization</em>]
|
| 1746 | <br />
|
| 1747 | Returns the outer height in pixels of the pop-up window.
|
| 1748 | </div>
|
| 1749 | </li>
|
| 1750 | <li class="method">
|
| 1751 | <div class="name">setHeight</div>
|
| 1752 | <div class="methodsignature"><code>void <strong>setHeight</strong>(Number <em>height</em>)</code></div>
|
| 1753 | <div class="summary">
|
| 1754 | Sets the outer height in pixels of the pop-up window.
|
| 1755 | </div>
|
| 1756 | </li>
|
| 1757 | <li class="method">
|
| 1758 | <div class="name">getMaxMessages</div>
|
| 1759 | <div class="methodsignature"><code>Number <strong>getMaxMessages</strong>()</code></div>
|
| 1760 | <div class="summary">
|
| 1761 | Returns the largest number of log messages that are displayed and stored
|
| 1762 | by the the console. Once reached, a new log message wil cause the
|
| 1763 | oldest message to be discarded. Default value is <code>null</code>, which means no
|
| 1764 | limit is applied.
|
| 1765 | </div>
|
| 1766 | </li>
|
| 1767 | <li class="method">
|
| 1768 | <div class="name">setMaxMessages</div>
|
| 1769 | <div class="methodsignature"><code>void <strong>setMaxMessages</strong>(Number <em>maxMessages</em>)</code></div>
|
| 1770 | <div class="summary">
|
| 1771 | [<em>not available after initialization</em>]
|
| 1772 | <br />
|
| 1773 | Sets the largest number of messages displayed and stored by the console window. Set
|
| 1774 | this to <code>null</code> to make this number unlimited.
|
| 1775 | </div>
|
| 1776 | </li>
|
| 1777 | <li class="method">
|
| 1778 | <div class="name">isShowCommandLine</div>
|
| 1779 | <div class="methodsignature"><code>Boolean <strong>isShowCommandLine</strong>()</code></div>
|
| 1780 | <div class="summary">
|
| 1781 | Returns whether the console includes a command line.
|
| 1782 | Default value is <code>true</code>.
|
| 1783 | </div>
|
| 1784 | </li>
|
| 1785 | <li class="method">
|
| 1786 | <div class="name">setShowCommandLine</div>
|
| 1787 | <div class="methodsignature"><code>void <strong>setShowCommandLine</strong>(Boolean <em>showCommandLine</em>)</code></div>
|
| 1788 | <div class="summary">
|
| 1789 | Sets whether the console includes a command line.
|
| 1790 | </div>
|
| 1791 | </li>
|
| 1792 | <li class="method">
|
| 1793 | <div class="name">getCommandLineObjectExpansionDepth</div>
|
| 1794 | <div class="methodsignature"><code>Number <strong>getCommandLineObjectExpansionDepth</strong>()</code></div>
|
| 1795 | <div class="summary">
|
| 1796 | Returns the number of levels to expand when an object value is logged to the console.
|
| 1797 | Each property of an object above this threshold will be expanded if it is itself an object
|
| 1798 | or array, otherwise its string representation will be displayed. Default value is 1 (i.e.
|
| 1799 | the properties of the object logged will be displayed in their string representation but
|
| 1800 | not expanded).
|
| 1801 | </div>
|
| 1802 | </li>
|
| 1803 | <li class="method">
|
| 1804 | <div class="name">setCommandLineObjectExpansionDepth:</div>
|
| 1805 | <div class="methodsignature"><code>void <strong>setCommandLineObjectExpansionDepth</strong>(Number <em>expansionDepth</em>)</code></div>
|
| 1806 | <div class="summary">
|
| 1807 | Sets the number of levels to expand when an object value is logged to the console.
|
| 1808 | </div>
|
| 1809 | </li>
|
| 1810 | <li class="method">
|
| 1811 | <div class="name">getCommandWindow</div>
|
| 1812 | <div class="methodsignature"><code>Window <strong>getCommandWindow</strong>()</code></div>
|
| 1813 | <div class="summary">
|
| 1814 | Returns a reference to the window in which commands typed into the command line
|
| 1815 | are currently being executed.
|
| 1816 | </div>
|
| 1817 | </li>
|
| 1818 | <li class="method">
|
| 1819 | <div class="name">setCommandWindow</div>
|
| 1820 | <div class="methodsignature"><code>void <strong>setCommandWindow</strong>(Window <em>commandWindow</em>)</code></div>
|
| 1821 | <div class="summary">
|
| 1822 | Sets the window in which commands typed into the command line are executed.
|
| 1823 | </div>
|
| 1824 | </li>
|
| 1825 | <li class="method">
|
| 1826 | <div class="name">getCommandLayout</div>
|
| 1827 | <div class="methodsignature"><code>Number <strong>getCommandLayout</strong>()</code></div>
|
| 1828 | <div class="summary">
|
| 1829 | Returns the layout used to format the output for commands typed into the command line.
|
| 1830 | The default value is a <code><a href="#patternlayout">PatternLayout</a></code> with
|
| 1831 | pattern string <code>%m</code>
|
| 1832 | </div>
|
| 1833 | </li>
|
| 1834 | <li class="method">
|
| 1835 | <div class="name">setCommandLayout</div>
|
| 1836 | <div class="methodsignature"><code>void <strong>setCommandLayout</strong>(Layout <em>commandLayout</em>)</code></div>
|
| 1837 | <div class="summary">
|
| 1838 | Sets the layout used to format the output for commands typed into the command line.
|
| 1839 | </div>
|
| 1840 | </li>
|
| 1841 | <li class="method">
|
| 1842 | <div class="name">clear</div>
|
| 1843 | <div class="methodsignature"><code>void <strong>clear</strong>()</code></div>
|
| 1844 | <div class="summary">
|
| 1845 | Clears all messages from the console window.
|
| 1846 | </div>
|
| 1847 | </li>
|
| 1848 | <li class="method">
|
| 1849 | <div class="name">close</div>
|
| 1850 | <div class="methodsignature"><code>void <strong>close</strong>()</code></div>
|
| 1851 | <div class="summary">
|
| 1852 | Closes the pop-up window.
|
| 1853 | </div>
|
| 1854 | </li>
|
| 1855 | <li class="method">
|
| 1856 | <div class="name">show</div>
|
| 1857 | <div class="methodsignature"><code>void <strong>show</strong>()</code></div>
|
| 1858 | <div class="summary">
|
| 1859 | Opens the pop-up window, if not already open.
|
| 1860 | </div>
|
| 1861 | </li>
|
| 1862 | <li class="method">
|
| 1863 | <div class="name">hide</div>
|
| 1864 | <div class="methodsignature"><code>void <strong>hide</strong>()</code></div>
|
| 1865 | <div class="summary">
|
| 1866 | Closes the pop-up window.
|
| 1867 | </div>
|
| 1868 | </li>
|
| 1869 | <li class="method">
|
| 1870 | <div class="name">focus</div>
|
| 1871 | <div class="methodsignature"><code>void <strong>focus</strong>()</code></div>
|
| 1872 | <div class="summary">
|
| 1873 | Brings the console window to the top and gives it the focus.
|
| 1874 | </div>
|
| 1875 | </li>
|
| 1876 | <li class="method">
|
| 1877 | <div class="name">focusCommandLine</div>
|
| 1878 | <div class="methodsignature"><code>void <strong>focusCommandLine</strong>()</code></div>
|
| 1879 | <div class="summary">
|
| 1880 | Brings the console window to the top and gives the focus to the command line.
|
| 1881 | </div>
|
| 1882 | </li>
|
| 1883 | <li class="method">
|
| 1884 | <div class="name">focusSearch</div>
|
| 1885 | <div class="methodsignature"><code>void <strong>focusSearch</strong>()</code></div>
|
| 1886 | <div class="summary">
|
| 1887 | Brings the console window to the top and gives the focus to the search box.
|
| 1888 | </div>
|
| 1889 | </li>
|
| 1890 | <li class="method">
|
| 1891 | <div class="name">evalCommandAndAppend</div>
|
| 1892 | <div class="methodsignature"><code>void <strong>evalCommandAndAppend</strong>(String <em>expr</em>)</code></div>
|
| 1893 | <div class="summary">
|
| 1894 | Evaluates the expression and appends the result to the console.
|
| 1895 | </div>
|
| 1896 | </li>
|
| 1897 | <li class="method">
|
| 1898 | <div class="name">addCommandLineFunction</div>
|
| 1899 | <div class="methodsignature"><code>void <strong>addCommandLineFunction</strong>(String <em>functionName</em>, Function <em>commandLineFunction</em>)</code></div>
|
| 1900 | <div class="summary">
|
| 1901 | <p>
|
| 1902 | Adds a function with the name specified to the list of functions available on the command line.
|
| 1903 | This feature may be used to add custom functions to the command line.
|
| 1904 | </p>
|
| 1905 | <p>
|
| 1906 | When you call the function on the command line, <code>commandLineFunction</code> is executed with the
|
| 1907 | following three parameters:
|
| 1908 | </p>
|
| 1909 | <ul>
|
| 1910 | <li><em>appender</em>. A reference to the appender in which the command was executed;</li>
|
| 1911 | <li><em>args</em>.
|
| 1912 | An array-like list of parameters passed into the function on the command line
|
| 1913 | (actually a reference to the <code>arguments</code> object representing the parameters passed
|
| 1914 | into the function by the user);</li>
|
| 1915 | <li><em>returnValue</em>. This is an object with two properties that allow the function to control
|
| 1916 | how the result is displayed:
|
| 1917 | <ul>
|
| 1918 | <li><em>appendResult</em>. A boolean value that determines whether the returned value from this
|
| 1919 | function is appended to the console. The default value is <code>true</code>;</li>
|
| 1920 | <li><em>isError</em>. A boolean value that specifies whether the output of this function
|
| 1921 | should be displayed as an error. The default value is <code>false</code>.</li>
|
| 1922 | </ul>
|
| 1923 | </li>
|
| 1924 | </ul>
|
| 1925 | <p>
|
| 1926 | The value returned by the function is formatted by the command layout and appended to the console.
|
| 1927 | </p>
|
| 1928 | </div>
|
| 1929 | </li>
|
| 1930 | </ul>
|
| 1931 | <p class="linktotop">
|
| 1932 | <a href="#container">Top</a>
|
| 1933 | </p>
|
| 1934 | </div>
|
| 1935 | <div id="inpageappender">
|
| 1936 | <h3>InPageAppender</h3>
|
| 1937 | <p class="editions">Editions: <strong>Standard</strong></p>
|
| 1938 | <p>
|
| 1939 | Logs messages to a console window in the page. The console is identical
|
| 1940 | to that used by the <code><a href="#popupappender">PopUpAppender</a></code>, except
|
| 1941 | for the absence of a 'Close' button.
|
| 1942 | </p>
|
| 1943 | <p><strong>Notes</strong></p>
|
| 1944 | <ul>
|
| 1945 | <li>
|
| 1946 | Prior to log4javascript 1.3, InPageAppender was known as InlineAppender.
|
| 1947 | For the sake of backwards compatibility, InlineAppender is still included in
|
| 1948 | 1.3 and later as an alias for InPageAppender.
|
| 1949 | </li>
|
| 1950 | <li>
|
| 1951 | <p>
|
| 1952 | The default layout for this appender is <code><a href="#patternlayout">PatternLayout</a></code>
|
| 1953 | with pattern string
|
| 1954 | </p>
|
| 1955 | <p>
|
| 1956 | <code>%d{HH:mm:ss} %-5p - %m{1}%n</code>
|
| 1957 | </p>
|
| 1958 | </li>
|
| 1959 | </ul>
|
| 1960 | <h4>Constructor</h4>
|
| 1961 | <ul class="propertieslist">
|
| 1962 | <li class="method">
|
| 1963 | <div class="name">InPageAppender</div>
|
| 1964 | <div class="methodsignature">
|
| 1965 | <code><strong>InPageAppender</strong>(HTMLElement <em>container</em>[,
|
| 1966 | Boolean <em>lazyInit</em>, Boolean <em>initiallyMinimized</em>,
|
| 1967 | Boolean <em>useDocumentWrite</em>, String <em>width</em>, String <em>height</em>])</code>
|
| 1968 | </div>
|
| 1969 | <div class="paramsheading">Parameters:</div>
|
| 1970 | <ul class="params">
|
| 1971 | <li class="param">
|
| 1972 | <code class="paramname">container</code>
|
| 1973 | <div>
|
| 1974 | The container element for the console window. This should be an HTML element.
|
| 1975 | </div>
|
| 1976 | </li>
|
| 1977 | <li class="param">
|
| 1978 | <code class="paramname">lazyInit</code>
|
| 1979 | [<em>optional</em>]
|
| 1980 | <div>
|
| 1981 | Set this to <code>true</code> to create the console only when the first log
|
| 1982 | message reaches the appender. Otherwise, the console is initialized as soon as the
|
| 1983 | appender is created. If not specified, defaults to <code>true</code>.
|
| 1984 | </div>
|
| 1985 | </li>
|
| 1986 | <li class="param">
|
| 1987 | <code class="paramname">initiallyMinimized</code>
|
| 1988 | [<em>optional</em>]
|
| 1989 | <div>
|
| 1990 | <p>
|
| 1991 | Whether the console window should start off hidden / minimized.
|
| 1992 | If not specified, defaults to <code>false</code>.
|
| 1993 | </p>
|
| 1994 | <p><strong>Notes</strong></p>
|
| 1995 | <ul>
|
| 1996 | <li>
|
| 1997 | In Safari (and possibly other browsers) hiding an <code>iframe</code>
|
| 1998 | resets its document, thus destroying the console window.
|
| 1999 | </li>
|
| 2000 | </ul>
|
| 2001 | </div>
|
| 2002 | </li>
|
| 2003 | <li class="param">
|
| 2004 | <code class="paramname">useDocumentWrite</code>
|
| 2005 | [<em>optional</em>]
|
| 2006 | <div>
|
| 2007 | <p>
|
| 2008 | Specifies how the console window is created. By default, the console window is
|
| 2009 | created dynamically using <code>document</code>'s <code>write</code> method. This has the
|
| 2010 | advantage of keeping all the code in one single JavaScript file. However, if your
|
| 2011 | page sets <code>document.domain</code> then the browser prevents script access to
|
| 2012 | a window unless it too has the same value set for <code>document.domain</code>. To
|
| 2013 | get round this issue, you can set <code>useDocumentWrite</code> to <code>false</code>
|
| 2014 | and log4javascript will instead use the external HTML file <code>console.html</code>
|
| 2015 | (or <code>console_uncompressed.html</code> if you're using an uncompressed version of
|
| 2016 | log4javascript.js), which must be placed in the same directory as your log4javascript.js file.
|
| 2017 | </p>
|
| 2018 | <p>
|
| 2019 | In general it's simpler to use the <code>document.write</code> method, so unless your
|
| 2020 | page needs to set <code>document.domain</code>, <code>useDocumentWrite</code> should
|
| 2021 | be set to <code>true</code>.
|
| 2022 | </p>
|
| 2023 | <p>
|
| 2024 | If not specified, defaults to <code>true</code>.
|
| 2025 | </p>
|
| 2026 | </div>
|
| 2027 | </li>
|
| 2028 | <li class="param">
|
| 2029 | <code class="paramname">width</code>
|
| 2030 | [<em>optional</em>]
|
| 2031 | <div>
|
| 2032 | The width of the console window. Any valid CSS length may be used. If not
|
| 2033 | specified, defaults to <code>100%</code>.
|
| 2034 | </div>
|
| 2035 | </li>
|
| 2036 | <li class="param">
|
| 2037 | <code class="paramname">height</code>
|
| 2038 | [<em>optional</em>]
|
| 2039 | <div>
|
| 2040 | The height of the console window. Any valid CSS length may be used. If not
|
| 2041 | specified, defaults to <code>250px</code>.
|
| 2042 | </div>
|
| 2043 | </li>
|
| 2044 | </ul>
|
| 2045 | </li>
|
| 2046 | </ul>
|
| 2047 | <h4>Methods</h4>
|
| 2048 | <ul class="propertieslist">
|
| 2049 | <li class="method">
|
| 2050 | <div class="name">addCssProperty</div>
|
| 2051 | <div class="methodsignature"><code>void <strong>addCssProperty</strong>(String <em>name</em>, String <em>value</em>)</code></div>
|
| 2052 | <div class="summary">
|
| 2053 | Sets a CSS style property on the HTML element containing the console iframe.
|
| 2054 | </div>
|
| 2055 | </li>
|
| 2056 | <li class="method">
|
| 2057 | <div class="name">isVisible</div>
|
| 2058 | <div class="methodsignature"><code>Boolean <strong>isVisible</strong>()</code></div>
|
| 2059 | <div class="summary">
|
| 2060 | Returns whether the console window is currently visible.
|
| 2061 | </div>
|
| 2062 | </li>
|
| 2063 | <li class="method">
|
| 2064 | <div class="name">isInitiallyMinimized</div>
|
| 2065 | <div class="methodsignature"><code>Boolean <strong>isInitiallyMinimized</strong>()</code></div>
|
| 2066 | <div class="summary">
|
| 2067 | Returns whether the console window starts off hidden / minimized.
|
| 2068 | </div>
|
| 2069 | </li>
|
| 2070 | <li class="method">
|
| 2071 | <div class="name">setInitiallyMinimized</div>
|
| 2072 | <div class="methodsignature"><code>void <strong>setInitiallyMinimized</strong>(Boolean <em>initiallyMinimized</em>)</code></div>
|
| 2073 | <div class="summary">
|
| 2074 | [<em>not available after initialization</em>]
|
| 2075 | <br />
|
| 2076 | Sets whether the console window should start off hidden / minimized.
|
| 2077 | </div>
|
| 2078 | </li>
|
| 2079 | <li class="method">
|
| 2080 | <div class="name">isNewestMessageAtTop</div>
|
| 2081 | <div class="methodsignature"><code>Boolean <strong>isNewestMessageAtTop</strong>()</code></div>
|
| 2082 | <div class="summary">
|
| 2083 | Returns whether new log messages are displayed at the top of the console window.
|
| 2084 | </div>
|
| 2085 | </li>
|
| 2086 | <li class="method">
|
| 2087 | <div class="name">setNewestMessageAtTop</div>
|
| 2088 | <div class="methodsignature"><code>void <strong>setNewestMessageAtTop</strong>(Boolean <em>newestMessageAtTop</em>)</code></div>
|
| 2089 | <div class="summary">
|
| 2090 | Sets whether to display new log messages at the top inside the console window.
|
| 2091 | </div>
|
| 2092 | </li>
|
| 2093 | <li class="method">
|
| 2094 | <div class="name">isScrollToLatestMessage</div>
|
| 2095 | <div class="methodsignature"><code>Boolean <strong>isScrollToLatestMessage</strong>()</code></div>
|
| 2096 | <div class="summary">
|
| 2097 | Returns whether the pop-up window scrolls to display the latest log message when a new message
|
| 2098 | is logged.
|
| 2099 | </div>
|
| 2100 | </li>
|
| 2101 | <li class="method">
|
| 2102 | <div class="name">setScrollToLatestMessage</div>
|
| 2103 | <div class="methodsignature"><code>void <strong>setScrollToLatestMessage</strong>(Boolean <em>scrollToLatestMessage</em>)</code></div>
|
| 2104 | <div class="summary">
|
| 2105 | Sets whether to scroll the console window to display the latest log message when a new message
|
| 2106 | is logged.
|
| 2107 | </div>
|
| 2108 | </li>
|
| 2109 | <li class="method">
|
| 2110 | <div class="name">getWidth</div>
|
| 2111 | <div class="methodsignature"><code>String <strong>getWidth</strong>()</code></div>
|
| 2112 | <div class="summary">
|
| 2113 | Returns the outer width of the console window.
|
| 2114 | </div>
|
| 2115 | </li>
|
| 2116 | <li class="method">
|
| 2117 | <div class="name">setWidth</div>
|
| 2118 | <div class="methodsignature"><code>void <strong>setWidth</strong>(String <em>width</em>)</code></div>
|
| 2119 | <div class="summary">
|
| 2120 | [<em>not available after initialization</em>]
|
| 2121 | <br />
|
| 2122 | Sets the outer width of the console window. Any valid CSS length may be used.
|
| 2123 | </div>
|
| 2124 | </li>
|
| 2125 | <li class="method">
|
| 2126 | <div class="name">getHeight</div>
|
| 2127 | <div class="methodsignature"><code>String <strong>getHeight</strong>()</code></div>
|
| 2128 | <div class="summary">
|
| 2129 | Returns the outer height of the console window.
|
| 2130 | </div>
|
| 2131 | </li>
|
| 2132 | <li class="method">
|
| 2133 | <div class="name">setHeight</div>
|
| 2134 | <div class="methodsignature"><code>void <strong>setHeight</strong>(String <em>height</em>)</code></div>
|
| 2135 | <div class="summary">
|
| 2136 | [<em>not available after initialization</em>]
|
| 2137 | <br />
|
| 2138 | Sets the outer height of the console window. Any valid CSS length may be used.
|
| 2139 | </div>
|
| 2140 | </li>
|
| 2141 | <li class="method">
|
| 2142 | <div class="name">getMaxMessages</div>
|
| 2143 | <div class="methodsignature"><code>Number <strong>getMaxMessages</strong>()</code></div>
|
| 2144 | <div class="summary">
|
| 2145 | Returns the largest number of messages displayed and stored by the console window.
|
| 2146 | </div>
|
| 2147 | </li>
|
| 2148 | <li class="method">
|
| 2149 | <div class="name">setMaxMessages</div>
|
| 2150 | <div class="methodsignature"><code>void <strong>setMaxMessages</strong>(Number <em>maxMessages</em>)</code></div>
|
| 2151 | <div class="summary">
|
| 2152 | [<em>not available after initialization</em>]
|
| 2153 | <br />
|
| 2154 | Sets the largest number of messages displayed and stored by the console window. Set
|
| 2155 | this to <code>null</code> to make this number unlimited.
|
| 2156 | </div>
|
| 2157 | </li>
|
| 2158 | <li class="method">
|
| 2159 | <div class="name">isShowCommandLine</div>
|
| 2160 | <div class="methodsignature"><code>Boolean <strong>isShowCommandLine</strong>()</code></div>
|
| 2161 | <div class="summary">
|
| 2162 | Returns whether the console includes a command line.
|
| 2163 | Default value is <code>true</code>.
|
| 2164 | </div>
|
| 2165 | </li>
|
| 2166 | <li class="method">
|
| 2167 | <div class="name">setShowCommandLine</div>
|
| 2168 | <div class="methodsignature"><code>void <strong>setShowCommandLine</strong>(Boolean <em>showCommandLine</em>)</code></div>
|
| 2169 | <div class="summary">
|
| 2170 | Sets whether the console includes a command line.
|
| 2171 | </div>
|
| 2172 | </li>
|
| 2173 | <li class="method">
|
| 2174 | <div class="name">getCommandLineObjectExpansionDepth</div>
|
| 2175 | <div class="methodsignature"><code>Number <strong>getCommandLineObjectExpansionDepth</strong>()</code></div>
|
| 2176 | <div class="summary">
|
| 2177 | Returns the number of levels to expand when an object value is logged to the console.
|
| 2178 | Each property of an object above this threshold will be expanded if it is itself an object
|
| 2179 | or array, otherwise its string representation will be displayed. Default value is 1 (i.e.
|
| 2180 | the properties of the object logged will be displayed in their string representation but
|
| 2181 | not expanded).
|
| 2182 | </div>
|
| 2183 | </li>
|
| 2184 | <li class="method">
|
| 2185 | <div class="name">setCommandLineObjectExpansionDepth:</div>
|
| 2186 | <div class="methodsignature"><code>void <strong>setCommandLineObjectExpansionDepth</strong>(Number <em>expansionDepth</em>)</code></div>
|
| 2187 | <div class="summary">
|
| 2188 | Sets the number of levels to expand when an object value is logged to the console.
|
| 2189 | </div>
|
| 2190 | </li>
|
| 2191 | <li class="method">
|
| 2192 | <div class="name">getCommandWindow</div>
|
| 2193 | <div class="methodsignature"><code>Window <strong>getCommandWindow</strong>()</code></div>
|
| 2194 | <div class="summary">
|
| 2195 | Returns a reference to the window in which commands typed into the command line
|
| 2196 | are currently being executed.
|
| 2197 | </div>
|
| 2198 | </li>
|
| 2199 | <li class="method">
|
| 2200 | <div class="name">setCommandWindow</div>
|
| 2201 | <div class="methodsignature"><code>void <strong>setCommandWindow</strong>(Window <em>commandWindow</em>)</code></div>
|
| 2202 | <div class="summary">
|
| 2203 | Sets the window in which commands typed into the command line are executed.
|
| 2204 | </div>
|
| 2205 | </li>
|
| 2206 | <li class="method">
|
| 2207 | <div class="name">getCommandLayout</div>
|
| 2208 | <div class="methodsignature"><code>Number <strong>getCommandLayout</strong>()</code></div>
|
| 2209 | <div class="summary">
|
| 2210 | Returns the layout used to format the output for commands typed into the command line.
|
| 2211 | The default value is a <code><a href="#patternlayout">PatternLayout</a></code> with
|
| 2212 | pattern string <code>%m</code>
|
| 2213 | </div>
|
| 2214 | </li>
|
| 2215 | <li class="method">
|
| 2216 | <div class="name">setCommandLayout</div>
|
| 2217 | <div class="methodsignature"><code>void <strong>setCommandLayout</strong>(Layout <em>commandLayout</em>)</code></div>
|
| 2218 | <div class="summary">
|
| 2219 | Sets the layout used to format the output for commands typed into the command line.
|
| 2220 | </div>
|
| 2221 | </li>
|
| 2222 | <li class="method">
|
| 2223 | <div class="name">clear</div>
|
| 2224 | <div class="methodsignature"><code>void <strong>clear</strong>()</code></div>
|
| 2225 | <div class="summary">
|
| 2226 | Clears all messages from the console window.
|
| 2227 | </div>
|
| 2228 | </li>
|
| 2229 | <li class="method">
|
| 2230 | <div class="name">show</div>
|
| 2231 | <div class="methodsignature"><code>void <strong>show</strong>()</code></div>
|
| 2232 | <div class="summary">
|
| 2233 | <p>
|
| 2234 | Shows / unhides the console window.
|
| 2235 | </p>
|
| 2236 | <p><strong>Notes</strong></p>
|
| 2237 | <ul>
|
| 2238 | <li>
|
| 2239 | In Safari (and possibly other browsers), hiding an <code>iframe</code>
|
| 2240 | resets its document, thus destroying the console window.
|
| 2241 | </li>
|
| 2242 | </ul>
|
| 2243 | </div>
|
| 2244 | </li>
|
| 2245 | <li class="method">
|
| 2246 | <div class="name">hide</div>
|
| 2247 | <div class="methodsignature"><code>void <strong>hide</strong>()</code></div>
|
| 2248 | <div class="summary">
|
| 2249 | <p>
|
| 2250 | Hides / minimizes the console window.
|
| 2251 | </p>
|
| 2252 | <p><strong>Notes</strong></p>
|
| 2253 | <ul>
|
| 2254 | <li>
|
| 2255 | In Safari (and possibly other browsers), hiding an <code>iframe</code>
|
| 2256 | resets its document, thus destroying the console window.
|
| 2257 | </li>
|
| 2258 | </ul>
|
| 2259 | </div>
|
| 2260 | </li>
|
| 2261 | <li class="method">
|
| 2262 | <div class="name">close</div>
|
| 2263 | <div class="methodsignature"><code>void <strong>close</strong>()</code></div>
|
| 2264 | <div class="summary">
|
| 2265 | Removes the console window iframe from the main document.
|
| 2266 | </div>
|
| 2267 | </li>
|
| 2268 | <li class="method">
|
| 2269 | <div class="name">focus</div>
|
| 2270 | <div class="methodsignature"><code>void <strong>focus</strong>()</code></div>
|
| 2271 | <div class="summary">
|
| 2272 | Brings the console window to the top and gives it the focus.
|
| 2273 | </div>
|
| 2274 | </li>
|
| 2275 | <li class="method">
|
| 2276 | <div class="name">focusCommandLine</div>
|
| 2277 | <div class="methodsignature"><code>void <strong>focusCommandLine</strong>()</code></div>
|
| 2278 | <div class="summary">
|
| 2279 | Brings the console window to the top and gives the focus to the command line.
|
| 2280 | </div>
|
| 2281 | </li>
|
| 2282 | <li class="method">
|
| 2283 | <div class="name">focusSearch</div>
|
| 2284 | <div class="methodsignature"><code>void <strong>focusSearch</strong>()</code></div>
|
| 2285 | <div class="summary">
|
| 2286 | Brings the console window to the top and gives the focus to the search box.
|
| 2287 | </div>
|
| 2288 | </li>
|
| 2289 | <li class="method">
|
| 2290 | <div class="name">evalCommandAndAppend</div>
|
| 2291 | <div class="methodsignature"><code>void <strong>evalCommandAndAppend</strong>(String <em>expr</em>)</code></div>
|
| 2292 | <div class="summary">
|
| 2293 | Evaluates the expression and appends the result to the console.
|
| 2294 | </div>
|
| 2295 | </li>
|
| 2296 | <li class="method">
|
| 2297 | <div class="name">addCommandLineFunction</div>
|
| 2298 | <div class="methodsignature"><code>void <strong>addCommandLineFunction</strong>(String <em>functionName</em>, Function <em>commandLineFunction</em>)</code></div>
|
| 2299 | <div class="summary">
|
| 2300 | <p>
|
| 2301 | Adds a function with the name specified to the list of functions available on the command line.
|
| 2302 | This feature may be used to add custom functions to the command line.
|
| 2303 | </p>
|
| 2304 | <p>
|
| 2305 | When you call the function on the command line, <code>commandLineFunction</code> is executed with the
|
| 2306 | following three parameters:
|
| 2307 | </p>
|
| 2308 | <ul>
|
| 2309 | <li><em>appender</em>. A reference to the appender in which the command was executed;</li>
|
| 2310 | <li><em>args</em>.
|
| 2311 | An array-like list of parameters passed into the function on the command line
|
| 2312 | (actually a reference to an <code>arguments</code> object);</li>
|
| 2313 | <li><em>returnValue</em>. This is an object with two properties that allow the function to control
|
| 2314 | how the result is displayed:
|
| 2315 | <ul>
|
| 2316 | <li><em>appendResult</em>. A boolean value that determines whether the returned value from this
|
| 2317 | function is appended to the console. The default value is <code>true</code>;</li>
|
| 2318 | <li><em>isError</em>. A boolean value that specifies whether the output of this function
|
| 2319 | should be displayed as an error. The default value is <code>false</code>.</li>
|
| 2320 | </ul>
|
| 2321 | </li>
|
| 2322 | </ul>
|
| 2323 | <p>
|
| 2324 | The value returned by the function is formatted by the command layout and appended to the console.
|
| 2325 | </p>
|
| 2326 | </div>
|
| 2327 | </li>
|
| 2328 | </ul>
|
| 2329 | <p class="linktotop">
|
| 2330 | <a href="#container">Top</a>
|
| 2331 | </p>
|
| 2332 | </div>
|
| 2333 | <div id="browserconsoleappender">
|
| 2334 | <h3>BrowserConsoleAppender</h3>
|
| 2335 | <p class="editions">Editions: <strong>Standardl</strong></p>
|
| 2336 | <p>
|
| 2337 | Writes log messages to the browser's built-in console, if present. This only works
|
| 2338 | currently in Safari, Opera and Firefox with the excellent
|
| 2339 | <a href="http://www.getfirebug.com" title="Firebug home page (opens in new window)"
|
| 2340 | target="_blank">Firebug</a> extension installed.
|
| 2341 | </p>
|
| 2342 | <p><strong>Notes</strong></p>
|
| 2343 | <ul>
|
| 2344 | <li>
|
| 2345 | As of log4javascript 1.3, the default threshold for this appender is <code>DEBUG</code>
|
| 2346 | as opposed to <code>WARN</code> as it was previously;
|
| 2347 | </li>
|
| 2348 | <li>
|
| 2349 | <p>
|
| 2350 | As of version 1.3, log4javascript has explicit support for Firebug's logging. This includes
|
| 2351 | the following mapping of log4javascript's log levels onto Firebug's:
|
| 2352 | </p>
|
| 2353 | <ul>
|
| 2354 | <li>log4javascript <code>TRACE</code>, <code>DEBUG</code> -> Firebug <code>debug</code></li>
|
| 2355 | <li>log4javascript <code>INFO</code> -> Firebug <code>info</code></li>
|
| 2356 | <li>log4javascript <code>WARN</code> -> Firebug <code>warn</code></li>
|
| 2357 | <li>log4javascript <code>ERROR</code>, <code>FATAL</code> -> Firebug <code>error</code></li>
|
| 2358 | </ul>
|
| 2359 | <p>
|
| 2360 | ... and the ability to pass objects into Firebug and take advantage of its object inspection.
|
| 2361 | This is because the default layout is now <code><a href="#nulllayout">NullLayout</a></code>,
|
| 2362 | which performs no formatting on an object.
|
| 2363 | </p>
|
| 2364 | </li>
|
| 2365 | </ul>
|
| 2366 | <h4>Constructor</h4>
|
| 2367 | <ul class="propertieslist">
|
| 2368 | <li class="method">
|
| 2369 | <div class="name">BrowserConsoleAppender</div>
|
| 2370 | <div class="methodsignature"><code><strong>BrowserConsoleAppender</strong>()</code></div>
|
| 2371 | </li>
|
| 2372 | </ul>
|
| 2373 | <p class="linktotop">
|
| 2374 | <a href="#container">Top</a>
|
| 2375 | </p>
|
| 2376 | </div>
|
| 2377 | </div>
|
| 2378 | <div id="layouts">
|
| 2379 | <h2>Layouts</h2>
|
| 2380 | <div id="layout">
|
| 2381 | <h3>Layout</h3>
|
| 2382 | <p>
|
| 2383 | There are a few methods common to all layouts:
|
| 2384 | </p>
|
| 2385 | <h4>Methods</h4>
|
| 2386 | <ul class="propertieslist">
|
| 2387 | <li class="method">
|
| 2388 | <div class="name">format</div>
|
| 2389 | <div class="methodsignature"><code>String <strong>format</strong>(LoggingEvent <em>loggingEvent</em>)</code></div>
|
| 2390 | <div class="paramsheading">Parameters:</div>
|
| 2391 | <ul class="params">
|
| 2392 | <li class="param">
|
| 2393 | <code class="paramname">loggingEvent</code>
|
| 2394 | </li>
|
| 2395 | </ul>
|
| 2396 | <div class="summary">
|
| 2397 | Formats the log message. You should override this method in your own layouts.
|
| 2398 | </div>
|
| 2399 | </li>
|
| 2400 | <li class="method">
|
| 2401 | <div class="name">ignoresThrowable</div>
|
| 2402 | <div class="methodsignature"><code>Boolean <strong>ignoresThrowable</strong>()</code></div>
|
| 2403 | <div class="summary">
|
| 2404 | Returns whether the layout ignores an error object in a logging event passed
|
| 2405 | to its <code>format</code> method.
|
| 2406 | </div>
|
| 2407 | </li>
|
| 2408 | <li class="method">
|
| 2409 | <div class="name">getContentType</div>
|
| 2410 | <div class="methodsignature"><code>String <strong>getContentType</strong>()</code></div>
|
| 2411 | <div class="summary">
|
| 2412 | Returns the content type of the output of the layout.
|
| 2413 | </div>
|
| 2414 | </li>
|
| 2415 | <li class="method">
|
| 2416 | <div class="name">allowBatching</div>
|
| 2417 | <div class="methodsignature"><code>Boolean <strong>allowBatching</strong>()</code></div>
|
| 2418 | <div class="summary">
|
| 2419 | Returns whether the layout's output is suitable for batching.
|
| 2420 | <code><a href="#jsonlayout">JsonLayout</a></code> and <code><a href="#xmllayout">XmlLayout</a></code>
|
| 2421 | are the only built-in layouts that return true for this method.
|
| 2422 | </div>
|
| 2423 | </li>
|
| 2424 | <li class="method">
|
| 2425 | <div class="name">getDataValues</div>
|
| 2426 | <div class="methodsignature"><code>Array <strong>getDataValues</strong>(LoggingEvent <em>loggingEvent</em>)</code></div>
|
| 2427 | <div class="paramsheading">Parameters:</div>
|
| 2428 | <ul class="params">
|
| 2429 | <li class="param">
|
| 2430 | <code class="paramname">loggingEvent</code>
|
| 2431 | </li>
|
| 2432 | </ul>
|
| 2433 | <div class="summary">
|
| 2434 | Used internally by log4javascript in constructing formatted output for some layouts.
|
| 2435 | </div>
|
| 2436 | </li>
|
| 2437 | <li class="method">
|
| 2438 | <div class="name">setKeys</div>
|
| 2439 | <div class="methodsignature"><code>void <strong>setKeys</strong>(String <em>loggerKey</em>,
|
| 2440 | String <em>timeStampKey</em>, String <em>levelKey</em>, String <em>messageKey</em>,
|
| 2441 | String <em>exceptionKey</em>, String <em>urlKey</em>)</code></div>
|
| 2442 | <div class="paramsheading">Parameters:</div>
|
| 2443 | <ul class="params">
|
| 2444 | <li class="param">
|
| 2445 | <code class="paramname">loggerKey</code>
|
| 2446 | <div>
|
| 2447 | Parameter to use for the log message's logger name. Default is <code>logger</code>.
|
| 2448 | </div>
|
| 2449 | </li>
|
| 2450 | <li class="param">
|
| 2451 | <code class="paramname">timeStampKey</code>
|
| 2452 | <div>
|
| 2453 | Parameter to use for the log message's timestamp. Default is <code>timestamp</code>.
|
| 2454 | </div>
|
| 2455 | </li>
|
| 2456 | <li class="param">
|
| 2457 | <code class="paramname">levelKey</code>
|
| 2458 | <div>
|
| 2459 | Parameter to use for the log message's level. Default is <code>level</code>.
|
| 2460 | </div>
|
| 2461 | </li>
|
| 2462 | <li class="param">
|
| 2463 | <code class="paramname">messageKey</code>
|
| 2464 | <div>
|
| 2465 | Parameter to use for the message itself. Default is <code>message</code>.
|
| 2466 | </div>
|
| 2467 | </li>
|
| 2468 | <li class="param">
|
| 2469 | <code class="paramname">exceptionKey</code>
|
| 2470 | <div>
|
| 2471 | Parameter to use for the log message's error (exception). Default is <code>exception</code>.
|
| 2472 | </div>
|
| 2473 | </li>
|
| 2474 | <li class="param">
|
| 2475 | <code class="paramname">urlKey</code>
|
| 2476 | <div>
|
| 2477 | Parameter to use for the current page URL. Default is <code>url</code>.
|
| 2478 | </div>
|
| 2479 | </li>
|
| 2480 | </ul>
|
| 2481 | <div class="summary">
|
| 2482 | This method is used to change the default keys used to create formatted name-value pairs
|
| 2483 | for the properties of a log message, for layouts that do this. These layouts are
|
| 2484 | <code><a href="#jsonlayout">JsonLayout</a></code> and
|
| 2485 | <code><a href="#httppostdatalayout">HttpPostDataLayout</a></code>.
|
| 2486 | </div>
|
| 2487 | </li>
|
| 2488 | <li class="method">
|
| 2489 | <div class="name">setCustomField</div>
|
| 2490 | <div class="methodsignature"><code>void <strong>setCustomField</strong>(String <em>name</em>,
|
| 2491 | String <em>value</em>)</code></div>
|
| 2492 | <div class="paramsheading">Parameters:</div>
|
| 2493 | <ul class="params">
|
| 2494 | <li class="param">
|
| 2495 | <code class="paramname">name</code>
|
| 2496 | <div>
|
| 2497 | Name of the custom property you wish to be included in the formmtted output.
|
| 2498 | </div>
|
| 2499 | </li>
|
| 2500 | <li class="param">
|
| 2501 | <code class="paramname">value</code>
|
| 2502 | <div>
|
| 2503 | Value of the custom property you wish to be included in the formatted output.
|
| 2504 | </div>
|
| 2505 | </li>
|
| 2506 | </ul>
|
| 2507 | <div class="summary">
|
| 2508 | Some layouts (<code><a href="#jsonlayout">JsonLayout</a></code>,
|
| 2509 | <code><a href="#httppostdatalayout">HttpPostDataLayout</a></code>,
|
| 2510 | <code><a href="#patternlayout">PatternLayout</a></code> and
|
| 2511 | <code><a href="#xmllayout">XmlLayout</a></code>) allow you to set
|
| 2512 | custom fields (e.g. a session id to send to the server) to the
|
| 2513 | formatted output. Use this method to set a custom field. If there
|
| 2514 | is already a custom field with the specified name, its value will
|
| 2515 | be updated with <code>value</code>.
|
| 2516 | </div>
|
| 2517 | <p><strong>Notes</strong></p>
|
| 2518 | <ul>
|
| 2519 | <li>
|
| 2520 | <p>
|
| 2521 | From version 1.4, the custom field value may be a function. In this
|
| 2522 | case, the function is run at the time the layout's format method is called,
|
| 2523 | with the following two parameters:
|
| 2524 | </p>
|
| 2525 | <ul>
|
| 2526 | <li><em>layout</em>. A reference to the layout being used;</li>
|
| 2527 | <li><em>loggingEvent</em>. A reference to the logging event being formatted.</li>
|
| 2528 | </ul>
|
| 2529 | </li>
|
| 2530 | </ul>
|
| 2531 | </li>
|
| 2532 | <li class="method">
|
| 2533 | <div class="name">hasCustomFields</div>
|
| 2534 | <div class="methodsignature"><code>Boolean <strong>hasCustomFields</strong>()</code></div>
|
| 2535 | <div class="summary">
|
| 2536 | Returns whether the layout has any custom fields.
|
| 2537 | </div>
|
| 2538 | </li>
|
| 2539 | </ul>
|
| 2540 | <p class="linktotop">
|
| 2541 | <a href="#container">Top</a>
|
| 2542 | </p>
|
| 2543 | </div>
|
| 2544 | <div id="nulllayout">
|
| 2545 | <h3>NullLayout</h3>
|
| 2546 | <p class="editions">Editions: <strong>All</strong></p>
|
| 2547 | <p>
|
| 2548 | The most basic layout. NullLayout's <code>format()</code> methods performs no
|
| 2549 | formatting at all and simply returns the message logged.
|
| 2550 | </p>
|
| 2551 | <h4>Constructor</h4>
|
| 2552 | <ul class="propertieslist">
|
| 2553 | <li class="method">
|
| 2554 | <div class="name">NullLayout</div>
|
| 2555 | <div class="methodsignature"><code><strong>NullLayout</strong>()</code></div>
|
| 2556 | </li>
|
| 2557 | </ul>
|
| 2558 | <p class="linktotop">
|
| 2559 | <a href="#container">Top</a>
|
| 2560 | </p>
|
| 2561 | </div>
|
| 2562 | <div id="simplelayout">
|
| 2563 | <h3>SimpleLayout</h3>
|
| 2564 | <p class="editions">Editions: <strong>Standard, Production</strong></p>
|
| 2565 | <p>
|
| 2566 | Provides basic formatting. SimpleLayout consists of the level of the log statement,
|
| 2567 | followed by " - " and then the log message itself. For example,
|
| 2568 | </p>
|
| 2569 | <p><code>DEBUG - Hello world</code></p>
|
| 2570 | <h4>Constructor</h4>
|
| 2571 | <ul class="propertieslist">
|
| 2572 | <li class="method">
|
| 2573 | <div class="name">SimpleLayout</div>
|
| 2574 | <div class="methodsignature"><code><strong>SimpleLayout</strong>()</code></div>
|
| 2575 | </li>
|
| 2576 | </ul>
|
| 2577 | <p class="linktotop">
|
| 2578 | <a href="#container">Top</a>
|
| 2579 | </p>
|
| 2580 | </div>
|
| 2581 | <div id="patternlayout">
|
| 2582 | <h3>PatternLayout</h3>
|
| 2583 | <p class="editions">Editions: <strong>All</strong></p>
|
| 2584 | <p>
|
| 2585 | Provides a flexible way of formatting a log message by means of a conversion pattern
|
| 2586 | string. The behaviour of this layout is a full implementation of <code>PatternLayout</code>
|
| 2587 | in log4j, with the exception of the set of conversion characters - log4javascript's is
|
| 2588 | necessarily a subset of that of log4j with a few additions of its own, since many of
|
| 2589 | the conversion characters in log4j only make sense in the context of Java.
|
| 2590 | </p>
|
| 2591 | <p>
|
| 2592 | The conversion pattern consists of literal text interspersed with special strings starting with
|
| 2593 | a % symbol called <em>conversion specifiers</em>. A conversion specifier consists of the
|
| 2594 | % symbol, a conversion character (possible characters are listed below) and
|
| 2595 | <em>format modifiers</em>. For full documentation of the conversion pattern, see
|
| 2596 | <a href="http://logging.apache.org/log4j/docs/api/org/apache/log4j/PatternLayout.html" target="_blank">log4j's
|
| 2597 | documentation</a>. Below is a list of all conversion characters available in log4javascript.
|
| 2598 | </p>
|
| 2599 | <h4>Conversion characters</h4>
|
| 2600 | <table border="1" cellspacing="0">
|
| 2601 | <thead>
|
| 2602 | <tr>
|
| 2603 | <th>Conversion Character</th>
|
| 2604 | <th>Effect</th>
|
| 2605 | </tr>
|
| 2606 | </thead>
|
| 2607 | <tbody>
|
| 2608 | <tr>
|
| 2609 | <td>a</td>
|
| 2610 | <td>
|
| 2611 | <p>
|
| 2612 | Outputs log messages specified as an array.
|
| 2613 | </p>
|
| 2614 | <p>
|
| 2615 | Behaves exactly like <code>%m</code>, except that multiple log messages are
|
| 2616 | assumed to have been specified in the logging call as an array rather than
|
| 2617 | as multiple parameters.
|
| 2618 | </p>
|
| 2619 | <p>
|
| 2620 | <strong>Since: 1.4</strong>
|
| 2621 | </p>
|
| 2622 | </td>
|
| 2623 | </tr>
|
| 2624 | <tr>
|
| 2625 | <td>c</td>
|
| 2626 | <td>
|
| 2627 | <p>
|
| 2628 | Outputs the logger name.
|
| 2629 | </p>
|
| 2630 | </td>
|
| 2631 | </tr>
|
| 2632 | <tr>
|
| 2633 | <td>d</td>
|
| 2634 | <td>
|
| 2635 | <p>
|
| 2636 | Outputs the date of the logging event. The date conversion specifier
|
| 2637 | may be followed by a date format specifier enclosed between braces. For
|
| 2638 | example, <code>%d{HH:mm:ss,SSS}</code> or
|
| 2639 | <code>%d{dd MMM yyyy HH:mm:ss,SSS}</code>. If no date
|
| 2640 | format specifier is given then ISO8601 format is assumed.
|
| 2641 | </p>
|
| 2642 | <p>
|
| 2643 | The date format specifier is the same as that used by Java's
|
| 2644 | <code><a href="http://java.sun.com/j2se/1.5.0/docs/api/java/text/SimpleDateFormat.html"
|
| 2645 | target="_blank">SimpleDateFormat</a></code>. log4javascript
|
| 2646 | includes a full implementation of SimpleDateFormat's
|
| 2647 | <code>format</code> method, with the exception of the pattern letter
|
| 2648 | 'z', (string representation of the timezone) for which the information
|
| 2649 | is not available in JavaScript.
|
| 2650 | </p>
|
| 2651 | </td>
|
| 2652 | </tr>
|
| 2653 | <tr>
|
| 2654 | <td>f</td>
|
| 2655 | <td>
|
| 2656 | <p>
|
| 2657 | Outputs the value of a custom field set on the layout. If present, the specifier gives
|
| 2658 | the index in the array of custom fields to use; otherwise, the first custom field in the
|
| 2659 | array is used.
|
| 2660 | </p>
|
| 2661 | <p>
|
| 2662 | <strong>Since: 1.3</strong>
|
| 2663 | </p>
|
| 2664 | </td>
|
| 2665 | </tr>
|
| 2666 | <tr>
|
| 2667 | <td>m</td>
|
| 2668 | <td>
|
| 2669 | <p>
|
| 2670 | Outputs the log messages of the logging event (i.e. the log
|
| 2671 | messages supplied by the client code).
|
| 2672 | </p>
|
| 2673 | <p>
|
| 2674 | As of version 1.4, multiple log messages may be supplied to logging calls.
|
| 2675 | <code>%m</code> displays each log message (using the rules below) one after
|
| 2676 | another, separated by spaces.
|
| 2677 | </p>
|
| 2678 | <p>
|
| 2679 | As of version 1.3, an object may be specified as the log message and will
|
| 2680 | be expanded to show its properties in the output, provided that a specifier
|
| 2681 | containing the number of levels to expand is provided. If no specifier is
|
| 2682 | provided then the message will be treated as a string regardless of its type.
|
| 2683 | For example, <code>%m{1}</code> will display an expansion of the object one
|
| 2684 | level deep, i.e. each property of the object will be displayed but if the
|
| 2685 | property value is itself an object it will not be expanded and will appear
|
| 2686 | as <code>[object Object]</code>.
|
| 2687 | </p>
|
| 2688 | </td>
|
| 2689 | </tr>
|
| 2690 | <tr>
|
| 2691 | <td>n</td>
|
| 2692 | <td>
|
| 2693 | <p>
|
| 2694 | Outputs a line separator.
|
| 2695 | </p>
|
| 2696 | </td>
|
| 2697 | </tr>
|
| 2698 | <tr>
|
| 2699 | <td>p</td>
|
| 2700 | <td>
|
| 2701 | <p>
|
| 2702 | Outputs the level of the logging event.
|
| 2703 | </p>
|
| 2704 | </td>
|
| 2705 | </tr>
|
| 2706 | <tr>
|
| 2707 | <td>r</td>
|
| 2708 | <td>
|
| 2709 | <p>
|
| 2710 | Outputs the number of milliseconds since log4javascript was initialized.
|
| 2711 | </p>
|
| 2712 | </td>
|
| 2713 | </tr>
|
| 2714 | <tr>
|
| 2715 | <td>%</td>
|
| 2716 | <td>
|
| 2717 | <p>
|
| 2718 | The sequence %% outputs a single percent sign.
|
| 2719 | </p>
|
| 2720 | </td>
|
| 2721 | </tr>
|
| 2722 | </tbody>
|
| 2723 | </table>
|
| 2724 | <h4>Static properties</h4>
|
| 2725 | <ul class="propertieslist">
|
| 2726 | <li class="property">
|
| 2727 | <div class="name">TTCC_CONVERSION_PATTERN</div>
|
| 2728 | <div class="summary">
|
| 2729 | Built-in conversion pattern, equivalent to <code>%r %p %c - %m%n</code>.
|
| 2730 | </div>
|
| 2731 | </li>
|
| 2732 | <li class="property">
|
| 2733 | <div class="name">DEFAULT_CONVERSION_PATTERN</div>
|
| 2734 | <div class="summary">
|
| 2735 | Built-in conversion pattern, equivalent to <code>%m%n</code>.
|
| 2736 | </div>
|
| 2737 | </li>
|
| 2738 | <li class="property">
|
| 2739 | <div class="name">ISO8601_DATEFORMAT</div>
|
| 2740 | <div class="summary">
|
| 2741 | Built-in date format (and also the default), equivalent to
|
| 2742 | <code>yyyy-MM-dd HH:mm:ss,SSS</code>.
|
| 2743 | </div>
|
| 2744 | </li>
|
| 2745 | <li class="property">
|
| 2746 | <div class="name">DATETIME_DATEFORMAT</div>
|
| 2747 | <div class="summary">
|
| 2748 | Built-in date format, equivalent to <code>dd MMM YYYY HH:mm:ss,SSS</code>.
|
| 2749 | </div>
|
| 2750 | </li>
|
| 2751 | <li class="property">
|
| 2752 | <div class="name">ABSOLUTETIME_DATEFORMAT</div>
|
| 2753 | <div class="summary">
|
| 2754 | Built-in date format, equivalent to <code>HH:mm:ss,SSS</code>.
|
| 2755 | </div>
|
| 2756 | </li>
|
| 2757 | </ul>
|
| 2758 | <h4>Constructor</h4>
|
| 2759 | <ul class="propertieslist">
|
| 2760 | <li class="method">
|
| 2761 | <div class="name">PatternLayout</div>
|
| 2762 | <div class="methodsignature"><code><strong>PatternLayout</strong>(String <em>pattern</em>)</code></div>
|
| 2763 | <div class="paramsheading">Parameters:</div>
|
| 2764 | <ul class="params">
|
| 2765 | <li class="param">
|
| 2766 | <code class="paramname">pattern</code>
|
| 2767 | <div>
|
| 2768 | The conversion pattern string to use.
|
| 2769 | </div>
|
| 2770 | </li>
|
| 2771 | </ul>
|
| 2772 | </li>
|
| 2773 | </ul>
|
| 2774 | <p class="linktotop">
|
| 2775 | <a href="#container">Top</a>
|
| 2776 | </p>
|
| 2777 | </div>
|
| 2778 | <div id="xmllayout">
|
| 2779 | <h3>XmlLayout</h3>
|
| 2780 | <p class="editions">Editions: <strong>Standard, Production</strong></p>
|
| 2781 | <p>
|
| 2782 | Based on log4j's <code>XmlLayout</code>, this layout formats a log message as a
|
| 2783 | fragment of XML. An example of the format of the fragment is as follows:
|
| 2784 | </p>
|
| 2785 | <pre>
|
| 2786 | <log4javascript:event logger="[default]" timestamp="1201048234203" level="ERROR">
|
| 2787 | <log4javascript:message><![CDATA[Big problem!]]></log4javascript:message>
|
| 2788 | <log4javascript:exception><![CDATA[Nasty error on line number 1
|
| 2789 | in file http://log4javascript.org/test.html]]></log4javascript:exception>
|
| 2790 | </log4javascript:event>
|
| 2791 | </pre>
|
| 2792 | <p><strong>Notes</strong></p>
|
| 2793 | <ul>
|
| 2794 | <li>
|
| 2795 | This layout supports batching of log messages when used in an
|
| 2796 | <code><a href="#ajaxappender">AjaxAppender</a></code>. A batch of
|
| 2797 | messages is simply concatenated to form a string of several XML
|
| 2798 | frgaments similar to that above.
|
| 2799 | </li>
|
| 2800 | <li>
|
| 2801 | The <code><log4javascript:exception></code> element is only present if an
|
| 2802 | exception was passed into the original log call.
|
| 2803 | </li>
|
| 2804 | <li>
|
| 2805 | As of version 1.4, timestamps are returned as milliseconds since midnight of
|
| 2806 | January 1, 1970 rather than seconds as in previous versions. This allows finer
|
| 2807 | measurement of the time a logging event occurred and is also the JavaScript
|
| 2808 | <code>Date</code> object's standard measurement.
|
| 2809 | </li>
|
| 2810 | <li>
|
| 2811 | Also as of version 1.4, multiple messages may be specified as separate parameters
|
| 2812 | in a single logging call. In <code>XmlLayout</code>, multiple messages may be
|
| 2813 | formatted as a single combined message or may be formated as several
|
| 2814 | <code><log4javascript:message></code> elements inside one
|
| 2815 | <code><log4javascript:messages></code> element as shown below:
|
| 2816 | <br />
|
| 2817 | <pre>
|
| 2818 | <log4javascript:event logger="[default]" timestamp="1201048234203" level="ERROR">
|
| 2819 | <log4javascript:messages>
|
| 2820 | <log4javascript:message><![CDATA[Big problem!]]></log4javascript:message>
|
| 2821 | <log4javascript:message><![CDATA[Value of x when this error
|
| 2822 | occurred: 3]]></log4javascript:message>
|
| 2823 | </log4javascript:messages>
|
| 2824 | <log4javascript:exception><![CDATA[Nasty error on line number 1
|
| 2825 | in file http://log4javascript.org/test.html]]></log4javascript:exception>
|
| 2826 | </log4javascript:event>
|
| 2827 | </pre>
|
| 2828 | </li>
|
| 2829 | <li>
|
| 2830 | As of version 1.3, custom fields may be added to the output. Each field will
|
| 2831 | add a tag of the following form inside the <code><log4javascript:event></code>
|
| 2832 | tag:
|
| 2833 | <br />
|
| 2834 | <pre>
|
| 2835 | <log4javascript:customfield name="sessionid"><![CDATA[1234]]></log4javascript:customfield>
|
| 2836 | </pre>
|
| 2837 | </li>
|
| 2838 | </ul>
|
| 2839 | <h4>Constructor</h4>
|
| 2840 | <ul class="propertieslist">
|
| 2841 | <li class="method">
|
| 2842 | <div class="name">XmlLayout</div>
|
| 2843 | <div class="methodsignature"><code><strong>XmlLayout</strong>([Boolean <em>combineMessages</em>])</code></div>
|
| 2844 | <ul class="params">
|
| 2845 | <li class="param">
|
| 2846 | <code class="paramname">combineMessages</code>
|
| 2847 | <div>
|
| 2848 | Whether or not to format multiple log messages as a combined single
|
| 2849 | <code><log4javascript:message></code> element
|
| 2850 | composed of each individual message separated by line breaks or to include
|
| 2851 | a <code><log4javascript:message></code> element for each message inside
|
| 2852 | one <code><log4javascript:messages></code> element.
|
| 2853 | If not specified, defaults to <code>true</code>.
|
| 2854 | </div>
|
| 2855 | </li>
|
| 2856 | </ul>
|
| 2857 | </li>
|
| 2858 | </ul>
|
| 2859 | <p class="linktotop">
|
| 2860 | <a href="#container">Top</a>
|
| 2861 | </p>
|
| 2862 | </div>
|
| 2863 | <div id="jsonlayout">
|
| 2864 | <h3>JsonLayout</h3>
|
| 2865 | <p class="editions">Editions: <strong>Standard, Production</strong></p>
|
| 2866 | <p>
|
| 2867 | Formats a logging event into JavaScript Object Notation (JSON).
|
| 2868 | JSON is a subset of JavaScript's object literal syntax, meaning that log
|
| 2869 | messages formatted with this layout can be interpreted directly by JavaScript
|
| 2870 | and converted into objects. See
|
| 2871 | <a href="http://json.org/" target="_blank" title="json.org (opens in new window)">json.org</a> for more details
|
| 2872 | about JSON.
|
| 2873 | </p>
|
| 2874 | <p>Example:</p>
|
| 2875 | <pre>
|
| 2876 | {
|
| 2877 | "logger": "[default]",
|
| 2878 | "timeStamp": 1201048234203,
|
| 2879 | "level": "ERROR",
|
| 2880 | "url": "http://log4javascript.org/test.html",
|
| 2881 | "message": "Big problem!",
|
| 2882 | "exception": "Nasty error on line number 1 in file
|
| 2883 | http://log4javascript.org/test.html"
|
| 2884 | }
|
| 2885 | </pre>
|
| 2886 | <p>
|
| 2887 | The <code>exception</code> property is only present if an exception was passed
|
| 2888 | into the original log call.
|
| 2889 | </p>
|
| 2890 | <p><strong>Notes</strong></p>
|
| 2891 | <ul>
|
| 2892 | <li>
|
| 2893 | This layout supports batching of log messages when used in an
|
| 2894 | <code><a href="#ajaxappender">AjaxAppender</a></code>. When sent singly
|
| 2895 | the layout formats the log message as a single JavaScript object literal;
|
| 2896 | when sent as a batch, the messages are formatted as an array literal whose
|
| 2897 | elements are log message objects.
|
| 2898 | </li>
|
| 2899 | <li>
|
| 2900 | <p>
|
| 2901 | As of version 1.3, custom fields may be added to the output. Each field will
|
| 2902 | add a property of the following form to the main object literal:
|
| 2903 | </p>
|
| 2904 | <pre>
|
| 2905 | "sessionid": 1234
|
| 2906 | </pre>
|
| 2907 | </li>
|
| 2908 | <li>
|
| 2909 | From version 1.4, the variable names used for log event properties such as
|
| 2910 | the message, timestamp and exception are specified using the <code>setKeys()</code>
|
| 2911 | method of <code><a href="#layout">Layout</a></code>.
|
| 2912 | </li>
|
| 2913 | <li>
|
| 2914 | <p>
|
| 2915 | Also as of version 1.4, multiple messages may be specified as separate parameters
|
| 2916 | in a single logging call. In <code>JsonLayout</code>, multiple messages may be
|
| 2917 | formatted as a single combined message or may be formated as an array of messages
|
| 2918 | as shown below:
|
| 2919 | </p>
|
| 2920 | <pre>
|
| 2921 | {
|
| 2922 | "logger": "[default]",
|
| 2923 | "timeStamp": 1201048234203,
|
| 2924 | "level": "ERROR",
|
| 2925 | "url": "http://log4javascript.org/test.html",
|
| 2926 | "message": [
|
| 2927 | "Big problem!",
|
| 2928 | "Value of x when this error occurred: 3"
|
| 2929 | ],
|
| 2930 | "exception": "Nasty error on line number 1 in file
|
| 2931 | http://log4javascript.org/test.html"
|
| 2932 | }
|
| 2933 | </pre>
|
| 2934 | </li>
|
| 2935 | </ul>
|
| 2936 | <h4>Constructor</h4>
|
| 2937 | <ul class="propertieslist">
|
| 2938 | <li class="method">
|
| 2939 | <div class="name">JsonLayout</div>
|
| 2940 | <div class="methodsignature"><code><strong>JsonLayout</strong>([Boolean <em>readable</em>, Boolean <em>combineMessages</em>])</code></div>
|
| 2941 | <div class="paramsheading">Parameters:</div>
|
| 2942 | <ul class="params">
|
| 2943 | <li class="param">
|
| 2944 | <code class="paramname">readable</code>
|
| 2945 | <div>
|
| 2946 | Whether or not to format each log message with line breaks and tabs.
|
| 2947 | If not specified, defaults to <code>false</code>.
|
| 2948 | </div>
|
| 2949 | </li>
|
| 2950 | <li class="param">
|
| 2951 | <code class="paramname">combineMessages</code>
|
| 2952 | <div>
|
| 2953 | Whether or not to format multiple log messages as a combined single
|
| 2954 | <code>message</code> property composed of each individual message separated by line
|
| 2955 | breaks or to format multiple messages as an array.
|
| 2956 | If not specified, defaults to <code>true</code>.
|
| 2957 | </div>
|
| 2958 | </li>
|
| 2959 | </ul>
|
| 2960 | </li>
|
| 2961 | </ul>
|
| 2962 | <h4>Methods</h4>
|
| 2963 | <ul class="propertieslist">
|
| 2964 | <li class="method">
|
| 2965 | <div class="name">isReadable</div>
|
| 2966 | <div class="methodsignature"><code>Boolean <strong>isReadable</strong>()</code></div>
|
| 2967 | <div class="summary">
|
| 2968 | Returns whether or not to each log message is formatted with line breaks and tabs.
|
| 2969 | </div>
|
| 2970 | <p><strong>Notes</strong></p>
|
| 2971 | <ul>
|
| 2972 | <li>
|
| 2973 | <p>
|
| 2974 | <code>setReadable</code> has been removed in version 1.4. This property can
|
| 2975 | be set via the constructor.
|
| 2976 | </p>
|
| 2977 | </li>
|
| 2978 | </ul>
|
| 2979 | </li>
|
| 2980 | </ul>
|
| 2981 | </div>
|
| 2982 | <div id="httppostdatalayout">
|
| 2983 | <h3>HttpPostDataLayout</h3>
|
| 2984 | <p class="editions">Editions: <strong>Standard, Production</strong></p>
|
| 2985 | <p>
|
| 2986 | Formats the log message as a simple URL-encoded string from which a simple
|
| 2987 | server-side script may extract parameters such as the log message, severity
|
| 2988 | and timestamp. This is the default layout for
|
| 2989 | <code><a href="#ajaxappender">AjaxAppender</a></code>.
|
| 2990 | </p>
|
| 2991 | <h4>Constructor</h4>
|
| 2992 | <ul class="propertieslist">
|
| 2993 | <li class="method">
|
| 2994 | <div class="name">HttpPostDataLayout</div>
|
| 2995 | <div class="methodsignature"><code><strong>HttpPostDataLayout</strong>()</code></div>
|
| 2996 | </li>
|
| 2997 | </ul>
|
| 2998 | <p><strong>Notes</strong></p>
|
| 2999 | <ul>
|
| 3000 | <li>
|
| 3001 | As of version 1.3, custom fields may be added to the output. Each field will
|
| 3002 | be added as a parameter to the post data.
|
| 3003 | </li>
|
| 3004 | <li>
|
| 3005 | From version 1.4, the variable names used for log event properties such as
|
| 3006 | the message, timestamp and exception are specified using the <code>setKeys()</code>
|
| 3007 | method of <code><a href="#layout">Layout</a></code>.
|
| 3008 | </li>
|
| 3009 | </ul>
|
| 3010 | <p class="linktotop">
|
| 3011 | <a href="#container">Top</a>
|
| 3012 | </p>
|
| 3013 | </div>
|
| 3014 | </div>
|
| 3015 | <div id="enabling">
|
| 3016 | <h2>Enabling / disabling log4javascript</h2>
|
| 3017 | <p>
|
| 3018 | All logging can be enabled or disabled in log4javascript in a number of ways:
|
| 3019 | </p>
|
| 3020 | <ul>
|
| 3021 | <li>
|
| 3022 | At any time, you can call
|
| 3023 | <code>log4javascript.setEnabled(<em>enabled</em>)</code>. This will
|
| 3024 | enable or disable all logging, depending on whether <code>enabled</code>
|
| 3025 | is set to <code>true</code> or <code>false</code>.
|
| 3026 | </li>
|
| 3027 | <li>
|
| 3028 | <p>
|
| 3029 | Assign a value to the global variable <code>log4javascript_disabled</code>.
|
| 3030 | The idea of this is so that you can enable or disable logging for a whole site by
|
| 3031 | including a JavaScript file in all your pages, and allowing this file to be
|
| 3032 | included <strong>before</strong> log4javascript.js to guarantee that no logging
|
| 3033 | can take place without having to alter log4javascript.js itself. Your included
|
| 3034 | .js file would include a single line such as the following:
|
| 3035 | </p>
|
| 3036 | <p>
|
| 3037 | <code>var log4javascript_disabled = true;</code>
|
| 3038 | </p>
|
| 3039 | </li>
|
| 3040 | <li>
|
| 3041 | Assign your logger object a value of <code>log4javascript.getNullLogger()</code>.
|
| 3042 | </li>
|
| 3043 | <li>
|
| 3044 | Replace your copy of log4javascript_x.js with stubs/log4javascript_x.js, provided in the
|
| 3045 | distribution. This file has a stub version of each of the functions and methods
|
| 3046 | in the log4javascript API and can simply be dropped in in place of the main file.
|
| 3047 | The compressed version of the stub is typically 15 times smaller than the
|
| 3048 | compressed version of the main file.
|
| 3049 | </li>
|
| 3050 | </ul>
|
| 3051 | <p class="linktotop">
|
| 3052 | <a href="#container">Top</a>
|
| 3053 | </p>
|
| 3054 | </div>
|
| 3055 | <div id="errorhandling">
|
| 3056 | <h2>log4javascript error handling</h2>
|
| 3057 | <p>
|
| 3058 | log4javascript has a single rudimentary logger-like object of its own to handle
|
| 3059 | messages generated by log4javascript itself. This logger is called <code>LogLog</code>
|
| 3060 | and is accessed via <code>log4javascript.logLog</code>.
|
| 3061 | </p>
|
| 3062 | <div id="loglog">
|
| 3063 | <h4>Methods</h4>
|
| 3064 | <ul class="propertieslist">
|
| 3065 | <li class="method">
|
| 3066 | <div class="name">setQuietMode</div>
|
| 3067 | <div class="methodsignature"><code>void <strong>setQuietMode</strong>(Boolean <em>quietMode</em>)</code></div>
|
| 3068 | <div class="paramsheading">Parameters:</div>
|
| 3069 | <ul class="params">
|
| 3070 | <li class="param">
|
| 3071 | <code class="paramname">quietMode</code>
|
| 3072 | <div>
|
| 3073 | Whether to turn quiet mode on or off.
|
| 3074 | </div>
|
| 3075 | </li>
|
| 3076 | </ul>
|
| 3077 | <div class="summary">
|
| 3078 | Sets whether <code>LogLog</code> is in quiet mode or not. In quiet mode, no
|
| 3079 | messages sent to <code>LogLog</code> have any visible effect. By default,
|
| 3080 | quiet mode is switched off.
|
| 3081 | </div>
|
| 3082 | </li>
|
| 3083 | <li class="method">
|
| 3084 | <div class="name">setAlertAllErrors</div>
|
| 3085 | <div class="methodsignature"><code>void <strong>setAlertAllErrors</strong>(Boolean <em>alertAllErrors</em>)</code></div>
|
| 3086 | <div class="paramsheading">Parameters:</div>
|
| 3087 | <ul class="params">
|
| 3088 | <li class="param">
|
| 3089 | <code class="paramname">showAllErrors</code>
|
| 3090 | <div>
|
| 3091 | Whether to show all errors or just the first.
|
| 3092 | </div>
|
| 3093 | </li>
|
| 3094 | </ul>
|
| 3095 | <div class="summary">
|
| 3096 | Sets how many errors <code>LogLog</code> will display alerts for. By default,
|
| 3097 | only the first error encountered generates an alert to the user. If you turn
|
| 3098 | all errors on by supplying <code>true</code> to this method then all errors
|
| 3099 | will generate alerts.
|
| 3100 | </div>
|
| 3101 | </li>
|
| 3102 | <li class="method">
|
| 3103 | <div class="name">debug</div>
|
| 3104 | <div class="methodsignature"><code>void <strong>debug</strong>(String <em>message</em>[, Error <em>exception</em>])</code></div>
|
| 3105 | <div class="paramsheading">Parameters:</div>
|
| 3106 | <ul class="params">
|
| 3107 | <li class="param">
|
| 3108 | <code class="paramname">message</code>
|
| 3109 | </li>
|
| 3110 | <li class="param">
|
| 3111 | <code class="paramname">exception</code>
|
| 3112 | [<em>optional</em>]
|
| 3113 | </li>
|
| 3114 | </ul>
|
| 3115 | <div class="summary">
|
| 3116 | Logs a debugging message to an in-memory list. This implementation is new in version 1.4.
|
| 3117 | </div>
|
| 3118 | </li>
|
| 3119 | <li class="method">
|
| 3120 | <div class="name">displayDebug</div>
|
| 3121 | <div class="methodsignature"><code>void <strong>displayDebug</strong>()</code></div>
|
| 3122 | <div class="summary">
|
| 3123 | Displays an alert of all debugging messages. This method is new in version 1.4.
|
| 3124 | </div>
|
| 3125 | </li>
|
| 3126 | <li class="method">
|
| 3127 | <div class="name">warn</div>
|
| 3128 | <div class="methodsignature"><code>void <strong>warn</strong>(String <em>message</em>[, Error <em>exception</em>])</code></div>
|
| 3129 | <div class="paramsheading">Parameters:</div>
|
| 3130 | <ul class="params">
|
| 3131 | <li class="param">
|
| 3132 | <code class="paramname">message</code>
|
| 3133 | </li>
|
| 3134 | <li class="param">
|
| 3135 | <code class="paramname">exception</code>
|
| 3136 | [<em>optional</em>]
|
| 3137 | </li>
|
| 3138 | </ul>
|
| 3139 | <div class="summary">
|
| 3140 | Currently has no effect.
|
| 3141 | </div>
|
| 3142 | </li>
|
| 3143 | <li class="method">
|
| 3144 | <div class="name">error</div>
|
| 3145 | <div class="methodsignature"><code>void <strong>error</strong>(String <em>message</em>[, Error <em>exception</em>])</code></div>
|
| 3146 | <div class="paramsheading">Parameters:</div>
|
| 3147 | <ul class="params">
|
| 3148 | <li class="param">
|
| 3149 | <code class="paramname">message</code>
|
| 3150 | </li>
|
| 3151 | <li class="param">
|
| 3152 | <code class="paramname">exception</code>
|
| 3153 | [<em>optional</em>]
|
| 3154 | </li>
|
| 3155 | </ul>
|
| 3156 | <div class="summary">
|
| 3157 | Generates an alert to the user if and only if the error is the first one
|
| 3158 | encountered and <code>setAlertAllErrors(true)</code> has not been called.
|
| 3159 | </div>
|
| 3160 | </li>
|
| 3161 | </ul>
|
| 3162 | <p class="linktotop">
|
| 3163 | <a href="#container">Top</a>
|
| 3164 | </p>
|
| 3165 | </div>
|
| 3166 | </div>
|
| 3167 | <div id="differences">
|
| 3168 | <h2>Differences between log4javascript and log4j</h2>
|
| 3169 | <p>
|
| 3170 | For the sake of keeping log4javascript as light and useful as possible, many
|
| 3171 | of the features of log4j that seem over-complex or inappropriate for
|
| 3172 | JavaScript have not been implemented. These include:
|
| 3173 | </p>
|
| 3174 | <ul>
|
| 3175 | <li>Filters</li>
|
| 3176 | <li>Configurators</li>
|
| 3177 | <li>Renderers</li>
|
| 3178 | </ul>
|
| 3179 | <p class="linktotop">
|
| 3180 | <a href="#container">Top</a>
|
| 3181 | </p>
|
| 3182 | </div>
|
| 3183 | </div>
|
| 3184 | <div id="footer">
|
| 3185 | <span class="externallinkinfo">
|
| 3186 | <strong>NB.</strong> All external links open in a new window.
|
| 3187 | </span>
|
| 3188 | Written by Tim Down. <a href="mailto:tim@log4javascript.org">tim@log4javascript.org</a>
|
| 3189 | <br />
|
| 3190 | log4javascript is distributed under the <a href="http://www.apache.org/licenses/LICENSE-2.0.html"
|
| 3191 | title="Apache License, Version 2.0 (opens in new window)" target="_blank">Apache License,
|
| 3192 | Version 2.0</a>
|
| 3193 |
|
| 3194 | </div>
|
| 3195 | </div>
|
| 3196 |
|
| 3197 | </body>
|
| 3198 | </html>
|