1 <?xml version="1.0"?>
\r
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
\r
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
\r
5 <title>log4javascript 1.4 manual</title>
\r
6 <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
\r
7 <meta name="author" content="Tim Down - tim@log4javascript.org" />
\r
8 <meta name="description" content="log4javascript, a logging framework for JavaScript based on log4j" />
\r
9 <meta name="robots" content="all" />
\r
10 <link rel="stylesheet" type="text/css" media="screen,print" href="../main.css" title="Default" />
\r
13 <div id="container" class="nonav">
\r
15 <h1><a href="index.html">log4javascript</a></h1>
\r
19 <a class="navitem" href="../index.html">home</a>
\r
20 | <a class="navitem" href="http://sourceforge.net/projects/log4javascript" target="_blank" title="Download (opens in new window)">download</a>
\r
21 | <a class="navitem" href="index.html">docs</a>
\r
22 | <a class="navitem" href="quickstart.html">quick start</a>
\r
23 | <a class="navitem" href="../demos/index.html">demos</a>
\r
24 | <a class="navitem" href="http://log4javascript.org" target="_blank">website</a>
\r
25 | <a class="navitem" href="http://www.timdown.co.uk" target="_blank">timdown.co.uk</a>
\r
27 <h1>log4javascript 1.4 manual</h1>
\r
30 <li><a href="#intro">Introduction</a></li>
\r
31 <li><a href="#noteaboutlog4javascript">Note about the log4javascript object</a></li>
\r
33 <a href="#loggersappenderslayoutslevels">Loggers, appenders, layouts and levels</a>
\r
35 <li><a href="#configuration">Configuring appenders</a></li>
\r
36 <li><a href="#loggersappenderslayoutslevelsexample">Example</a></li>
\r
39 <li><a href="#log4javascript">log4javascript static properties/methods</a></li>
\r
40 <li><a href="#levels">Levels</a></li>
\r
41 <li><a href="#loggers">Loggers</a></li>
\r
43 <a href="#appenders">Appenders</a>
\r
45 <li><a href="#appender">Appender</a></li>
\r
46 <li><a href="#alertappender">AlertAppender</a></li>
\r
47 <li><a href="#ajaxappender">AjaxAppender</a></li>
\r
48 <li><a href="#popupappender">PopUpAppender</a></li>
\r
49 <li><a href="#inpageappender">InPageAppender</a></li>
\r
50 <li><a href="#browserconsoleappender">BrowserConsoleAppender</a></li>
\r
54 <a href="#layouts">Layouts</a>
\r
56 <li><a href="#layout">Layout</a></li>
\r
57 <li><a href="#nulllayout">NullLayout</a></li>
\r
58 <li><a href="#simplelayout">SimpleLayout</a></li>
\r
59 <li><a href="#patternlayout">PatternLayout</a></li>
\r
60 <li><a href="#xmllayout">XmlLayout</a></li>
\r
61 <li><a href="#jsonlayout">JsonLayout</a></li>
\r
62 <li><a href="#httppostdatalayout">HttpPostDataLayout</a></li>
\r
65 <li><a href="#enabling">Enabling / disabling log4javascript</a></li>
\r
67 <a href="#errorhandling">log4javascript error handling</a>
\r
69 <li><a href="#loglog">LogLog</a></li>
\r
72 <li><a href="#differences">Differences between log4javascript and log4j</a></li>
\r
75 <h2>Introduction</h2>
\r
77 Anyone who has done a reasonable amount of JavaScript development will be
\r
78 familiar with <code>alert</code> as a means of debugging. For
\r
79 a small script, it works fine. But for anything of greater complexity than,
\r
80 say, a rollover script its shortcomings become apparent. The most obvious problem
\r
81 is the endless clicking of 'OK'. Another problem is that for a page
\r
82 heavily reliant on events generated from user actions, alerts
\r
83 can actually alter the way the page behaves. One final problem is infinite loops:
\r
84 without alerts, the browser will notice that the script has messed
\r
85 up and will offer the user the chance to stop the script running. With an
\r
86 alert inside an infinite loop, you're forced to kill the browser.
\r
89 At the other end of the scale there is
\r
90 <a href="http://www.mozilla.org/projects/venkman/" target="_blank">Venkman</a>,
\r
91 a full-on JavaScript debugger for Mozilla-based browsers such as Firefox. Here
\r
92 I have to confess that I simply have not put in the time to learn how to make
\r
93 it work well for me and I suspect I am not alone.
\r
96 Nowadays, easily the best option for day-to-day JavaScript development is the brilliant
\r
97 <a href="http://www.getfirebug.com" title="Firebug home page (opens in new window)"
\r
98 target="_blank">Firebug</a>, a Firefox plugin with built-in debugger, console, logging,
\r
99 and profiler. It's a seriously impressive tool but by its very nature as a Firefox
\r
100 plugin can only be used in one of the typical target browsers for mainstream web
\r
104 log4javascript was originally written as a cross-browser tool to ease the pain of JavaScript
\r
105 debugging without the time investment required to use a debugger effectively. It requires
\r
106 only a JavaScript include and one line of code to initialize with default settings.
\r
107 Having for several years used log4j and its .NET port log4net, it was natural for me to
\r
111 log4javascript is by no means the only JavaScript logging framework out there.
\r
112 It is not even the only JavaScript implementation of log4j. It turns out the name
\r
113 log4javascript is used by another JavaScript logging framework, and that the name log4js is
\r
114 used by at least two other pieces of software; this version of log4javascript is unrelated
\r
117 <p class="linktotop">
\r
118 <a href="#container">Top</a>
\r
121 <div id="noteaboutlog4javascript">
\r
122 <h2>Note about the log4javascript object</h2>
\r
124 All of log4javascript's instantiable classes are accessible via the log4javascript object, which
\r
125 acts as a namespace. Therefore references to all class names must be preceded with "log4javascript.".
\r
129 <code>var popUpAppender = new log4javascript.PopUpAppender();</code>
\r
131 <p class="linktotop">
\r
132 <a href="#container">Top</a>
\r
135 <div id="loggersappenderslayoutslevels">
\r
136 <h2>Loggers, Appenders, Layouts and Levels</h2>
\r
138 A <em>logger</em> in log4javascript is the object on which log calls are
\r
139 made. A logger may be assigned zero or more <em>appenders</em>.
\r
140 An appender is an object that actually does the logging: for example,
\r
141 a <code><a href="#popupappender">PopUpAppender</a></code> logs messages to
\r
142 a pop-up console window while an <code><a href="#ajaxappender">AjaxAppender</a></code>
\r
143 uses HTTP to send log messages back to the server. Each appender is assigned
\r
144 a <em>layout</em>, which is responsible for formatting log messages that
\r
145 are passed to an appender.
\r
148 Every log message has a <em>level</em>. This is the severity of the message.
\r
149 Available levels are <code>TRACE</code>, <code>DEBUG</code>, <code>INFO</code>,
\r
150 <code>WARN</code>, <code>ERROR</code> and <code>FATAL</code> - these correspond to
\r
151 the logging methods <code>trace</code>, <code>debug</code>, <code>info</code>,
\r
152 <code>warn</code>, <code>error</code> and <code>fatal</code> of <code>Logger</code>.
\r
153 Levels are ordered as follows: <code>TRACE</code> < <code>DEBUG</code> <
\r
154 <code>INFO</code> < <code>WARN</code> < <code>ERROR</code> <
\r
155 <code>FATAL</code>. This means the <code>FATAL</code> is the most severe and
\r
156 <code>TRACE</code> the least. Also included are levels called <code>ALL</code>
\r
157 and <code>OFF</code> intended to enable or disable all logging respectively.
\r
160 Both loggers and appenders also have threshold levels (by default, <code>DEBUG</code>
\r
161 for loggers and <code>ALL</code> for appenders).
\r
162 Setting a level to either a logger or an appender disables log messages of severity
\r
163 lower than that level. For instance, if a level of <code>INFO</code> is set on a
\r
164 logger then only log messages of severity <code>INFO</code> or greater will be logged,
\r
165 meaning <code>DEBUG</code> and <code>TRACE</code> messages will not be logged. If the
\r
166 same logger had two appenders, one of level <code>DEBUG</code> and one of level
\r
167 <code>WARN</code> then the first appender will still only log messages of
\r
168 <code>INFO</code> or greater while the second appender will only log messages of level
\r
169 <code>WARN</code> or greater.
\r
172 This allows the developer fine control over which messages get logged where.
\r
174 <div id="configuration">
\r
175 <h3>Configuring appenders</h3>
\r
177 From version 1.4, <strong>configuring appenders is only possible via configuration
\r
178 methods</strong>. As the number of configuration options increases it becomes increasingly
\r
179 undesirable to use constructor parameters, so support for it has been dropped.
\r
182 <div id="loggersappenderslayoutslevelsexample">
\r
185 <strong>NB.</strong> The Ajax side of this example relies on having
\r
186 server-side processing in place.
\r
189 First, log4javascript is initialized, and a logger (actually the
\r
190 anonymous logger) is assigned to a variable called <code>log</code>:
\r
193 <script type="text/javascript" src="log4javascript.js"></script>
\r
194 <script type="text/javascript">
\r
196 var log = log4javascript.getLogger();
\r
199 <code>log</code> does not yet have any appenders, so a call to <code>log.debug()</code>
\r
200 will do nothing as yet. For this example we will use a
\r
201 <code><a href="#popupappender">PopUpAppender</a></code> for debugging purposes.
\r
202 Since the lifespan of the messages displayed in the pop-up is only going to be the
\r
203 same as that of the window, a <code><a href="#patternlayout">PatternLayout</a></code>
\r
204 is used that displays the time of the message and not the date (note that this is
\r
205 also true of PopUpAppender's default layout). The format of the string passed into
\r
206 PatternLayout is explained <a href="#patternlayout">below</a>.
\r
209 var popUpAppender = new log4javascript.PopUpAppender();
\r
210 var popUpLayout = new log4javascript.PatternLayout("%d{HH:mm:ss} %-5p - %m%n");
\r
211 popUpAppender.setLayout(popUpLayout);
\r
212 log.addAppender(popUpAppender);
\r
215 Suppose that we also want to send log messages to the server, but limited to
\r
216 error messages only. To achieve this we use an
\r
217 <code><a href="#ajaxappender">AjaxAppender</a></code>. Note that if no layout is
\r
218 specified then for convenience a default layout is used; in the case of
\r
219 AjaxAppender, that is <code><a href="#httppostdatalayout">HttpPostDataLayout</a></code>,
\r
220 which formats log messages as a standard HTTP POST string from which a simple
\r
221 server-side script (not provided with log4javascript) will be able to extract
\r
222 posted parameters. This is fine for our purposes:
\r
225 var ajaxAppender = new log4javascript.AjaxAppender("myloggingservlet.do");
\r
226 ajaxAppender.setThreshold(log4javascript.Level.<code>ERROR</code>);
\r
227 log.addAppender(ajaxAppender);
\r
230 Finally, some test log messages and the closing script tag:
\r
233 log.debug("Debugging message (appears in pop-up)");
\r
234 log.error("Error message (appears in pop-up and in server log)");
\r
242 <script type="text/javascript" src="log4javascript.js"></script>
\r
243 <script type="text/javascript">
\r
245 var log = log4javascript.getLogger();
\r
246 var popUpAppender = new log4javascript.PopUpAppender();
\r
247 var popUpLayout = new log4javascript.PatternLayout("%d{HH:mm:ss} %-5p - %m%n");
\r
248 popUpAppender.setLayout(popUpLayout);
\r
249 log.addAppender(popUpAppender);
\r
250 var ajaxAppender = new log4javascript.AjaxAppender("myloggingservlet.do");
\r
251 ajaxAppender.setThreshold(log4javascript.Level.ERROR);
\r
252 log.addAppender(ajaxAppender);
\r
253 log.debug("Debugging message (appears in pop-up)");
\r
254 log.error("Error message (appears in pop-up and in server log)");
\r
259 <a href="../examples/example_manual.html" title="View example (opens in new window)"
\r
260 target="_blank">See this example in action</a> (opens in new window)
\r
263 <p class="linktotop">
\r
264 <a href="#container">Top</a>
\r
267 <div id="log4javascript">
\r
268 <h2>log4javascript static properties/methods</h2>
\r
269 <h4>Properties</h4>
\r
270 <ul class="propertieslist">
\r
271 <li class="property">
\r
272 <div class="name">version</div>
\r
273 <div class="summary">
\r
274 The version number of your copy of log4javascript.
\r
277 <li class="property">
\r
278 <div class="name">edition</div>
\r
279 <div class="summary">
\r
280 The edition of your copy of log4javascript.
\r
283 <li class="property">
\r
284 <div class="name">logLog</div>
\r
285 <div class="summary">
\r
286 log4javascript's internal logging object. <a href="#loglog">See below for more details</a>.
\r
291 <ul class="propertieslist">
\r
292 <li class="method">
\r
293 <div class="name">getLogger</div>
\r
294 <div class="methodsignature"><code>Logger <strong>getLogger</strong>([String <em>loggerName</em>])</code></div>
\r
295 <div class="paramsheading">Parameters:</div>
\r
296 <ul class="params">
\r
298 <code class="paramname">loggerName</code>
\r
299 [<em>optional</em>]
\r
302 <div class="summary">
\r
304 Returns a logger with the specified name, creating it if a logger with that name does not
\r
305 already exist. If no name is specified, a logger is returned with name <code>[anonymous]</code>, and
\r
306 subsequent calls to <code>getLogger()</code> (with no logger name specified) will return
\r
307 this same logger object.
\r
310 Note that the names <code>[anonymous]</code>, <code>[default]</code>, <code>[null]</code>
\r
311 and <code>root</code> are reserved for
\r
312 the anonymous logger, default logger, null logger and root logger respectively.
\r
316 <li class="method">
\r
317 <div class="name">getDefaultLogger</div>
\r
318 <div class="methodsignature"><code>Logger <strong>getDefaultLogger</strong>()</code></div>
\r
319 <div class="summary">
\r
320 Convenience method that returns the default logger. The default logger
\r
321 has a single appender: a <code><a href="#popupappender">PopUpAppender</a></code>
\r
322 with the default layout, width and height, and with <code>focusPopUp</code> set to false
\r
323 and <code>lazyInit</code>, <code>useOldPopUp</code> and
\r
324 <code>complainAboutPopUpBlocking</code> all set to true.
\r
327 <li class="method">
\r
328 <div class="name">getNullLogger</div>
\r
329 <div class="methodsignature"><code>Logger <strong>getNullLogger</strong>()</code></div>
\r
330 <div class="summary">
\r
331 Returns an empty logger with no appenders. Useful for disabling all logging.
\r
334 <li class="method">
\r
335 <div class="name">getRootLogger</div>
\r
336 <div class="methodsignature"><code>Logger <strong>getRootLogger</strong>()</code></div>
\r
337 <div class="summary">
\r
338 Returns the root logger from which all other loggers derive.
\r
341 <li class="method">
\r
342 <div class="name">resetConfiguration</div>
\r
343 <div class="methodsignature"><code>void <strong>resetConfiguration</strong>()</code></div>
\r
344 <div class="summary">
\r
345 Resets the all loggers to their default level.
\r
348 <li class="method">
\r
349 <div class="name">setEnabled</div>
\r
350 <div class="methodsignature"><code>void <strong>setEnabled</strong>(Boolean <em>enabled</em>)</code></div>
\r
351 <div class="paramsheading">Parameters:</div>
\r
352 <ul class="params">
\r
354 <code class="paramname">enabled</code>
\r
357 <div class="summary">
\r
358 Enables or disables all logging, depending on <code>enabled</code>.
\r
361 <li class="method">
\r
362 <div class="name">isEnabled</div>
\r
363 <div class="methodsignature"><code>Boolean <strong>isEnabled</strong>()</code></div>
\r
364 <div class="summary">
\r
365 Returns true or false depending on whether logging is enabled.
\r
368 <li class="method" id="log4javascriptaddeventlistener">
\r
369 <div class="name">addEventListener</div>
\r
370 <div class="methodsignature"><code>void <strong>addEventListener</strong>(String <em>eventType</em>, Function <em>listener</em>)</code></div>
\r
371 <div class="paramsheading">Parameters:</div>
\r
372 <ul class="params">
\r
374 <code class="paramname">eventType</code>
\r
377 <code class="paramname">listener</code>
\r
380 <div class="summary">
\r
382 Adds a function to be called when an event of the type specified occurs in log4javascript.
\r
383 Supported event types are <code>load</code> (occurs once the page has loaded) and
\r
384 <code>error</code>.
\r
387 Each listener is pased three paramaters:
\r
390 <li><code>sender</code>. The object that raised the event (i.e. the log4javascript object);</li>
\r
391 <li><code>eventType</code>. The type of the event;</li>
\r
393 <code>eventArgs</code>. An object containing of event-specific arguments. For the <code>error</code> event,
\r
394 this is an object with properties <code>message</code> and <code>exception</code>. For the <code>load</code>
\r
395 event this is an empty object.
\r
400 <li class="method">
\r
401 <div class="name">removeEventListener</div>
\r
402 <div class="methodsignature"><code>void <strong>removeEventListener</strong>(String <em>eventType</em>, Function <em>listener</em>)</code></div>
\r
403 <div class="paramsheading">Parameters:</div>
\r
404 <ul class="params">
\r
406 <code class="paramname">eventType</code>
\r
409 <code class="paramname">listener</code>
\r
412 <div class="summary">
\r
413 Removes the event listener function supplied for the event of the type specified.
\r
416 <li class="method">
\r
417 <div class="name">dispatchEvent</div>
\r
418 <div class="methodsignature"><code>void <strong>dispatchEvent</strong>(String <em>eventType</em>, Object <em>eventArgs</em>)</code></div>
\r
419 <div class="paramsheading">Parameters:</div>
\r
420 <ul class="params">
\r
422 <code class="paramname">eventType</code>
\r
425 <code class="paramname">eventArgs</code>
\r
428 <div class="summary">
\r
429 Raises an event of type <code>eventType</code> on the <code>log4javascript</code> object.
\r
430 Each of the listeners for this type of event (registered via <code>addEventListener</code>)
\r
431 is called and passed <code>eventArgs</code> as the third parameter.
\r
434 <li class="method">
\r
435 <div class="name">setEventTypes</div>
\r
436 <div class="methodsignature"><code>void <strong>setEventTypes</strong>(Array <em>eventTypes</em>)</code></div>
\r
437 <div class="paramsheading">Parameters:</div>
\r
438 <ul class="params">
\r
440 <code class="paramname">eventTypes</code>
\r
443 <div class="summary">
\r
444 Used internally to specify the types of events that the <code>log4javascript</code> object can raise.
\r
447 <li class="method">
\r
448 <div class="name">setShowStackTraces</div>
\r
449 <div class="methodsignature"><code>void <strong>setShowStackTraces</strong>(Boolean <em>show</em>)</code></div>
\r
450 <div class="paramsheading">Parameters:</div>
\r
451 <ul class="params">
\r
453 <code class="paramname">show</code>
\r
456 <div class="summary">
\r
457 Enables or disables displaying of error stack traces, depending on <code>show</code>.
\r
458 By default, stack traces are not displayed. (Only works in Firefox)
\r
461 <li class="method">
\r
462 <div class="name">evalInScope</div>
\r
463 <div class="methodsignature"><code>Object <strong>evalInScope</strong>(String <em>expr</em>)</code></div>
\r
464 <div class="paramsheading">Parameters:</div>
\r
465 <ul class="params">
\r
467 <code class="paramname">expr</code>
\r
470 <div class="summary">
\r
471 This evaluates the given expression in the log4javascript scope, thus allowing
\r
472 scripts to access internal log4javascript variables and functions. This was written
\r
473 for the purposes of automated testing but could be used by custom extensions to
\r
478 <p class="linktotop">
\r
479 <a href="#container">Top</a>
\r
485 Levels are available as static properties of the <code>log4javascript.Level</code>
\r
486 object. In ascending order of severity:
\r
489 <li><code>log4javascript.Level.ALL</code></li>
\r
490 <li><code>log4javascript.Level.TRACE</code></li>
\r
491 <li><code>log4javascript.Level.DEBUG</code></li>
\r
492 <li><code>log4javascript.Level.INFO</code></li>
\r
493 <li><code>log4javascript.Level.WARN</code></li>
\r
494 <li><code>log4javascript.Level.ERROR</code></li>
\r
495 <li><code>log4javascript.Level.FATAL</code></li>
\r
496 <li><code>log4javascript.Level.OFF</code></li>
\r
498 <p class="linktotop">
\r
499 <a href="#container">Top</a>
\r
505 It is possible to have multiple loggers in log4javascript. For example, you
\r
506 may wish to have a logger for debugging purposes that logs messages to a
\r
507 pop-up window and a separate logger that reports any client-side application
\r
508 errors to the server via Ajax.
\r
510 <div id="loggerhierarchy">
\r
511 <h3>Logger hierarchy and appender additivity</h3>
\r
513 From version 1.4, log4javascript has hierarchical loggers, implemented in the same way
\r
514 as log4j. In summary, you specify a logger's parent logger by means of a dot between the
\r
515 parent logger name and the child logger name. Therefore the logger <code>tim.app.security</code>
\r
516 inherits from <code>tim.app</code>, which in turn inherits from <code>tim</code> which,
\r
517 finally, inherits from the root logger.
\r
520 What inheritance means for a logger is that in the absence of a threshold level set
\r
521 specifically on the logger it inherits its level from its parent; also, a logger inherits
\r
522 all its parent's appenders (this is known as <em>appender additivity</em> in log4j. This
\r
523 behaviour can be enabled or disabled via <code>setAdditivity()</code>. See below). In the
\r
524 above example, if the root logger has a level of <code>DEBUG</code> and one appender,
\r
525 each of the loggers <code>tim.app.security</code>, <code>tim.app</code> and <code>tim</code> would
\r
526 inherit the root level's appender. If, say, <code>tim.app</code>'s threshold level was set
\r
527 to <code>WARN</code>, <code>tim</code>'s effective level would remain at <code>DEBUG</code>
\r
528 (inherited from the root logger) while <code>tim.app.security</code>'s effective level would
\r
529 be <code>WARN</code>, inherited from <code>tim.app</code>. The important thing to note is
\r
530 that appenders accumulate down the logger hierarchy while levels are simply inherited from
\r
531 the nearest ancestor with a threshold level set.
\r
534 For a detailed explanation of the logger hierarchy, see the
\r
535 <a href="http://logging.apache.org/log4j/docs/manual.html" target="_blank"
\r
536 title="Log4j manual (opens in new window)">log4j manual</a>.
\r
539 <p><strong>Notes</strong></p>
\r
542 It is not possible to instantiate loggers directly. Instead you must use
\r
543 one of the methods of the <code>log4javascript</code> object: <code>getLogger</code>,
\r
544 <code>getRootLogger</code>, <code>getDefaultLogger</code> or <code>getNullLogger</code>.
\r
547 <h4>Logger methods</h4>
\r
548 <ul class="propertieslist">
\r
549 <li class="method">
\r
550 <div class="name">addAppender</div>
\r
551 <div class="methodsignature"><code>void <strong>addAppender</strong>(Appender <em>appender</em>)</code></div>
\r
552 <div class="paramsheading">Parameters:</div>
\r
553 <ul class="params">
\r
555 <code class="paramname">appender</code>
\r
558 <div class="summary">
\r
559 Adds the given appender.
\r
562 <li class="method">
\r
563 <div class="name">removeAppender</div>
\r
564 <div class="methodsignature"><code>void <strong>removeAppender</strong>(Appender <em>appender</em>)</code></div>
\r
565 <div class="paramsheading">Parameters:</div>
\r
566 <ul class="params">
\r
568 <code class="paramname">appender</code>
\r
571 <div class="summary">
\r
572 Removes the given appender.
\r
575 <li class="method">
\r
576 <div class="name">removeAllAppenders</div>
\r
577 <div class="methodsignature"><code>void <strong>removeAllAppenders</strong>()</code></div>
\r
578 <div class="summary">
\r
579 Clears all appenders for the current logger.
\r
582 <li class="method">
\r
583 <div class="name">setLevel</div>
\r
584 <div class="methodsignature"><code>void <strong>setLevel</strong>(Level <em>level</em>)</code></div>
\r
585 <div class="paramsheading">Parameters:</div>
\r
586 <ul class="params">
\r
588 <code class="paramname">level</code>
\r
591 <div class="summary">
\r
592 Sets the level. Log messages of a lower level than <code>level</code> will not be logged.
\r
593 Default value is <code>DEBUG</code>.
\r
596 <li class="method">
\r
597 <div class="name">getLevel</div>
\r
598 <div class="methodsignature"><code>Level <strong>getLevel</strong>()</code></div>
\r
599 <div class="summary">
\r
600 Returns the level explicitly set for this logger or <code>null</code> if none has been set.
\r
603 <li class="method">
\r
604 <div class="name">getEffectiveLevel</div>
\r
605 <div class="methodsignature"><code>Level <strong>getEffectiveLevel</strong>()</code></div>
\r
606 <div class="summary">
\r
607 Returns the level at which the logger is operating. This is either the level explicitly
\r
608 set on the logger or, if no level has been set, the effective level of the logger's parent.
\r
611 <li class="method">
\r
612 <div class="name">setAdditivity</div>
\r
613 <div class="methodsignature"><code>void <strong>setAdditivity</strong>(Boolean <em>additivity</em>)</code></div>
\r
614 <div class="paramsheading">Parameters:</div>
\r
615 <ul class="params">
\r
617 <code class="paramname">additivity</code>
\r
620 <div class="summary">
\r
622 Sets whether appender additivity is enabled (the default) or disabled. If set to false, this
\r
623 particular logger will not inherit any appenders form its ancestors. Any descendant of this
\r
624 logger, however, will inherit from its ancestors as normal, unless its own additivity is
\r
625 explicitly set to false.
\r
628 Default value is <code>true</code>.
\r
632 <li class="method">
\r
633 <div class="name">getAdditivity</div>
\r
634 <div class="methodsignature"><code>Level <strong>getLevel</strong>()</code></div>
\r
635 <div class="summary">
\r
636 Returns whether additivity is enabled for this logger.
\r
639 <li class="method">
\r
640 <div class="name">log</div>
\r
641 <div class="methodsignature"><code>void <strong>log</strong>(Level <em>level</em>, Object <em>params</em>)</code></div>
\r
642 <div class="paramsheading">Parameters:</div>
\r
643 <ul class="params">
\r
645 <code class="paramname">level</code>
\r
648 <code class="paramname">params</code>
\r
651 <div class="summary">
\r
652 Generic logging method used by wrapper methods such as <code>debug</code>,
\r
653 <code>error</code> etc.
\r
655 <p><strong>Notes</strong></p>
\r
658 The signature of this method has changed in 1.4.
\r
662 <li class="method">
\r
663 <div class="name">trace</div>
\r
664 <div class="methodsignature"><code>void <strong>trace</strong>(Object <em>message1</em>[, Object <em>message2</em>, ... ][, Error <em>exception</em>])</code></div>
\r
665 <div class="paramsheading">Parameters:</div>
\r
666 <ul class="params">
\r
668 <code class="paramname">message1[, message2...]</code>
\r
671 <code class="paramname">exception</code>
\r
672 [<em>optional</em>]
\r
675 <div class="summary">
\r
676 Logs one or more messages and optionally an error at level <code>TRACE</code>.
\r
678 <p><strong>Notes</strong></p>
\r
681 Logging of multiple messages in one call is new in 1.4.
\r
685 <li class="method">
\r
686 <div class="name">debug</div>
\r
687 <div class="methodsignature"><code>void <strong>debug</strong>(Object <em>message1</em>[, Object <em>message2</em>, ... ][, Error <em>exception</em>])</code></div>
\r
688 <div class="paramsheading">Parameters:</div>
\r
689 <ul class="params">
\r
691 <code class="paramname">message1[, message2...]</code>
\r
694 <code class="paramname">exception</code>
\r
695 [<em>optional</em>]
\r
698 <div class="summary">
\r
699 Logs one or more messages and optionally an error at level <code>DEBUG</code>.
\r
701 <p><strong>Notes</strong></p>
\r
704 Logging of multiple messages in one call is new in 1.4.
\r
708 <li class="method">
\r
709 <div class="name">info</div>
\r
710 <div class="methodsignature"><code>void <strong>info</strong>(Object <em>message1</em>[, Object <em>message2</em>, ... ][, Error <em>exception</em>])</code></div>
\r
711 <div class="paramsheading">Parameters:</div>
\r
712 <ul class="params">
\r
714 <code class="paramname">message1[, message2...]</code>
\r
717 <code class="paramname">exception</code>
\r
718 [<em>optional</em>]
\r
721 <div class="summary">
\r
722 Logs one or more messages and optionally an error at level <code>INFO</code>.
\r
724 <p><strong>Notes</strong></p>
\r
727 Logging of multiple messages in one call is new in 1.4.
\r
731 <li class="method">
\r
732 <div class="name">warn</div>
\r
733 <div class="methodsignature"><code>void <strong>warn</strong>(Object <em>message1</em>[, Object <em>message2</em>, ... ][, Error <em>exception</em>])</code></div>
\r
734 <div class="paramsheading">Parameters:</div>
\r
735 <ul class="params">
\r
737 <code class="paramname">message1[, message2...]</code>
\r
740 <code class="paramname">exception</code>
\r
741 [<em>optional</em>]
\r
744 <div class="summary">
\r
745 Logs one or more messages and optionally an error at level <code>WARN</code>.
\r
747 <p><strong>Notes</strong></p>
\r
750 Logging of multiple messages in one call is new in 1.4.
\r
754 <li class="method">
\r
755 <div class="name">error</div>
\r
756 <div class="methodsignature"><code>void <strong>error</strong>(Object <em>message1</em>[, Object <em>message2</em>, ... ][, Error <em>exception</em>])</code></div>
\r
757 <div class="paramsheading">Parameters:</div>
\r
758 <ul class="params">
\r
760 <code class="paramname">message1[, message2...]</code>
\r
763 <code class="paramname">exception</code>
\r
764 [<em>optional</em>]
\r
767 <div class="summary">
\r
768 Logs one or more messages and optionally an error at level <code>ERROR</code>.
\r
770 <p><strong>Notes</strong></p>
\r
773 Logging of multiple messages in one call is new in 1.4.
\r
777 <li class="method">
\r
778 <div class="name">fatal</div>
\r
779 <div class="methodsignature"><code>void <strong>fatal</strong>(Object <em>message1</em>[, Object <em>message2</em>, ... ][, Error <em>exception</em>])</code></div>
\r
780 <div class="paramsheading">Parameters:</div>
\r
781 <ul class="params">
\r
783 <code class="paramname">message1[, message2...]</code>
\r
786 <code class="paramname">exception</code>
\r
787 [<em>optional</em>]
\r
790 <div class="summary">
\r
791 Logs one or more messages and optionally an error at level <code>FATAL</code>.
\r
793 <p><strong>Notes</strong></p>
\r
796 Logging of multiple messages in one call is new in 1.4.
\r
800 <li class="method">
\r
801 <div class="name">isEnabledFor</div>
\r
802 <div class="methodsignature"><code>Boolean <strong>isEnabledFor</strong>(Level <em>level</em>, Error <em>exception</em>)</code></div>
\r
803 <div class="paramsheading">Parameters:</div>
\r
804 <ul class="params">
\r
806 <code class="paramname">level</code>
\r
809 <div class="summary">
\r
810 Returns whether the logger is enabled for the specified level.
\r
813 <li class="method">
\r
814 <div class="name">isTraceEnabled</div>
\r
815 <div class="methodsignature"><code>Boolean <strong>isTraceEnabled</strong>()</code></div>
\r
816 <div class="summary">
\r
817 Returns whether the logger is enabled for <code>TRACE</code> messages.
\r
820 <li class="method">
\r
821 <div class="name">isDebugEnabled</div>
\r
822 <div class="methodsignature"><code>Boolean <strong>isDebugEnabled</strong>()</code></div>
\r
823 <div class="summary">
\r
824 Returns whether the logger is enabled for <code>DEBUG</code> messages.
\r
827 <li class="method">
\r
828 <div class="name">isInfoEnabled</div>
\r
829 <div class="methodsignature"><code>Boolean <strong>isInfoEnabled</strong>()</code></div>
\r
830 <div class="summary">
\r
831 Returns whether the logger is enabled for <code>INFO</code> messages.
\r
834 <li class="method">
\r
835 <div class="name">isWarnEnabled</div>
\r
836 <div class="methodsignature"><code>Boolean <strong>isWarnEnabled</strong>()</code></div>
\r
837 <div class="summary">
\r
838 Returns whether the logger is enabled for <code>WARN</code> messages.
\r
841 <li class="method">
\r
842 <div class="name">isErrorEnabled</div>
\r
843 <div class="methodsignature"><code>Boolean <strong>isErrorEnabled</strong>()</code></div>
\r
844 <div class="summary">
\r
845 Returns whether the logger is enabled for <code>ERROR</code> messages.
\r
848 <li class="method">
\r
849 <div class="name">isFatalEnabled</div>
\r
850 <div class="methodsignature"><code>Boolean <strong>isFatalEnabled</strong>()</code></div>
\r
851 <div class="summary">
\r
852 Returns whether the logger is enabled for <code>FATAL</code> messages.
\r
855 <li class="method">
\r
856 <div class="name">group</div>
\r
857 <div class="methodsignature"><code>void <strong>group</strong>(String <em>name</em>, Boolean <em>initiallyExpanded</em>)</code></div>
\r
858 <div class="paramsheading">Parameters:</div>
\r
859 <ul class="params">
\r
861 <code class="paramname">name</code>
\r
864 <code class="paramname">initiallyExpanded</code>
\r
865 [<em>optional</em>]
\r
868 <div class="summary">
\r
869 Starts a new group of log messages. In appenders that support grouping (currently
\r
870 <code><a href="#popupappender">PopUpAppender</a></code> and
\r
871 <code><a href="#inpageappender">InPageAppender</a></code>), a group appears as an expandable
\r
872 section in the console, labelled with the <code>name</code> specified.
\r
873 Specifying <code>initiallyExpanded</code> determines whether the
\r
874 group starts off expanded (the default is <code>true</code>). Groups may be nested.
\r
877 <li class="method">
\r
878 <div class="name">groupEnd</div>
\r
879 <div class="methodsignature"><code>void <strong>groupEnd</strong>()</code></div>
\r
880 <div class="summary">
\r
881 Ends the current group. If there is no group then this function has no effect.
\r
884 <li class="method">
\r
885 <div class="name">time</div>
\r
886 <div class="methodsignature"><code>void <strong>time</strong>(String <em>name</em>, Level <em>level</em>)</code></div>
\r
887 <div class="paramsheading">Parameters:</div>
\r
888 <ul class="params">
\r
890 <code class="paramname">name</code>
\r
893 <code class="paramname">level</code>
\r
894 [<em>optional</em>]
\r
897 <div class="summary">
\r
898 Starts a timer with name <code>name</code>. When the timer is ended with a
\r
899 call to <code>timeEnd</code> using the same name, the amount of time that
\r
900 has elapsed in milliseconds since the timer was started is logged at level
\r
901 <code>level</code>. If not level is supplied, the level defaults to <code>INFO</code>.
\r
904 <li class="method">
\r
905 <div class="name">timeEnd</div>
\r
906 <div class="methodsignature"><code>void <strong>timeEnd</strong>(String <em>name</em>)</code></div>
\r
907 <div class="paramsheading">Parameters:</div>
\r
908 <ul class="params">
\r
910 <code class="paramname">name</code>
\r
913 <div class="summary">
\r
914 Ends the timer with name <code>name</code> and logs the time elapsed.
\r
917 <li class="method">
\r
918 <div class="name">assert</div>
\r
919 <div class="methodsignature"><code>void <strong>assert</strong>(Object <em>expr</em>)</code></div>
\r
920 <div class="paramsheading">Parameters:</div>
\r
921 <ul class="params">
\r
923 <code class="paramname">expr</code>
\r
926 <div class="summary">
\r
927 Asserts the given expression is <code>true</code> or evaluates to <code>true</code>.
\r
928 If so, nothing is logged. If not, an error is logged at the <code>ERROR</code> level.
\r
932 <p class="linktotop">
\r
933 <a href="#container">Top</a>
\r
936 <div id="appenders">
\r
938 <div id="appender">
\r
941 There are methods common to all appenders, as listed below.
\r
944 <ul class="propertieslist">
\r
945 <li class="method">
\r
946 <div class="name">doAppend</div>
\r
947 <div class="methodsignature"><code>void <strong>doAppend</strong>(LoggingEvent <em>loggingEvent</em>)</code></div>
\r
948 <div class="paramsheading">Parameters:</div>
\r
949 <ul class="params">
\r
951 <code class="paramname">loggingEvent</code>
\r
954 <div class="summary">
\r
956 Checks the logging event's level is at least as severe as the appender's
\r
957 threshold and calls the appender's <code>append</code> method if so.
\r
960 This method should not in general be used directly or overridden.
\r
964 <li class="method">
\r
965 <div class="name">append</div>
\r
966 <div class="methodsignature"><code>void <strong>append</strong>(LoggingEvent <em>loggingEvent</em>)</code></div>
\r
967 <div class="paramsheading">Parameters:</div>
\r
968 <ul class="params">
\r
970 <code class="paramname">loggingEvent</code>
\r
973 <div class="summary">
\r
974 Appender-specific method to append a log message. Every appender object should implement
\r
978 <li class="method">
\r
979 <div class="name">setLayout</div>
\r
980 <div class="methodsignature"><code>void <strong>setLayout</strong>(Layout <em>layout</em>)</code></div>
\r
981 <div class="paramsheading">Parameters:</div>
\r
982 <ul class="params">
\r
984 <code class="paramname">layout</code>
\r
987 <div class="summary">
\r
988 Sets the appender's layout.
\r
991 <li class="method">
\r
992 <div class="name">getLayout</div>
\r
993 <div class="methodsignature"><code>Layout <strong>getLayout</strong>()</code></div>
\r
994 <div class="summary">
\r
995 Returns the appender's layout.
\r
998 <li class="method">
\r
999 <div class="name">setThreshold</div>
\r
1000 <div class="methodsignature"><code>void <strong>setThreshold</strong>(Level <em>level</em>)</code></div>
\r
1001 <div class="paramsheading">Parameters:</div>
\r
1002 <ul class="params">
\r
1003 <li class="param">
\r
1004 <code class="paramname">level</code>
\r
1007 <div class="summary">
\r
1008 Sets the appender's threshold. Log messages of level less severe than this
\r
1009 threshold will not be logged.
\r
1012 <li class="method">
\r
1013 <div class="name">getThreshold</div>
\r
1014 <div class="methodsignature"><code>Level <strong>getThreshold</strong>()</code></div>
\r
1015 <div class="summary">
\r
1016 Returns the appender's threshold.
\r
1019 <li class="method">
\r
1020 <div class="name">toString</div>
\r
1021 <div class="methodsignature"><code>string <strong>toString</strong>()</code></div>
\r
1022 <div class="summary">
\r
1023 Returns a string representation of the appender. Every appender object should implement
\r
1028 <p class="linktotop">
\r
1029 <a href="#container">Top</a>
\r
1032 <div id="alertappender">
\r
1033 <h3>AlertAppender</h3>
\r
1034 <p class="editions">Editions: <strong>Standard</strong></p>
\r
1036 Displays a log message as a JavaScript alert.
\r
1038 <h4>Constructor</h4>
\r
1039 <ul class="propertieslist">
\r
1040 <li class="method">
\r
1041 <div class="name">AlertAppender</div>
\r
1042 <div class="methodsignature"><code><strong>AlertAppender</strong>()</code></div>
\r
1045 <p class="linktotop">
\r
1046 <a href="#container">Top</a>
\r
1049 <div id="ajaxappender">
\r
1050 <h3>AjaxAppender</h3>
\r
1051 <p class="editions">Editions: <strong>Standard, Production</strong></p>
\r
1053 A flexible appender that asynchronously sends log messages to a server via HTTP
\r
1054 (Ajax, if you insist, though the 'x' of Ajax only comes into play in any form if you use an
\r
1055 <code><a href="#xmllayout">XmlLayout</a></code>).
\r
1058 The default configuration is to send each log message as a separate HTTP post
\r
1059 request to the server using an <code><a href="#httppostdatalayout">HttpPostDataLayout</a></code>,
\r
1060 without waiting for a response before sending any subsequent requests. However,
\r
1061 an <code>AjaxAppender</code> may be configured to do any one of or combinations of the following:
\r
1065 send log messages in batches (if the selected layout supports it - particularly suited
\r
1066 to <code>AjaxAppender</code> are <code><a href="#jsonlayout">JsonLayout</a></code> and
\r
1067 <code><a href="#xmllayout">XmlLayout</a></code>, both of which allow batching);
\r
1070 wait for a response from a previous request before sending the next log message / batch
\r
1074 send all queued log messages at timed intervals.
\r
1077 <p><strong>Notes</strong></p>
\r
1080 AjaxAppender relies on the <code>XMLHttpRequest</code> object. It also requires
\r
1081 the presence of correctly implemented <code>setRequestHeader</code> method on
\r
1082 this object, which rules out Opera prior to version 8.01. If your browser does not
\r
1083 support the necessary objects then one alert will display to explain why it
\r
1084 doesn't work, after which the appender will silently switch off.
\r
1087 In AjaxAppender only, <code>setLayout</code> may not be called after the first
\r
1088 message has been logged.
\r
1091 The default layout is <code><a href="#httppostdatalayout">HttpPostDataLayout</a></code>.
\r
1094 From version 1.4, log message data is always sent as one or more name/value pairs.
\r
1095 In the case of <code><a href="#httppostdatalayout">HttpPostDataLayout</a></code>, data
\r
1096 is sent the same as in previous versions. For other layouts such as
\r
1097 <code><a href="#jsonlayout">JsonLayout</a></code> and
\r
1098 <code><a href="#xmllayout">XmlLayout</a></code>, the formatted log message is posted as
\r
1099 the value of a parameter called <code>data</code>, though this may be changed via
\r
1100 <code>setPostVarName</code>.
\r
1103 From version 1.4, log message timestamps are sent as standard JavaScript times, i.e.
\r
1104 the number of milliseconds since 00:00:00 UTC on January 1, 1970.
\r
1108 Also from version 1.4, any outstanding log messages may optionally be sent when the
\r
1109 main page unloads (i.e. user follows a link, closes the window or refreshes the
\r
1110 page). This behaviour may be enabled using <code>setSendAllOnUnload</code>; see
\r
1114 This behaviour is dependent on <code>window.onbeforeunload</code>; unfortunately,
\r
1115 Opera does not always raise this event, so this feature does not work reliably in
\r
1120 <h4>Constructor</h4>
\r
1121 <ul class="propertieslist">
\r
1122 <li class="method">
\r
1123 <div class="name">AjaxAppender</div>
\r
1124 <div class="methodsignature">
\r
1125 <code><strong>AjaxAppender</strong>(String <em>url</em>)</code>
\r
1127 <div class="paramsheading">Parameters:</div>
\r
1128 <ul class="params">
\r
1129 <li class="param">
\r
1130 <code class="paramname">url</code>
\r
1132 The URL to which log messages should be sent. Note that this is subject
\r
1133 to the usual Ajax restrictions: the URL should be in the same domain as that
\r
1134 of the page making the request.
\r
1141 <ul class="propertieslist">
\r
1142 <li class="method">
\r
1143 <div class="name">setSendAllOnUnload</div>
\r
1144 <div class="methodsignature"><code>void <strong>setSendAllOnUnload</strong>(Boolean <em>sendAllOnUnload</em>)</code></div>
\r
1145 <div class="summary">
\r
1147 [<em>not available after first message logged</em>]
\r
1150 Whether to send all remaining unsent log messages to the server when the page
\r
1154 Since version 1.4.3, the default value is <code>false</code>. Previously the
\r
1155 default was <code>true</code>.
\r
1157 <p><strong>Notes</strong></p>
\r
1160 This feature was found not to work prior to version 1.4.3 in WebKit
\r
1161 browsers (e.g. Google Chrome, Safari). As a result, a workaround was
\r
1162 implemented in 1.4.3 which has the unfortunate side effect of popping up a
\r
1163 confirmation dialog to the user if there are any log messages to send when
\r
1164 the page unloads. As a result, this feature is now obtrusive for the user
\r
1165 and is therefore disabled by default.
\r
1168 This feature does not work in any version of Opera.
\r
1173 <li class="method">
\r
1174 <div class="name">isSendAllOnUnload</div>
\r
1175 <div class="methodsignature"><code>Boolean <strong>isSendAllOnUnload</strong>()</code></div>
\r
1176 <div class="summary">
\r
1177 Returns whether all remaining unsent log messages are sent to the server when the page unloads.
\r
1180 <li class="method">
\r
1181 <div class="name">setPostVarName</div>
\r
1182 <div class="methodsignature"><code>void <strong>setPostVarName</strong>(String <em>postVarName</em>)</code></div>
\r
1183 <div class="summary">
\r
1185 [<em>not available after first message logged</em>]
\r
1188 Sets the post variable name whose value will the formatted log message(s) for
\r
1192 Default value is <code>data</code>.
\r
1194 <p><strong>Notes</strong></p>
\r
1197 This has no effect if the current layout is an
\r
1198 <code><a href="#httppostdatalayout">HttpPostDataLayout</a></code>.
\r
1203 <li class="method">
\r
1204 <div class="name">getPostVarName</div>
\r
1205 <div class="methodsignature"><code>String <strong>getPostVarName</strong>()</code></div>
\r
1206 <div class="summary">
\r
1207 Returns the post variable name whose value will the formatted log message(s) for
\r
1211 <li class="method">
\r
1212 <div class="name">setTimed</div>
\r
1213 <div class="methodsignature"><code>void <strong>setTimed</strong>(Boolean <em>timed</em>)</code></div>
\r
1214 <div class="summary">
\r
1216 [<em>not available after first message logged</em>]
\r
1219 Whether to send log messages to the server at regular, timed intervals.
\r
1222 Default value is <code>false</code>.
\r
1226 <li class="method">
\r
1227 <div class="name">isTimed</div>
\r
1228 <div class="methodsignature"><code>Boolean <strong>isTimed</strong>()</code></div>
\r
1229 <div class="summary">
\r
1230 Returns whether log messages are sent to the server at regular, timed intervals.
\r
1233 <li class="method">
\r
1234 <div class="name">setWaitForResponse</div>
\r
1235 <div class="methodsignature"><code>void <strong>setWaitForResponse</strong>(Boolean <em>waitForResponse</em>)</code></div>
\r
1236 <div class="summary">
\r
1238 [<em>not available after first message logged</em>]
\r
1241 Sets whether to wait for a response from a previous HTTP request from this
\r
1242 appender before sending the next log message / batch of messages.
\r
1245 Default value is <code>false</code>.
\r
1249 <li class="method">
\r
1250 <div class="name">isWaitForResponse</div>
\r
1251 <div class="methodsignature"><code>Boolean <strong>isWaitForResponse</strong>()</code></div>
\r
1252 <div class="summary">
\r
1253 Returns whether the appender waits for a response from a previous HTTP request from this
\r
1254 appender before sending the next log message / batch of messages.
\r
1257 <li class="method">
\r
1258 <div class="name">setBatchSize</div>
\r
1259 <div class="methodsignature"><code>void <strong>setBatchSize</strong>(Number <em>batchSize</em>)</code></div>
\r
1260 <div class="summary">
\r
1262 [<em>not available after first message logged</em>]
\r
1265 Sets the number of log messages to send in each request. If not specified,
\r
1266 defaults to <code>1</code>.
\r
1268 <p><strong>Notes</strong></p>
\r
1271 Setting this to a number greater than 1 means that the appender will wait
\r
1272 until it has forwarded that many valid log messages before sending any more.
\r
1273 This also means that if the page unloads for any reason and <code>sendAllOnUnload</code>
\r
1274 is not set to <code>true</code>, any log messages waiting in the queue will not be sent.
\r
1277 If batching is used in conjunction with timed sending of log messages,
\r
1278 messages will still be sent in batches of size <code>batchSize</code>,
\r
1279 regardless of how many log messages are queued by the time the timed
\r
1280 sending is invoked. Incomplete batches will not be sent except when the
\r
1281 page unloads, if <code>sendAllOnUnload</code> is set to <code>true</code>.
\r
1286 <li class="method">
\r
1287 <div class="name">getBatchSize</div>
\r
1288 <div class="methodsignature"><code>Number <strong>getBatchSize</strong>()</code></div>
\r
1289 <div class="summary">
\r
1290 Returns the number of log messages sent in each request. See above for more details.
\r
1293 <li class="method">
\r
1294 <div class="name">setTimerInterval</div>
\r
1295 <div class="methodsignature"><code>void <strong>setTimerInterval</strong>(Number <em>timerInterval</em>)</code></div>
\r
1296 <div class="summary">
\r
1298 [<em>not available after first message logged</em>]
\r
1301 Sets the length of time in milliseconds between each sending of queued log
\r
1304 <p><strong>Notes</strong></p>
\r
1307 <code>timerInterval</code> only has an effect in conjunction with
\r
1308 <code>timed</code> (set by <code>setTimed()</code>. If <code>timed</code>
\r
1309 is set to false then <code>timerInterval</code> has no effect.
\r
1312 Each time the queue of log messages or batches of messages is cleared,
\r
1313 the countdown to the next sending only starts once the final request
\r
1314 has been sent (and, if <code>waitForResponse</code> is set to <code>true</code>,
\r
1315 the final response received). This means that the actual interval at
\r
1316 which the queue of messages is cleared cannot be fixed.
\r
1321 <li class="method">
\r
1322 <div class="name">getTimerInterval</div>
\r
1323 <div class="methodsignature"><code>Number <strong>getTimerInterval</strong>()</code></div>
\r
1324 <div class="summary">
\r
1325 Returns the length of time in milliseconds between each sending of queued log
\r
1326 messages. See above for more details.
\r
1329 <li class="method">
\r
1330 <div class="name">setRequestSuccessCallback</div>
\r
1331 <div class="methodsignature"><code>void <strong>setRequestSuccessCallback</strong>(Function <em>requestSuccessCallback</em>)</code></div>
\r
1332 <div class="summary">
\r
1334 Sets the function that is called whenever a successful request is made, called at the
\r
1335 point at which the response is received. This feature can be used to confirm
\r
1336 whether a request has been successful and act accordingly.
\r
1339 A single parameter, <code>xmlHttp</code>, is passed to the callback function.
\r
1340 This is the XMLHttpRequest object that performed the request.
\r
1344 <li class="method">
\r
1345 <div class="name">setFailCallback</div>
\r
1346 <div class="methodsignature"><code>void <strong>setFailCallback</strong>(Function <em>failCallback</em>)</code></div>
\r
1347 <div class="summary">
\r
1349 Sets the function that is called whenever any kind of failure occurs in the appender,
\r
1350 including browser deficiencies or configuration errors (e.g. supplying a
\r
1351 non-existent URL to the appender). This feature can be used to handle
\r
1352 AjaxAppender-specific errors.
\r
1355 A single parameter, <code>message</code>, is passed to the callback function.
\r
1356 This is the error-specific message that caused the failure.
\r
1360 <li class="method">
\r
1361 <div class="name">setSessionId</div>
\r
1362 <div class="methodsignature"><code>void <strong>setSessionId</strong>(String <em>sessionId</em>)</code></div>
\r
1363 <div class="summary">
\r
1364 Sets the session id sent to the server each time a request is made.
\r
1367 <li class="method">
\r
1368 <div class="name">getSessionId</div>
\r
1369 <div class="methodsignature"><code>String <strong>getSessionId</strong>()</code></div>
\r
1370 <div class="summary">
\r
1371 Returns the session id sent to the server each time a request is made.
\r
1374 <li class="method">
\r
1375 <div class="name">addHeader</div>
\r
1376 <div class="methodsignature"><code>void <strong>addHeader</strong>(String <em>name</em>,
\r
1377 String <em>value</em>)</code></div>
\r
1378 <div class="summary">
\r
1380 Adds an HTTP header that is sent with each request.
\r
1383 <strong>Since: 1.4.3</strong>
\r
1387 <li class="method">
\r
1388 <div class="name">getHeaders</div>
\r
1389 <div class="methodsignature"><code>Array <strong>getHeaders</strong>()</code></div>
\r
1390 <div class="summary">
\r
1391 Returns an array of the additional headers that are sent with each HTTP request.
\r
1392 Each array item is an object with properties <code>name</code> and
\r
1393 <code>value</code>.
\r
1395 <strong>Since: 1.4.3</strong>
\r
1399 <li class="method">
\r
1400 <div class="name">sendAll</div>
\r
1401 <div class="methodsignature"><code>void <strong>sendAll</strong>()</code></div>
\r
1402 <div class="summary">
\r
1403 Sends all log messages in the queue. If log messages are batched then only completed
\r
1408 <p class="linktotop">
\r
1409 <a href="#container">Top</a>
\r
1412 <div id="popupappender">
\r
1413 <h3>PopUpAppender</h3>
\r
1414 <p class="editions">Editions: <strong>Standard</strong></p>
\r
1416 Logs messages to a pop-up console window (note: you will need to disable pop-up
\r
1417 blockers to use it). The pop-up displays a list of all log messages, and has
\r
1418 the following features:
\r
1421 <li>log messages are colour-coded by severity;</li>
\r
1422 <li>log messages are displayed in a monospace font to allow easy readability;</li>
\r
1423 <li>switchable wrap mode to allow wrapping of long lines</li>
\r
1424 <li>all whitespace in log messages is honoured (except in wrap mode);</li>
\r
1425 <li>filters to show and hide messages of a particular level;</li>
\r
1427 search facility that allows searching of log messages as you type, with the
\r
1428 following features:
\r
1430 <li>supports regular expressions;</li>
\r
1431 <li>case sensitive or insensitive matching;</li>
\r
1432 <li>buttons to navigate through all the matches;</li>
\r
1433 <li>switch to highlight all matches;</li>
\r
1434 <li>switch to filter out all log messages that contain no matches;</li>
\r
1435 <li>switch to enable or disable the search;</li>
\r
1436 <li>search is dynamically applied to every log message as it is added to the console.</li>
\r
1439 <li>switch to toggle between logging from the top down and from the bottom up;</li>
\r
1440 <li>switch to turn automatic scrolling when a new message is logged on and off;</li>
\r
1441 <li>switch to turn off all logging to the pop-up (useful if a timer is generating unwanted log messages);</li>
\r
1442 <li>optional configurable limit to the number of log message that are displayed. If
\r
1443 set and this limit is reached, each new log message will cause the oldest one to
\r
1444 be discarded;</li>
\r
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>
\r
1446 <li>clear button to allow user to delete all current log messages.</li>
\r
1448 command prompt with up/down arrow history. Command line functions may be added
\r
1449 to the appender. Several command line functions are built in:
\r
1450 <ul class="propertieslist">
\r
1451 <li class="method">
\r
1452 <div class="methodsignature"><code><strong>$</strong>(String <em>id</em>)</code></div>
\r
1453 <div class="summary">
\r
1454 Prints a string representation of a single element with the id supplied.
\r
1457 <li class="method">
\r
1458 <div class="methodsignature"><code><strong>dir</strong>(Object <em>obj</em>)</code></div>
\r
1459 <div class="summary">
\r
1460 Prints a list of a properties of the object supplied.
\r
1463 <li class="method">
\r
1464 <div class="methodsignature"><code><strong>dirxml</strong>(HTMLElement <em>el</em>)</code></div>
\r
1465 <div class="summary">
\r
1466 Prints the XML source code of an HTML or XML element
\r
1469 <li class="method">
\r
1470 <div class="methodsignature"><code><strong>cd</strong>(Object <em>win</em>)</code></div>
\r
1471 <div class="summary">
\r
1472 Changes the scope of execution of commands to the named frame or window (either a
\r
1473 window/frame name or a reference to a window object may be supplied).
\r
1476 <li class="method">
\r
1477 <div class="methodsignature"><code><strong>clear</strong>()</code></div>
\r
1478 <div class="summary">
\r
1479 Clears the console.
\r
1482 <li class="method">
\r
1483 <div class="methodsignature"><code><strong>keys</strong>(Object <em>obj</em>)</code></div>
\r
1484 <div class="summary">
\r
1485 Prints a list of the names of all properties of the object supplied.
\r
1488 <li class="method">
\r
1489 <div class="methodsignature"><code><strong>values</strong>(Object <em>obj</em>)</code></div>
\r
1490 <div class="summary">
\r
1491 Prints a list of the values of all properties of the object supplied.
\r
1494 <li class="method">
\r
1495 <div class="methodsignature"><code><strong>expansionDepth</strong>(Number <em>depth</em>)</code></div>
\r
1496 <div class="summary">
\r
1497 Sets the number of levels of expansion of objects that are displayed by
\r
1498 the command line. The default value is 1.
\r
1504 <p><strong>Notes</strong></p>
\r
1508 The default layout for this appender is <code><a href="#patternlayout">PatternLayout</a></code>
\r
1509 with pattern string
\r
1512 <code>%d{HH:mm:ss} %-5p - %m{1}%n</code>
\r
1516 <h4>Constructor</h4>
\r
1517 <ul class="propertieslist">
\r
1518 <li class="method">
\r
1519 <div class="name">PopUpAppender</div>
\r
1520 <div class="methodsignature">
\r
1521 <code><strong>PopUpAppender</strong>([Boolean <em>lazyInit</em>,
\r
1522 Boolean <em>initiallyMinimized</em>, Boolean <em>useDocumentWrite</em>,
\r
1523 Number <em>width</em>, Number <em>height</em>])</code>
\r
1525 <div class="paramsheading">Parameters:</div>
\r
1526 <ul class="params">
\r
1527 <li class="param">
\r
1528 <code class="paramname">lazyInit</code>
\r
1529 [<em>optional</em>]
\r
1531 Set this to <code>true</code> to open the pop-up only when the first log
\r
1532 message reaches the appender. Otherwise, the pop-up window opens as soon as the
\r
1533 appender is created. If not specified, defaults to <code>false</code>.
\r
1536 <li class="param">
\r
1537 <code class="paramname">initiallyMinimized</code>
\r
1538 [<em>optional</em>]
\r
1541 Whether the console window should start off hidden / minimized.
\r
1542 If not specified, defaults to <code>false</code>.
\r
1546 <li class="param">
\r
1547 <code class="paramname">useDocumentWrite</code>
\r
1548 [<em>optional</em>]
\r
1551 Specifies how the console window is created. By default, the console window is
\r
1552 created dynamically using <code>document</code>'s <code>write</code> method. This has the
\r
1553 advantage of keeping all the code in one single JavaScript file. However, if your
\r
1554 page sets <code>document.domain</code> then the browser prevents script access to
\r
1555 a window unless it too has the same value set for <code>document.domain</code>. To
\r
1556 get round this issue, you can set <code>useDocumentWrite</code> to <code>false</code>
\r
1557 and log4javascript will instead use the external HTML file <code>console.html</code>
\r
1558 (or <code>console_uncompressed.html</code> if you're using an uncompressed version of
\r
1559 log4javascript.js), which must be placed in the same directory as your log4javascript.js file.
\r
1562 Note that if <code>useDocumentWrite</code> is set to <code>true</code>, the old pop-up
\r
1563 window will always be closed and a new one created whenever the page is refreshed, even
\r
1564 if <code>setUseOldPopUp(true)</code> has been called.
\r
1567 In general it's simpler to use the <code>document.write</code> method, so unless your
\r
1568 page needs to set <code>document.domain</code>, <code>useDocumentWrite</code> should
\r
1569 be set to <code>true</code>.
\r
1572 If not specified, defaults to <code>true</code>.
\r
1576 <li class="param">
\r
1577 <code class="paramname">width</code>
\r
1578 [<em>optional</em>]
\r
1580 The outer width in pixels of the pop-up window. If not specified,
\r
1581 defaults to <code>600</code>.
\r
1584 <li class="param">
\r
1585 <code class="paramname">height</code>
\r
1586 [<em>optional</em>]
\r
1588 The outer height in pixels of the pop-up window. If not specified,
\r
1589 defaults to <code>400</code>.
\r
1596 <ul class="propertieslist">
\r
1597 <li class="method">
\r
1598 <div class="name">isInitiallyMinimized</div>
\r
1599 <div class="methodsignature"><code>Boolean <strong>isInitiallyMinimized</strong>()</code></div>
\r
1600 <div class="summary">
\r
1601 Returns whether the console window starts off hidden / minimized.
\r
1604 <li class="method">
\r
1605 <div class="name">setInitiallyMinimized</div>
\r
1606 <div class="methodsignature"><code>void <strong>setInitiallyMinimized</strong>(Boolean <em>initiallyMinimized</em>)</code></div>
\r
1607 <div class="summary">
\r
1608 [<em>not available after initialization</em>]
\r
1610 Sets whether the console window should start off hidden / minimized.
\r
1613 <li class="method">
\r
1614 <div class="name">isFocusPopUp</div>
\r
1615 <div class="methodsignature"><code>Boolean <strong>isFocusPopUp</strong>()</code></div>
\r
1616 <div class="summary">
\r
1617 Returns whether the pop-up window is focussed (i.e. brought it to the front)
\r
1618 when a new log message is added. Default value is <code>false</code>.
\r
1621 <li class="method">
\r
1622 <div class="name">setFocusPopUp</div>
\r
1623 <div class="methodsignature"><code>void <strong>setFocusPopUp</strong>(Boolean <em>focusPopUp</em>)</code></div>
\r
1624 <div class="summary">
\r
1625 Sets whether to focus the pop-up window (i.e. bring it to the front)
\r
1626 when a new log message is added.
\r
1629 <li class="method">
\r
1630 <div class="name">isUseOldPopUp</div>
\r
1631 <div class="methodsignature"><code>Boolean <strong>isUseOldPopUp</strong>()</code></div>
\r
1632 <div class="summary">
\r
1634 Returns whether the same pop-up window is used if the main page is
\r
1635 reloaded. If set to <code>true</code>, when the page is reloaded
\r
1636 a line is drawn in the pop-up and subsequent log messages are added
\r
1637 to the same pop-up. Otherwise, a new pop-up window is created that
\r
1638 replaces the original pop-up. If not specified, defaults to
\r
1639 <code>true</code>.
\r
1641 <p><strong>Notes</strong></p>
\r
1644 In Internet Explorer 5, the browser prevents this from working
\r
1645 properly, so a new pop-up window is always created when the main
\r
1646 page reloads. Also, the original pop-up does not get closed.
\r
1651 <li class="method">
\r
1652 <div class="name">setUseOldPopUp</div>
\r
1653 <div class="methodsignature"><code>void <strong>setUseOldPopUp</strong>(Boolean <em>useOldPopUp</em>)</code></div>
\r
1654 <div class="summary">
\r
1655 [<em>not available after initialization</em>]
\r
1657 Sets whether to use the same pop-up window if the main page is reloaded.
\r
1658 See <code>isUseOldPopUp</code> above for details.
\r
1661 <li class="method">
\r
1662 <div class="name">isComplainAboutPopUpBlocking</div>
\r
1663 <div class="methodsignature"><code>Boolean <strong>isComplainAboutPopUpBlocking</strong>()</code></div>
\r
1664 <div class="summary">
\r
1665 Returns whether an alert is shown to the user when the pop-up window
\r
1666 cannot be created as a result of a pop-up blocker. Default value is <code>true</code>.
\r
1669 <li class="method">
\r
1670 <div class="name">setComplainAboutPopUpBlocking</div>
\r
1671 <div class="methodsignature"><code>void <strong>setComplainAboutPopUpBlocking</strong>(Boolean <em>complainAboutPopUpBlocking</em>)</code></div>
\r
1672 <div class="summary">
\r
1673 [<em>not available after initialization</em>]
\r
1675 Sets whether to announce to show an alert to the user when the pop-up window
\r
1676 cannot be created as a result of a pop-up blocker.
\r
1679 <li class="method">
\r
1680 <div class="name">isNewestMessageAtTop</div>
\r
1681 <div class="methodsignature"><code>Boolean <strong>isNewestMessageAtTop</strong>()</code></div>
\r
1682 <div class="summary">
\r
1683 Returns whether new log messages are displayed at the top of the pop-up window.
\r
1684 Default value is <code>false</code> (i.e. log messages are appended to the bottom of the window).
\r
1687 <li class="method">
\r
1688 <div class="name">setNewestMessageAtTop</div>
\r
1689 <div class="methodsignature"><code>void <strong>setNewestMessageAtTop</strong>(Boolean <em>newestMessageAtTop</em>)</code></div>
\r
1690 <div class="summary">
\r
1691 Sets whether to display new log messages at the top inside the pop-up window.
\r
1694 <li class="method">
\r
1695 <div class="name">isScrollToLatestMessage</div>
\r
1696 <div class="methodsignature"><code>Boolean <strong>isScrollToLatestMessage</strong>()</code></div>
\r
1697 <div class="summary">
\r
1698 Returns whether the pop-up window scrolls to display the latest log message when a new message
\r
1699 is logged. Default value is <code>true</code>.
\r
1702 <li class="method">
\r
1703 <div class="name">setScrollToLatestMessage</div>
\r
1704 <div class="methodsignature"><code>void <strong>setScrollToLatestMessage</strong>(Boolean <em>scrollToLatestMessage</em>)</code></div>
\r
1705 <div class="summary">
\r
1706 Sets whether to scroll the pop-up window to display the latest log message when a new message
\r
1710 <li class="method">
\r
1711 <div class="name">isReopenWhenClosed</div>
\r
1712 <div class="methodsignature"><code>Boolean <strong>isReopenWhenClosed</strong>()</code></div>
\r
1713 <div class="summary">
\r
1714 Returns whether the pop-up window reopens automatically after being closed when a new log message is logged.
\r
1715 Default value is <code>false</code>.
\r
1718 <li class="method">
\r
1719 <div class="name">setReopenWhenClosed</div>
\r
1720 <div class="methodsignature"><code>void <strong>setReopenWhenClosed</strong>(Boolean <em>reopenWhenClosed</em>)</code></div>
\r
1721 <div class="summary">
\r
1722 Sets whether to reopen the pop-up window automatically after being closed when a new log message is logged.
\r
1725 <li class="method">
\r
1726 <div class="name">getWidth</div>
\r
1727 <div class="methodsignature"><code>Number <strong>getWidth</strong>()</code></div>
\r
1728 <div class="summary">
\r
1729 Returns the outer width in pixels of the pop-up window.
\r
1732 <li class="method">
\r
1733 <div class="name">setWidth</div>
\r
1734 <div class="methodsignature"><code>void <strong>setWidth</strong>(Number <em>width</em>)</code></div>
\r
1735 <div class="summary">
\r
1736 [<em>not available after initialization</em>]
\r
1738 Sets the outer width in pixels of the pop-up window.
\r
1741 <li class="method">
\r
1742 <div class="name">getHeight</div>
\r
1743 <div class="methodsignature"><code>Number <strong>getHeight</strong>()</code></div>
\r
1744 <div class="summary">
\r
1745 [<em>not available after initialization</em>]
\r
1747 Returns the outer height in pixels of the pop-up window.
\r
1750 <li class="method">
\r
1751 <div class="name">setHeight</div>
\r
1752 <div class="methodsignature"><code>void <strong>setHeight</strong>(Number <em>height</em>)</code></div>
\r
1753 <div class="summary">
\r
1754 Sets the outer height in pixels of the pop-up window.
\r
1757 <li class="method">
\r
1758 <div class="name">getMaxMessages</div>
\r
1759 <div class="methodsignature"><code>Number <strong>getMaxMessages</strong>()</code></div>
\r
1760 <div class="summary">
\r
1761 Returns the largest number of log messages that are displayed and stored
\r
1762 by the the console. Once reached, a new log message wil cause the
\r
1763 oldest message to be discarded. Default value is <code>null</code>, which means no
\r
1767 <li class="method">
\r
1768 <div class="name">setMaxMessages</div>
\r
1769 <div class="methodsignature"><code>void <strong>setMaxMessages</strong>(Number <em>maxMessages</em>)</code></div>
\r
1770 <div class="summary">
\r
1771 [<em>not available after initialization</em>]
\r
1773 Sets the largest number of messages displayed and stored by the console window. Set
\r
1774 this to <code>null</code> to make this number unlimited.
\r
1777 <li class="method">
\r
1778 <div class="name">isShowCommandLine</div>
\r
1779 <div class="methodsignature"><code>Boolean <strong>isShowCommandLine</strong>()</code></div>
\r
1780 <div class="summary">
\r
1781 Returns whether the console includes a command line.
\r
1782 Default value is <code>true</code>.
\r
1785 <li class="method">
\r
1786 <div class="name">setShowCommandLine</div>
\r
1787 <div class="methodsignature"><code>void <strong>setShowCommandLine</strong>(Boolean <em>showCommandLine</em>)</code></div>
\r
1788 <div class="summary">
\r
1789 Sets whether the console includes a command line.
\r
1792 <li class="method">
\r
1793 <div class="name">getCommandLineObjectExpansionDepth</div>
\r
1794 <div class="methodsignature"><code>Number <strong>getCommandLineObjectExpansionDepth</strong>()</code></div>
\r
1795 <div class="summary">
\r
1796 Returns the number of levels to expand when an object value is logged to the console.
\r
1797 Each property of an object above this threshold will be expanded if it is itself an object
\r
1798 or array, otherwise its string representation will be displayed. Default value is 1 (i.e.
\r
1799 the properties of the object logged will be displayed in their string representation but
\r
1803 <li class="method">
\r
1804 <div class="name">setCommandLineObjectExpansionDepth:</div>
\r
1805 <div class="methodsignature"><code>void <strong>setCommandLineObjectExpansionDepth</strong>(Number <em>expansionDepth</em>)</code></div>
\r
1806 <div class="summary">
\r
1807 Sets the number of levels to expand when an object value is logged to the console.
\r
1810 <li class="method">
\r
1811 <div class="name">getCommandWindow</div>
\r
1812 <div class="methodsignature"><code>Window <strong>getCommandWindow</strong>()</code></div>
\r
1813 <div class="summary">
\r
1814 Returns a reference to the window in which commands typed into the command line
\r
1815 are currently being executed.
\r
1818 <li class="method">
\r
1819 <div class="name">setCommandWindow</div>
\r
1820 <div class="methodsignature"><code>void <strong>setCommandWindow</strong>(Window <em>commandWindow</em>)</code></div>
\r
1821 <div class="summary">
\r
1822 Sets the window in which commands typed into the command line are executed.
\r
1825 <li class="method">
\r
1826 <div class="name">getCommandLayout</div>
\r
1827 <div class="methodsignature"><code>Number <strong>getCommandLayout</strong>()</code></div>
\r
1828 <div class="summary">
\r
1829 Returns the layout used to format the output for commands typed into the command line.
\r
1830 The default value is a <code><a href="#patternlayout">PatternLayout</a></code> with
\r
1831 pattern string <code>%m</code>
\r
1834 <li class="method">
\r
1835 <div class="name">setCommandLayout</div>
\r
1836 <div class="methodsignature"><code>void <strong>setCommandLayout</strong>(Layout <em>commandLayout</em>)</code></div>
\r
1837 <div class="summary">
\r
1838 Sets the layout used to format the output for commands typed into the command line.
\r
1841 <li class="method">
\r
1842 <div class="name">clear</div>
\r
1843 <div class="methodsignature"><code>void <strong>clear</strong>()</code></div>
\r
1844 <div class="summary">
\r
1845 Clears all messages from the console window.
\r
1848 <li class="method">
\r
1849 <div class="name">close</div>
\r
1850 <div class="methodsignature"><code>void <strong>close</strong>()</code></div>
\r
1851 <div class="summary">
\r
1852 Closes the pop-up window.
\r
1855 <li class="method">
\r
1856 <div class="name">show</div>
\r
1857 <div class="methodsignature"><code>void <strong>show</strong>()</code></div>
\r
1858 <div class="summary">
\r
1859 Opens the pop-up window, if not already open.
\r
1862 <li class="method">
\r
1863 <div class="name">hide</div>
\r
1864 <div class="methodsignature"><code>void <strong>hide</strong>()</code></div>
\r
1865 <div class="summary">
\r
1866 Closes the pop-up window.
\r
1869 <li class="method">
\r
1870 <div class="name">focus</div>
\r
1871 <div class="methodsignature"><code>void <strong>focus</strong>()</code></div>
\r
1872 <div class="summary">
\r
1873 Brings the console window to the top and gives it the focus.
\r
1876 <li class="method">
\r
1877 <div class="name">focusCommandLine</div>
\r
1878 <div class="methodsignature"><code>void <strong>focusCommandLine</strong>()</code></div>
\r
1879 <div class="summary">
\r
1880 Brings the console window to the top and gives the focus to the command line.
\r
1883 <li class="method">
\r
1884 <div class="name">focusSearch</div>
\r
1885 <div class="methodsignature"><code>void <strong>focusSearch</strong>()</code></div>
\r
1886 <div class="summary">
\r
1887 Brings the console window to the top and gives the focus to the search box.
\r
1890 <li class="method">
\r
1891 <div class="name">evalCommandAndAppend</div>
\r
1892 <div class="methodsignature"><code>void <strong>evalCommandAndAppend</strong>(String <em>expr</em>)</code></div>
\r
1893 <div class="summary">
\r
1894 Evaluates the expression and appends the result to the console.
\r
1897 <li class="method">
\r
1898 <div class="name">addCommandLineFunction</div>
\r
1899 <div class="methodsignature"><code>void <strong>addCommandLineFunction</strong>(String <em>functionName</em>, Function <em>commandLineFunction</em>)</code></div>
\r
1900 <div class="summary">
\r
1902 Adds a function with the name specified to the list of functions available on the command line.
\r
1903 This feature may be used to add custom functions to the command line.
\r
1906 When you call the function on the command line, <code>commandLineFunction</code> is executed with the
\r
1907 following three parameters:
\r
1910 <li><em>appender</em>. A reference to the appender in which the command was executed;</li>
\r
1911 <li><em>args</em>.
\r
1912 An array-like list of parameters passed into the function on the command line
\r
1913 (actually a reference to the <code>arguments</code> object representing the parameters passed
\r
1914 into the function by the user);</li>
\r
1915 <li><em>returnValue</em>. This is an object with two properties that allow the function to control
\r
1916 how the result is displayed:
\r
1918 <li><em>appendResult</em>. A boolean value that determines whether the returned value from this
\r
1919 function is appended to the console. The default value is <code>true</code>;</li>
\r
1920 <li><em>isError</em>. A boolean value that specifies whether the output of this function
\r
1921 should be displayed as an error. The default value is <code>false</code>.</li>
\r
1926 The value returned by the function is formatted by the command layout and appended to the console.
\r
1931 <p class="linktotop">
\r
1932 <a href="#container">Top</a>
\r
1935 <div id="inpageappender">
\r
1936 <h3>InPageAppender</h3>
\r
1937 <p class="editions">Editions: <strong>Standard</strong></p>
\r
1939 Logs messages to a console window in the page. The console is identical
\r
1940 to that used by the <code><a href="#popupappender">PopUpAppender</a></code>, except
\r
1941 for the absence of a 'Close' button.
\r
1943 <p><strong>Notes</strong></p>
\r
1946 Prior to log4javascript 1.3, InPageAppender was known as InlineAppender.
\r
1947 For the sake of backwards compatibility, InlineAppender is still included in
\r
1948 1.3 and later as an alias for InPageAppender.
\r
1952 The default layout for this appender is <code><a href="#patternlayout">PatternLayout</a></code>
\r
1953 with pattern string
\r
1956 <code>%d{HH:mm:ss} %-5p - %m{1}%n</code>
\r
1960 <h4>Constructor</h4>
\r
1961 <ul class="propertieslist">
\r
1962 <li class="method">
\r
1963 <div class="name">InPageAppender</div>
\r
1964 <div class="methodsignature">
\r
1965 <code><strong>InPageAppender</strong>(HTMLElement <em>container</em>[,
\r
1966 Boolean <em>lazyInit</em>, Boolean <em>initiallyMinimized</em>,
\r
1967 Boolean <em>useDocumentWrite</em>, String <em>width</em>, String <em>height</em>])</code>
\r
1969 <div class="paramsheading">Parameters:</div>
\r
1970 <ul class="params">
\r
1971 <li class="param">
\r
1972 <code class="paramname">container</code>
\r
1974 The container element for the console window. This should be an HTML element.
\r
1977 <li class="param">
\r
1978 <code class="paramname">lazyInit</code>
\r
1979 [<em>optional</em>]
\r
1981 Set this to <code>true</code> to create the console only when the first log
\r
1982 message reaches the appender. Otherwise, the console is initialized as soon as the
\r
1983 appender is created. If not specified, defaults to <code>true</code>.
\r
1986 <li class="param">
\r
1987 <code class="paramname">initiallyMinimized</code>
\r
1988 [<em>optional</em>]
\r
1991 Whether the console window should start off hidden / minimized.
\r
1992 If not specified, defaults to <code>false</code>.
\r
1994 <p><strong>Notes</strong></p>
\r
1997 In Safari (and possibly other browsers) hiding an <code>iframe</code>
\r
1998 resets its document, thus destroying the console window.
\r
2003 <li class="param">
\r
2004 <code class="paramname">useDocumentWrite</code>
\r
2005 [<em>optional</em>]
\r
2008 Specifies how the console window is created. By default, the console window is
\r
2009 created dynamically using <code>document</code>'s <code>write</code> method. This has the
\r
2010 advantage of keeping all the code in one single JavaScript file. However, if your
\r
2011 page sets <code>document.domain</code> then the browser prevents script access to
\r
2012 a window unless it too has the same value set for <code>document.domain</code>. To
\r
2013 get round this issue, you can set <code>useDocumentWrite</code> to <code>false</code>
\r
2014 and log4javascript will instead use the external HTML file <code>console.html</code>
\r
2015 (or <code>console_uncompressed.html</code> if you're using an uncompressed version of
\r
2016 log4javascript.js), which must be placed in the same directory as your log4javascript.js file.
\r
2019 In general it's simpler to use the <code>document.write</code> method, so unless your
\r
2020 page needs to set <code>document.domain</code>, <code>useDocumentWrite</code> should
\r
2021 be set to <code>true</code>.
\r
2024 If not specified, defaults to <code>true</code>.
\r
2028 <li class="param">
\r
2029 <code class="paramname">width</code>
\r
2030 [<em>optional</em>]
\r
2032 The width of the console window. Any valid CSS length may be used. If not
\r
2033 specified, defaults to <code>100%</code>.
\r
2036 <li class="param">
\r
2037 <code class="paramname">height</code>
\r
2038 [<em>optional</em>]
\r
2040 The height of the console window. Any valid CSS length may be used. If not
\r
2041 specified, defaults to <code>250px</code>.
\r
2048 <ul class="propertieslist">
\r
2049 <li class="method">
\r
2050 <div class="name">addCssProperty</div>
\r
2051 <div class="methodsignature"><code>void <strong>addCssProperty</strong>(String <em>name</em>, String <em>value</em>)</code></div>
\r
2052 <div class="summary">
\r
2053 Sets a CSS style property on the HTML element containing the console iframe.
\r
2056 <li class="method">
\r
2057 <div class="name">isVisible</div>
\r
2058 <div class="methodsignature"><code>Boolean <strong>isVisible</strong>()</code></div>
\r
2059 <div class="summary">
\r
2060 Returns whether the console window is currently visible.
\r
2063 <li class="method">
\r
2064 <div class="name">isInitiallyMinimized</div>
\r
2065 <div class="methodsignature"><code>Boolean <strong>isInitiallyMinimized</strong>()</code></div>
\r
2066 <div class="summary">
\r
2067 Returns whether the console window starts off hidden / minimized.
\r
2070 <li class="method">
\r
2071 <div class="name">setInitiallyMinimized</div>
\r
2072 <div class="methodsignature"><code>void <strong>setInitiallyMinimized</strong>(Boolean <em>initiallyMinimized</em>)</code></div>
\r
2073 <div class="summary">
\r
2074 [<em>not available after initialization</em>]
\r
2076 Sets whether the console window should start off hidden / minimized.
\r
2079 <li class="method">
\r
2080 <div class="name">isNewestMessageAtTop</div>
\r
2081 <div class="methodsignature"><code>Boolean <strong>isNewestMessageAtTop</strong>()</code></div>
\r
2082 <div class="summary">
\r
2083 Returns whether new log messages are displayed at the top of the console window.
\r
2086 <li class="method">
\r
2087 <div class="name">setNewestMessageAtTop</div>
\r
2088 <div class="methodsignature"><code>void <strong>setNewestMessageAtTop</strong>(Boolean <em>newestMessageAtTop</em>)</code></div>
\r
2089 <div class="summary">
\r
2090 Sets whether to display new log messages at the top inside the console window.
\r
2093 <li class="method">
\r
2094 <div class="name">isScrollToLatestMessage</div>
\r
2095 <div class="methodsignature"><code>Boolean <strong>isScrollToLatestMessage</strong>()</code></div>
\r
2096 <div class="summary">
\r
2097 Returns whether the pop-up window scrolls to display the latest log message when a new message
\r
2101 <li class="method">
\r
2102 <div class="name">setScrollToLatestMessage</div>
\r
2103 <div class="methodsignature"><code>void <strong>setScrollToLatestMessage</strong>(Boolean <em>scrollToLatestMessage</em>)</code></div>
\r
2104 <div class="summary">
\r
2105 Sets whether to scroll the console window to display the latest log message when a new message
\r
2109 <li class="method">
\r
2110 <div class="name">getWidth</div>
\r
2111 <div class="methodsignature"><code>String <strong>getWidth</strong>()</code></div>
\r
2112 <div class="summary">
\r
2113 Returns the outer width of the console window.
\r
2116 <li class="method">
\r
2117 <div class="name">setWidth</div>
\r
2118 <div class="methodsignature"><code>void <strong>setWidth</strong>(String <em>width</em>)</code></div>
\r
2119 <div class="summary">
\r
2120 [<em>not available after initialization</em>]
\r
2122 Sets the outer width of the console window. Any valid CSS length may be used.
\r
2125 <li class="method">
\r
2126 <div class="name">getHeight</div>
\r
2127 <div class="methodsignature"><code>String <strong>getHeight</strong>()</code></div>
\r
2128 <div class="summary">
\r
2129 Returns the outer height of the console window.
\r
2132 <li class="method">
\r
2133 <div class="name">setHeight</div>
\r
2134 <div class="methodsignature"><code>void <strong>setHeight</strong>(String <em>height</em>)</code></div>
\r
2135 <div class="summary">
\r
2136 [<em>not available after initialization</em>]
\r
2138 Sets the outer height of the console window. Any valid CSS length may be used.
\r
2141 <li class="method">
\r
2142 <div class="name">getMaxMessages</div>
\r
2143 <div class="methodsignature"><code>Number <strong>getMaxMessages</strong>()</code></div>
\r
2144 <div class="summary">
\r
2145 Returns the largest number of messages displayed and stored by the console window.
\r
2148 <li class="method">
\r
2149 <div class="name">setMaxMessages</div>
\r
2150 <div class="methodsignature"><code>void <strong>setMaxMessages</strong>(Number <em>maxMessages</em>)</code></div>
\r
2151 <div class="summary">
\r
2152 [<em>not available after initialization</em>]
\r
2154 Sets the largest number of messages displayed and stored by the console window. Set
\r
2155 this to <code>null</code> to make this number unlimited.
\r
2158 <li class="method">
\r
2159 <div class="name">isShowCommandLine</div>
\r
2160 <div class="methodsignature"><code>Boolean <strong>isShowCommandLine</strong>()</code></div>
\r
2161 <div class="summary">
\r
2162 Returns whether the console includes a command line.
\r
2163 Default value is <code>true</code>.
\r
2166 <li class="method">
\r
2167 <div class="name">setShowCommandLine</div>
\r
2168 <div class="methodsignature"><code>void <strong>setShowCommandLine</strong>(Boolean <em>showCommandLine</em>)</code></div>
\r
2169 <div class="summary">
\r
2170 Sets whether the console includes a command line.
\r
2173 <li class="method">
\r
2174 <div class="name">getCommandLineObjectExpansionDepth</div>
\r
2175 <div class="methodsignature"><code>Number <strong>getCommandLineObjectExpansionDepth</strong>()</code></div>
\r
2176 <div class="summary">
\r
2177 Returns the number of levels to expand when an object value is logged to the console.
\r
2178 Each property of an object above this threshold will be expanded if it is itself an object
\r
2179 or array, otherwise its string representation will be displayed. Default value is 1 (i.e.
\r
2180 the properties of the object logged will be displayed in their string representation but
\r
2184 <li class="method">
\r
2185 <div class="name">setCommandLineObjectExpansionDepth:</div>
\r
2186 <div class="methodsignature"><code>void <strong>setCommandLineObjectExpansionDepth</strong>(Number <em>expansionDepth</em>)</code></div>
\r
2187 <div class="summary">
\r
2188 Sets the number of levels to expand when an object value is logged to the console.
\r
2191 <li class="method">
\r
2192 <div class="name">getCommandWindow</div>
\r
2193 <div class="methodsignature"><code>Window <strong>getCommandWindow</strong>()</code></div>
\r
2194 <div class="summary">
\r
2195 Returns a reference to the window in which commands typed into the command line
\r
2196 are currently being executed.
\r
2199 <li class="method">
\r
2200 <div class="name">setCommandWindow</div>
\r
2201 <div class="methodsignature"><code>void <strong>setCommandWindow</strong>(Window <em>commandWindow</em>)</code></div>
\r
2202 <div class="summary">
\r
2203 Sets the window in which commands typed into the command line are executed.
\r
2206 <li class="method">
\r
2207 <div class="name">getCommandLayout</div>
\r
2208 <div class="methodsignature"><code>Number <strong>getCommandLayout</strong>()</code></div>
\r
2209 <div class="summary">
\r
2210 Returns the layout used to format the output for commands typed into the command line.
\r
2211 The default value is a <code><a href="#patternlayout">PatternLayout</a></code> with
\r
2212 pattern string <code>%m</code>
\r
2215 <li class="method">
\r
2216 <div class="name">setCommandLayout</div>
\r
2217 <div class="methodsignature"><code>void <strong>setCommandLayout</strong>(Layout <em>commandLayout</em>)</code></div>
\r
2218 <div class="summary">
\r
2219 Sets the layout used to format the output for commands typed into the command line.
\r
2222 <li class="method">
\r
2223 <div class="name">clear</div>
\r
2224 <div class="methodsignature"><code>void <strong>clear</strong>()</code></div>
\r
2225 <div class="summary">
\r
2226 Clears all messages from the console window.
\r
2229 <li class="method">
\r
2230 <div class="name">show</div>
\r
2231 <div class="methodsignature"><code>void <strong>show</strong>()</code></div>
\r
2232 <div class="summary">
\r
2234 Shows / unhides the console window.
\r
2236 <p><strong>Notes</strong></p>
\r
2239 In Safari (and possibly other browsers), hiding an <code>iframe</code>
\r
2240 resets its document, thus destroying the console window.
\r
2245 <li class="method">
\r
2246 <div class="name">hide</div>
\r
2247 <div class="methodsignature"><code>void <strong>hide</strong>()</code></div>
\r
2248 <div class="summary">
\r
2250 Hides / minimizes the console window.
\r
2252 <p><strong>Notes</strong></p>
\r
2255 In Safari (and possibly other browsers), hiding an <code>iframe</code>
\r
2256 resets its document, thus destroying the console window.
\r
2261 <li class="method">
\r
2262 <div class="name">close</div>
\r
2263 <div class="methodsignature"><code>void <strong>close</strong>()</code></div>
\r
2264 <div class="summary">
\r
2265 Removes the console window iframe from the main document.
\r
2268 <li class="method">
\r
2269 <div class="name">focus</div>
\r
2270 <div class="methodsignature"><code>void <strong>focus</strong>()</code></div>
\r
2271 <div class="summary">
\r
2272 Brings the console window to the top and gives it the focus.
\r
2275 <li class="method">
\r
2276 <div class="name">focusCommandLine</div>
\r
2277 <div class="methodsignature"><code>void <strong>focusCommandLine</strong>()</code></div>
\r
2278 <div class="summary">
\r
2279 Brings the console window to the top and gives the focus to the command line.
\r
2282 <li class="method">
\r
2283 <div class="name">focusSearch</div>
\r
2284 <div class="methodsignature"><code>void <strong>focusSearch</strong>()</code></div>
\r
2285 <div class="summary">
\r
2286 Brings the console window to the top and gives the focus to the search box.
\r
2289 <li class="method">
\r
2290 <div class="name">evalCommandAndAppend</div>
\r
2291 <div class="methodsignature"><code>void <strong>evalCommandAndAppend</strong>(String <em>expr</em>)</code></div>
\r
2292 <div class="summary">
\r
2293 Evaluates the expression and appends the result to the console.
\r
2296 <li class="method">
\r
2297 <div class="name">addCommandLineFunction</div>
\r
2298 <div class="methodsignature"><code>void <strong>addCommandLineFunction</strong>(String <em>functionName</em>, Function <em>commandLineFunction</em>)</code></div>
\r
2299 <div class="summary">
\r
2301 Adds a function with the name specified to the list of functions available on the command line.
\r
2302 This feature may be used to add custom functions to the command line.
\r
2305 When you call the function on the command line, <code>commandLineFunction</code> is executed with the
\r
2306 following three parameters:
\r
2309 <li><em>appender</em>. A reference to the appender in which the command was executed;</li>
\r
2310 <li><em>args</em>.
\r
2311 An array-like list of parameters passed into the function on the command line
\r
2312 (actually a reference to an <code>arguments</code> object);</li>
\r
2313 <li><em>returnValue</em>. This is an object with two properties that allow the function to control
\r
2314 how the result is displayed:
\r
2316 <li><em>appendResult</em>. A boolean value that determines whether the returned value from this
\r
2317 function is appended to the console. The default value is <code>true</code>;</li>
\r
2318 <li><em>isError</em>. A boolean value that specifies whether the output of this function
\r
2319 should be displayed as an error. The default value is <code>false</code>.</li>
\r
2324 The value returned by the function is formatted by the command layout and appended to the console.
\r
2329 <p class="linktotop">
\r
2330 <a href="#container">Top</a>
\r
2333 <div id="browserconsoleappender">
\r
2334 <h3>BrowserConsoleAppender</h3>
\r
2335 <p class="editions">Editions: <strong>Standardl</strong></p>
\r
2337 Writes log messages to the browser's built-in console, if present. This only works
\r
2338 currently in Safari, Opera and Firefox with the excellent
\r
2339 <a href="http://www.getfirebug.com" title="Firebug home page (opens in new window)"
\r
2340 target="_blank">Firebug</a> extension installed.
\r
2342 <p><strong>Notes</strong></p>
\r
2345 As of log4javascript 1.3, the default threshold for this appender is <code>DEBUG</code>
\r
2346 as opposed to <code>WARN</code> as it was previously;
\r
2350 As of version 1.3, log4javascript has explicit support for Firebug's logging. This includes
\r
2351 the following mapping of log4javascript's log levels onto Firebug's:
\r
2354 <li>log4javascript <code>TRACE</code>, <code>DEBUG</code> -> Firebug <code>debug</code></li>
\r
2355 <li>log4javascript <code>INFO</code> -> Firebug <code>info</code></li>
\r
2356 <li>log4javascript <code>WARN</code> -> Firebug <code>warn</code></li>
\r
2357 <li>log4javascript <code>ERROR</code>, <code>FATAL</code> -> Firebug <code>error</code></li>
\r
2360 ... and the ability to pass objects into Firebug and take advantage of its object inspection.
\r
2361 This is because the default layout is now <code><a href="#nulllayout">NullLayout</a></code>,
\r
2362 which performs no formatting on an object.
\r
2366 <h4>Constructor</h4>
\r
2367 <ul class="propertieslist">
\r
2368 <li class="method">
\r
2369 <div class="name">BrowserConsoleAppender</div>
\r
2370 <div class="methodsignature"><code><strong>BrowserConsoleAppender</strong>()</code></div>
\r
2373 <p class="linktotop">
\r
2374 <a href="#container">Top</a>
\r
2378 <div id="layouts">
\r
2383 There are a few methods common to all layouts:
\r
2386 <ul class="propertieslist">
\r
2387 <li class="method">
\r
2388 <div class="name">format</div>
\r
2389 <div class="methodsignature"><code>String <strong>format</strong>(LoggingEvent <em>loggingEvent</em>)</code></div>
\r
2390 <div class="paramsheading">Parameters:</div>
\r
2391 <ul class="params">
\r
2392 <li class="param">
\r
2393 <code class="paramname">loggingEvent</code>
\r
2396 <div class="summary">
\r
2397 Formats the log message. You should override this method in your own layouts.
\r
2400 <li class="method">
\r
2401 <div class="name">ignoresThrowable</div>
\r
2402 <div class="methodsignature"><code>Boolean <strong>ignoresThrowable</strong>()</code></div>
\r
2403 <div class="summary">
\r
2404 Returns whether the layout ignores an error object in a logging event passed
\r
2405 to its <code>format</code> method.
\r
2408 <li class="method">
\r
2409 <div class="name">getContentType</div>
\r
2410 <div class="methodsignature"><code>String <strong>getContentType</strong>()</code></div>
\r
2411 <div class="summary">
\r
2412 Returns the content type of the output of the layout.
\r
2415 <li class="method">
\r
2416 <div class="name">allowBatching</div>
\r
2417 <div class="methodsignature"><code>Boolean <strong>allowBatching</strong>()</code></div>
\r
2418 <div class="summary">
\r
2419 Returns whether the layout's output is suitable for batching.
\r
2420 <code><a href="#jsonlayout">JsonLayout</a></code> and <code><a href="#xmllayout">XmlLayout</a></code>
\r
2421 are the only built-in layouts that return true for this method.
\r
2424 <li class="method">
\r
2425 <div class="name">getDataValues</div>
\r
2426 <div class="methodsignature"><code>Array <strong>getDataValues</strong>(LoggingEvent <em>loggingEvent</em>)</code></div>
\r
2427 <div class="paramsheading">Parameters:</div>
\r
2428 <ul class="params">
\r
2429 <li class="param">
\r
2430 <code class="paramname">loggingEvent</code>
\r
2433 <div class="summary">
\r
2434 Used internally by log4javascript in constructing formatted output for some layouts.
\r
2437 <li class="method">
\r
2438 <div class="name">setKeys</div>
\r
2439 <div class="methodsignature"><code>void <strong>setKeys</strong>(String <em>loggerKey</em>,
\r
2440 String <em>timeStampKey</em>, String <em>levelKey</em>, String <em>messageKey</em>,
\r
2441 String <em>exceptionKey</em>, String <em>urlKey</em>)</code></div>
\r
2442 <div class="paramsheading">Parameters:</div>
\r
2443 <ul class="params">
\r
2444 <li class="param">
\r
2445 <code class="paramname">loggerKey</code>
\r
2447 Parameter to use for the log message's logger name. Default is <code>logger</code>.
\r
2450 <li class="param">
\r
2451 <code class="paramname">timeStampKey</code>
\r
2453 Parameter to use for the log message's timestamp. Default is <code>timestamp</code>.
\r
2456 <li class="param">
\r
2457 <code class="paramname">levelKey</code>
\r
2459 Parameter to use for the log message's level. Default is <code>level</code>.
\r
2462 <li class="param">
\r
2463 <code class="paramname">messageKey</code>
\r
2465 Parameter to use for the message itself. Default is <code>message</code>.
\r
2468 <li class="param">
\r
2469 <code class="paramname">exceptionKey</code>
\r
2471 Parameter to use for the log message's error (exception). Default is <code>exception</code>.
\r
2474 <li class="param">
\r
2475 <code class="paramname">urlKey</code>
\r
2477 Parameter to use for the current page URL. Default is <code>url</code>.
\r
2481 <div class="summary">
\r
2482 This method is used to change the default keys used to create formatted name-value pairs
\r
2483 for the properties of a log message, for layouts that do this. These layouts are
\r
2484 <code><a href="#jsonlayout">JsonLayout</a></code> and
\r
2485 <code><a href="#httppostdatalayout">HttpPostDataLayout</a></code>.
\r
2488 <li class="method">
\r
2489 <div class="name">setCustomField</div>
\r
2490 <div class="methodsignature"><code>void <strong>setCustomField</strong>(String <em>name</em>,
\r
2491 String <em>value</em>)</code></div>
\r
2492 <div class="paramsheading">Parameters:</div>
\r
2493 <ul class="params">
\r
2494 <li class="param">
\r
2495 <code class="paramname">name</code>
\r
2497 Name of the custom property you wish to be included in the formmtted output.
\r
2500 <li class="param">
\r
2501 <code class="paramname">value</code>
\r
2503 Value of the custom property you wish to be included in the formatted output.
\r
2507 <div class="summary">
\r
2508 Some layouts (<code><a href="#jsonlayout">JsonLayout</a></code>,
\r
2509 <code><a href="#httppostdatalayout">HttpPostDataLayout</a></code>,
\r
2510 <code><a href="#patternlayout">PatternLayout</a></code> and
\r
2511 <code><a href="#xmllayout">XmlLayout</a></code>) allow you to set
\r
2512 custom fields (e.g. a session id to send to the server) to the
\r
2513 formatted output. Use this method to set a custom field. If there
\r
2514 is already a custom field with the specified name, its value will
\r
2515 be updated with <code>value</code>.
\r
2517 <p><strong>Notes</strong></p>
\r
2521 From version 1.4, the custom field value may be a function. In this
\r
2522 case, the function is run at the time the layout's format method is called,
\r
2523 with the following two parameters:
\r
2526 <li><em>layout</em>. A reference to the layout being used;</li>
\r
2527 <li><em>loggingEvent</em>. A reference to the logging event being formatted.</li>
\r
2532 <li class="method">
\r
2533 <div class="name">hasCustomFields</div>
\r
2534 <div class="methodsignature"><code>Boolean <strong>hasCustomFields</strong>()</code></div>
\r
2535 <div class="summary">
\r
2536 Returns whether the layout has any custom fields.
\r
2540 <p class="linktotop">
\r
2541 <a href="#container">Top</a>
\r
2544 <div id="nulllayout">
\r
2545 <h3>NullLayout</h3>
\r
2546 <p class="editions">Editions: <strong>All</strong></p>
\r
2548 The most basic layout. NullLayout's <code>format()</code> methods performs no
\r
2549 formatting at all and simply returns the message logged.
\r
2551 <h4>Constructor</h4>
\r
2552 <ul class="propertieslist">
\r
2553 <li class="method">
\r
2554 <div class="name">NullLayout</div>
\r
2555 <div class="methodsignature"><code><strong>NullLayout</strong>()</code></div>
\r
2558 <p class="linktotop">
\r
2559 <a href="#container">Top</a>
\r
2562 <div id="simplelayout">
\r
2563 <h3>SimpleLayout</h3>
\r
2564 <p class="editions">Editions: <strong>Standard, Production</strong></p>
\r
2566 Provides basic formatting. SimpleLayout consists of the level of the log statement,
\r
2567 followed by " - " and then the log message itself. For example,
\r
2569 <p><code>DEBUG - Hello world</code></p>
\r
2570 <h4>Constructor</h4>
\r
2571 <ul class="propertieslist">
\r
2572 <li class="method">
\r
2573 <div class="name">SimpleLayout</div>
\r
2574 <div class="methodsignature"><code><strong>SimpleLayout</strong>()</code></div>
\r
2577 <p class="linktotop">
\r
2578 <a href="#container">Top</a>
\r
2581 <div id="patternlayout">
\r
2582 <h3>PatternLayout</h3>
\r
2583 <p class="editions">Editions: <strong>All</strong></p>
\r
2585 Provides a flexible way of formatting a log message by means of a conversion pattern
\r
2586 string. The behaviour of this layout is a full implementation of <code>PatternLayout</code>
\r
2587 in log4j, with the exception of the set of conversion characters - log4javascript's is
\r
2588 necessarily a subset of that of log4j with a few additions of its own, since many of
\r
2589 the conversion characters in log4j only make sense in the context of Java.
\r
2592 The conversion pattern consists of literal text interspersed with special strings starting with
\r
2593 a % symbol called <em>conversion specifiers</em>. A conversion specifier consists of the
\r
2594 % symbol, a conversion character (possible characters are listed below) and
\r
2595 <em>format modifiers</em>. For full documentation of the conversion pattern, see
\r
2596 <a href="http://logging.apache.org/log4j/docs/api/org/apache/log4j/PatternLayout.html" target="_blank">log4j's
\r
2597 documentation</a>. Below is a list of all conversion characters available in log4javascript.
\r
2599 <h4>Conversion characters</h4>
\r
2600 <table border="1" cellspacing="0">
\r
2603 <th>Conversion Character</th>
\r
2612 Outputs log messages specified as an array.
\r
2615 Behaves exactly like <code>%m</code>, except that multiple log messages are
\r
2616 assumed to have been specified in the logging call as an array rather than
\r
2617 as multiple parameters.
\r
2620 <strong>Since: 1.4</strong>
\r
2628 Outputs the logger name.
\r
2636 Outputs the date of the logging event. The date conversion specifier
\r
2637 may be followed by a date format specifier enclosed between braces. For
\r
2638 example, <code>%d{HH:mm:ss,SSS}</code> or
\r
2639 <code>%d{dd MMM yyyy HH:mm:ss,SSS}</code>. If no date
\r
2640 format specifier is given then ISO8601 format is assumed.
\r
2643 The date format specifier is the same as that used by Java's
\r
2644 <code><a href="http://java.sun.com/j2se/1.5.0/docs/api/java/text/SimpleDateFormat.html"
\r
2645 target="_blank">SimpleDateFormat</a></code>. log4javascript
\r
2646 includes a full implementation of SimpleDateFormat's
\r
2647 <code>format</code> method, with the exception of the pattern letter
\r
2648 'z', (string representation of the timezone) for which the information
\r
2649 is not available in JavaScript.
\r
2657 Outputs the value of a custom field set on the layout. If present, the specifier gives
\r
2658 the index in the array of custom fields to use; otherwise, the first custom field in the
\r
2662 <strong>Since: 1.3</strong>
\r
2670 Outputs the log messages of the logging event (i.e. the log
\r
2671 messages supplied by the client code).
\r
2674 As of version 1.4, multiple log messages may be supplied to logging calls.
\r
2675 <code>%m</code> displays each log message (using the rules below) one after
\r
2676 another, separated by spaces.
\r
2679 As of version 1.3, an object may be specified as the log message and will
\r
2680 be expanded to show its properties in the output, provided that a specifier
\r
2681 containing the number of levels to expand is provided. If no specifier is
\r
2682 provided then the message will be treated as a string regardless of its type.
\r
2683 For example, <code>%m{1}</code> will display an expansion of the object one
\r
2684 level deep, i.e. each property of the object will be displayed but if the
\r
2685 property value is itself an object it will not be expanded and will appear
\r
2686 as <code>[object Object]</code>.
\r
2694 Outputs a line separator.
\r
2702 Outputs the level of the logging event.
\r
2710 Outputs the number of milliseconds since log4javascript was initialized.
\r
2718 The sequence %% outputs a single percent sign.
\r
2724 <h4>Static properties</h4>
\r
2725 <ul class="propertieslist">
\r
2726 <li class="property">
\r
2727 <div class="name">TTCC_CONVERSION_PATTERN</div>
\r
2728 <div class="summary">
\r
2729 Built-in conversion pattern, equivalent to <code>%r %p %c - %m%n</code>.
\r
2732 <li class="property">
\r
2733 <div class="name">DEFAULT_CONVERSION_PATTERN</div>
\r
2734 <div class="summary">
\r
2735 Built-in conversion pattern, equivalent to <code>%m%n</code>.
\r
2738 <li class="property">
\r
2739 <div class="name">ISO8601_DATEFORMAT</div>
\r
2740 <div class="summary">
\r
2741 Built-in date format (and also the default), equivalent to
\r
2742 <code>yyyy-MM-dd HH:mm:ss,SSS</code>.
\r
2745 <li class="property">
\r
2746 <div class="name">DATETIME_DATEFORMAT</div>
\r
2747 <div class="summary">
\r
2748 Built-in date format, equivalent to <code>dd MMM YYYY HH:mm:ss,SSS</code>.
\r
2751 <li class="property">
\r
2752 <div class="name">ABSOLUTETIME_DATEFORMAT</div>
\r
2753 <div class="summary">
\r
2754 Built-in date format, equivalent to <code>HH:mm:ss,SSS</code>.
\r
2758 <h4>Constructor</h4>
\r
2759 <ul class="propertieslist">
\r
2760 <li class="method">
\r
2761 <div class="name">PatternLayout</div>
\r
2762 <div class="methodsignature"><code><strong>PatternLayout</strong>(String <em>pattern</em>)</code></div>
\r
2763 <div class="paramsheading">Parameters:</div>
\r
2764 <ul class="params">
\r
2765 <li class="param">
\r
2766 <code class="paramname">pattern</code>
\r
2768 The conversion pattern string to use.
\r
2774 <p class="linktotop">
\r
2775 <a href="#container">Top</a>
\r
2778 <div id="xmllayout">
\r
2779 <h3>XmlLayout</h3>
\r
2780 <p class="editions">Editions: <strong>Standard, Production</strong></p>
\r
2782 Based on log4j's <code>XmlLayout</code>, this layout formats a log message as a
\r
2783 fragment of XML. An example of the format of the fragment is as follows:
\r
2786 <log4javascript:event logger="[default]" timestamp="1201048234203" level="ERROR">
\r
2787 <log4javascript:message><![CDATA[Big problem!]]></log4javascript:message>
\r
2788 <log4javascript:exception><![CDATA[Nasty error on line number 1
\r
2789 in file http://log4javascript.org/test.html]]></log4javascript:exception>
\r
2790 </log4javascript:event>
\r
2792 <p><strong>Notes</strong></p>
\r
2795 This layout supports batching of log messages when used in an
\r
2796 <code><a href="#ajaxappender">AjaxAppender</a></code>. A batch of
\r
2797 messages is simply concatenated to form a string of several XML
\r
2798 frgaments similar to that above.
\r
2801 The <code><log4javascript:exception></code> element is only present if an
\r
2802 exception was passed into the original log call.
\r
2805 As of version 1.4, timestamps are returned as milliseconds since midnight of
\r
2806 January 1, 1970 rather than seconds as in previous versions. This allows finer
\r
2807 measurement of the time a logging event occurred and is also the JavaScript
\r
2808 <code>Date</code> object's standard measurement.
\r
2811 Also as of version 1.4, multiple messages may be specified as separate parameters
\r
2812 in a single logging call. In <code>XmlLayout</code>, multiple messages may be
\r
2813 formatted as a single combined message or may be formated as several
\r
2814 <code><log4javascript:message></code> elements inside one
\r
2815 <code><log4javascript:messages></code> element as shown below:
\r
2818 <log4javascript:event logger="[default]" timestamp="1201048234203" level="ERROR">
\r
2819 <log4javascript:messages>
\r
2820 <log4javascript:message><![CDATA[Big problem!]]></log4javascript:message>
\r
2821 <log4javascript:message><![CDATA[Value of x when this error
\r
2822 occurred: 3]]></log4javascript:message>
\r
2823 </log4javascript:messages>
\r
2824 <log4javascript:exception><![CDATA[Nasty error on line number 1
\r
2825 in file http://log4javascript.org/test.html]]></log4javascript:exception>
\r
2826 </log4javascript:event>
\r
2830 As of version 1.3, custom fields may be added to the output. Each field will
\r
2831 add a tag of the following form inside the <code><log4javascript:event></code>
\r
2835 <log4javascript:customfield name="sessionid"><![CDATA[1234]]></log4javascript:customfield>
\r
2839 <h4>Constructor</h4>
\r
2840 <ul class="propertieslist">
\r
2841 <li class="method">
\r
2842 <div class="name">XmlLayout</div>
\r
2843 <div class="methodsignature"><code><strong>XmlLayout</strong>([Boolean <em>combineMessages</em>])</code></div>
\r
2844 <ul class="params">
\r
2845 <li class="param">
\r
2846 <code class="paramname">combineMessages</code>
\r
2848 Whether or not to format multiple log messages as a combined single
\r
2849 <code><log4javascript:message></code> element
\r
2850 composed of each individual message separated by line breaks or to include
\r
2851 a <code><log4javascript:message></code> element for each message inside
\r
2852 one <code><log4javascript:messages></code> element.
\r
2853 If not specified, defaults to <code>true</code>.
\r
2859 <p class="linktotop">
\r
2860 <a href="#container">Top</a>
\r
2863 <div id="jsonlayout">
\r
2864 <h3>JsonLayout</h3>
\r
2865 <p class="editions">Editions: <strong>Standard, Production</strong></p>
\r
2867 Formats a logging event into JavaScript Object Notation (JSON).
\r
2868 JSON is a subset of JavaScript's object literal syntax, meaning that log
\r
2869 messages formatted with this layout can be interpreted directly by JavaScript
\r
2870 and converted into objects. See
\r
2871 <a href="http://json.org/" target="_blank" title="json.org (opens in new window)">json.org</a> for more details
\r
2877 "logger": "[default]",
\r
2878 "timeStamp": 1201048234203,
\r
2880 "url": "http://log4javascript.org/test.html",
\r
2881 "message": "Big problem!",
\r
2882 "exception": "Nasty error on line number 1 in file
\r
2883 http://log4javascript.org/test.html"
\r
2887 The <code>exception</code> property is only present if an exception was passed
\r
2888 into the original log call.
\r
2890 <p><strong>Notes</strong></p>
\r
2893 This layout supports batching of log messages when used in an
\r
2894 <code><a href="#ajaxappender">AjaxAppender</a></code>. When sent singly
\r
2895 the layout formats the log message as a single JavaScript object literal;
\r
2896 when sent as a batch, the messages are formatted as an array literal whose
\r
2897 elements are log message objects.
\r
2901 As of version 1.3, custom fields may be added to the output. Each field will
\r
2902 add a property of the following form to the main object literal:
\r
2909 From version 1.4, the variable names used for log event properties such as
\r
2910 the message, timestamp and exception are specified using the <code>setKeys()</code>
\r
2911 method of <code><a href="#layout">Layout</a></code>.
\r
2915 Also as of version 1.4, multiple messages may be specified as separate parameters
\r
2916 in a single logging call. In <code>JsonLayout</code>, multiple messages may be
\r
2917 formatted as a single combined message or may be formated as an array of messages
\r
2922 "logger": "[default]",
\r
2923 "timeStamp": 1201048234203,
\r
2925 "url": "http://log4javascript.org/test.html",
\r
2928 "Value of x when this error occurred: 3"
\r
2930 "exception": "Nasty error on line number 1 in file
\r
2931 http://log4javascript.org/test.html"
\r
2936 <h4>Constructor</h4>
\r
2937 <ul class="propertieslist">
\r
2938 <li class="method">
\r
2939 <div class="name">JsonLayout</div>
\r
2940 <div class="methodsignature"><code><strong>JsonLayout</strong>([Boolean <em>readable</em>, Boolean <em>combineMessages</em>])</code></div>
\r
2941 <div class="paramsheading">Parameters:</div>
\r
2942 <ul class="params">
\r
2943 <li class="param">
\r
2944 <code class="paramname">readable</code>
\r
2946 Whether or not to format each log message with line breaks and tabs.
\r
2947 If not specified, defaults to <code>false</code>.
\r
2950 <li class="param">
\r
2951 <code class="paramname">combineMessages</code>
\r
2953 Whether or not to format multiple log messages as a combined single
\r
2954 <code>message</code> property composed of each individual message separated by line
\r
2955 breaks or to format multiple messages as an array.
\r
2956 If not specified, defaults to <code>true</code>.
\r
2963 <ul class="propertieslist">
\r
2964 <li class="method">
\r
2965 <div class="name">isReadable</div>
\r
2966 <div class="methodsignature"><code>Boolean <strong>isReadable</strong>()</code></div>
\r
2967 <div class="summary">
\r
2968 Returns whether or not to each log message is formatted with line breaks and tabs.
\r
2970 <p><strong>Notes</strong></p>
\r
2974 <code>setReadable</code> has been removed in version 1.4. This property can
\r
2975 be set via the constructor.
\r
2982 <div id="httppostdatalayout">
\r
2983 <h3>HttpPostDataLayout</h3>
\r
2984 <p class="editions">Editions: <strong>Standard, Production</strong></p>
\r
2986 Formats the log message as a simple URL-encoded string from which a simple
\r
2987 server-side script may extract parameters such as the log message, severity
\r
2988 and timestamp. This is the default layout for
\r
2989 <code><a href="#ajaxappender">AjaxAppender</a></code>.
\r
2991 <h4>Constructor</h4>
\r
2992 <ul class="propertieslist">
\r
2993 <li class="method">
\r
2994 <div class="name">HttpPostDataLayout</div>
\r
2995 <div class="methodsignature"><code><strong>HttpPostDataLayout</strong>()</code></div>
\r
2998 <p><strong>Notes</strong></p>
\r
3001 As of version 1.3, custom fields may be added to the output. Each field will
\r
3002 be added as a parameter to the post data.
\r
3005 From version 1.4, the variable names used for log event properties such as
\r
3006 the message, timestamp and exception are specified using the <code>setKeys()</code>
\r
3007 method of <code><a href="#layout">Layout</a></code>.
\r
3010 <p class="linktotop">
\r
3011 <a href="#container">Top</a>
\r
3015 <div id="enabling">
\r
3016 <h2>Enabling / disabling log4javascript</h2>
\r
3018 All logging can be enabled or disabled in log4javascript in a number of ways:
\r
3022 At any time, you can call
\r
3023 <code>log4javascript.setEnabled(<em>enabled</em>)</code>. This will
\r
3024 enable or disable all logging, depending on whether <code>enabled</code>
\r
3025 is set to <code>true</code> or <code>false</code>.
\r
3029 Assign a value to the global variable <code>log4javascript_disabled</code>.
\r
3030 The idea of this is so that you can enable or disable logging for a whole site by
\r
3031 including a JavaScript file in all your pages, and allowing this file to be
\r
3032 included <strong>before</strong> log4javascript.js to guarantee that no logging
\r
3033 can take place without having to alter log4javascript.js itself. Your included
\r
3034 .js file would include a single line such as the following:
\r
3037 <code>var log4javascript_disabled = true;</code>
\r
3041 Assign your logger object a value of <code>log4javascript.getNullLogger()</code>.
\r
3044 Replace your copy of log4javascript_x.js with stubs/log4javascript_x.js, provided in the
\r
3045 distribution. This file has a stub version of each of the functions and methods
\r
3046 in the log4javascript API and can simply be dropped in in place of the main file.
\r
3047 The compressed version of the stub is typically 15 times smaller than the
\r
3048 compressed version of the main file.
\r
3051 <p class="linktotop">
\r
3052 <a href="#container">Top</a>
\r
3055 <div id="errorhandling">
\r
3056 <h2>log4javascript error handling</h2>
\r
3058 log4javascript has a single rudimentary logger-like object of its own to handle
\r
3059 messages generated by log4javascript itself. This logger is called <code>LogLog</code>
\r
3060 and is accessed via <code>log4javascript.logLog</code>.
\r
3064 <ul class="propertieslist">
\r
3065 <li class="method">
\r
3066 <div class="name">setQuietMode</div>
\r
3067 <div class="methodsignature"><code>void <strong>setQuietMode</strong>(Boolean <em>quietMode</em>)</code></div>
\r
3068 <div class="paramsheading">Parameters:</div>
\r
3069 <ul class="params">
\r
3070 <li class="param">
\r
3071 <code class="paramname">quietMode</code>
\r
3073 Whether to turn quiet mode on or off.
\r
3077 <div class="summary">
\r
3078 Sets whether <code>LogLog</code> is in quiet mode or not. In quiet mode, no
\r
3079 messages sent to <code>LogLog</code> have any visible effect. By default,
\r
3080 quiet mode is switched off.
\r
3083 <li class="method">
\r
3084 <div class="name">setAlertAllErrors</div>
\r
3085 <div class="methodsignature"><code>void <strong>setAlertAllErrors</strong>(Boolean <em>alertAllErrors</em>)</code></div>
\r
3086 <div class="paramsheading">Parameters:</div>
\r
3087 <ul class="params">
\r
3088 <li class="param">
\r
3089 <code class="paramname">showAllErrors</code>
\r
3091 Whether to show all errors or just the first.
\r
3095 <div class="summary">
\r
3096 Sets how many errors <code>LogLog</code> will display alerts for. By default,
\r
3097 only the first error encountered generates an alert to the user. If you turn
\r
3098 all errors on by supplying <code>true</code> to this method then all errors
\r
3099 will generate alerts.
\r
3102 <li class="method">
\r
3103 <div class="name">debug</div>
\r
3104 <div class="methodsignature"><code>void <strong>debug</strong>(String <em>message</em>[, Error <em>exception</em>])</code></div>
\r
3105 <div class="paramsheading">Parameters:</div>
\r
3106 <ul class="params">
\r
3107 <li class="param">
\r
3108 <code class="paramname">message</code>
\r
3110 <li class="param">
\r
3111 <code class="paramname">exception</code>
\r
3112 [<em>optional</em>]
\r
3115 <div class="summary">
\r
3116 Logs a debugging message to an in-memory list. This implementation is new in version 1.4.
\r
3119 <li class="method">
\r
3120 <div class="name">displayDebug</div>
\r
3121 <div class="methodsignature"><code>void <strong>displayDebug</strong>()</code></div>
\r
3122 <div class="summary">
\r
3123 Displays an alert of all debugging messages. This method is new in version 1.4.
\r
3126 <li class="method">
\r
3127 <div class="name">warn</div>
\r
3128 <div class="methodsignature"><code>void <strong>warn</strong>(String <em>message</em>[, Error <em>exception</em>])</code></div>
\r
3129 <div class="paramsheading">Parameters:</div>
\r
3130 <ul class="params">
\r
3131 <li class="param">
\r
3132 <code class="paramname">message</code>
\r
3134 <li class="param">
\r
3135 <code class="paramname">exception</code>
\r
3136 [<em>optional</em>]
\r
3139 <div class="summary">
\r
3140 Currently has no effect.
\r
3143 <li class="method">
\r
3144 <div class="name">error</div>
\r
3145 <div class="methodsignature"><code>void <strong>error</strong>(String <em>message</em>[, Error <em>exception</em>])</code></div>
\r
3146 <div class="paramsheading">Parameters:</div>
\r
3147 <ul class="params">
\r
3148 <li class="param">
\r
3149 <code class="paramname">message</code>
\r
3151 <li class="param">
\r
3152 <code class="paramname">exception</code>
\r
3153 [<em>optional</em>]
\r
3156 <div class="summary">
\r
3157 Generates an alert to the user if and only if the error is the first one
\r
3158 encountered and <code>setAlertAllErrors(true)</code> has not been called.
\r
3162 <p class="linktotop">
\r
3163 <a href="#container">Top</a>
\r
3167 <div id="differences">
\r
3168 <h2>Differences between log4javascript and log4j</h2>
\r
3170 For the sake of keeping log4javascript as light and useful as possible, many
\r
3171 of the features of log4j that seem over-complex or inappropriate for
\r
3172 JavaScript have not been implemented. These include:
\r
3176 <li>Configurators</li>
\r
3177 <li>Renderers</li>
\r
3179 <p class="linktotop">
\r
3180 <a href="#container">Top</a>
\r
3185 <span class="externallinkinfo">
\r
3186 <strong>NB.</strong> All external links open in a new window.
\r
3188 Written by Tim Down. <a href="mailto:tim@log4javascript.org">tim@log4javascript.org</a>
\r
3190 log4javascript is distributed under the <a href="http://www.apache.org/licenses/LICENSE-2.0.html"
\r
3191 title="Apache License, Version 2.0 (opens in new window)" target="_blank">Apache License,
\r
git://git.onelab.eu / plstackapi.git / blob