log4r 1.1.6 → 1.1.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/README +3 -3
- data/Rakefile +2 -2
- data/doc/rdoc/Log4r.html +519 -0
- data/doc/rdoc/Log4r/BasicFormatter.html +388 -0
- data/doc/rdoc/Log4r/ConfigError.html +225 -0
- data/doc/rdoc/Log4r/Configurator.html +1068 -0
- data/doc/rdoc/Log4r/DateFileOutputter.html +479 -0
- data/doc/rdoc/Log4r/DefaultFormatter.html +223 -0
- data/doc/rdoc/Log4r/EmailOutputter.html +654 -0
- data/doc/rdoc/Log4r/FileOutputter.html +346 -0
- data/doc/rdoc/Log4r/Formatter.html +309 -0
- data/doc/rdoc/Log4r/GDC.html +346 -0
- data/doc/rdoc/Log4r/GDC_rb.html +80 -0
- data/doc/rdoc/Log4r/IOOutputter.html +410 -0
- data/doc/rdoc/Log4r/Log4jXmlFormatter.html +337 -0
- data/doc/rdoc/Log4r/Log4rConfig.html +211 -0
- data/doc/rdoc/Log4r/Log4rTools.html +388 -0
- data/doc/rdoc/Log4r/LogEvent.html +378 -0
- data/doc/rdoc/Log4r/LogServer.html +340 -0
- data/doc/rdoc/Log4r/Logger.html +1150 -0
- data/doc/rdoc/Log4r/Logger/LoggerFactory.html +218 -0
- data/doc/rdoc/Log4r/Logger/Repository.html +225 -0
- data/doc/rdoc/Log4r/MDC.html +424 -0
- data/doc/rdoc/Log4r/MDC_rb.html +83 -0
- data/doc/rdoc/Log4r/NDC.html +632 -0
- data/doc/rdoc/Log4r/NDC_rb.html +110 -0
- data/doc/rdoc/Log4r/ObjectFormatter.html +280 -0
- data/doc/rdoc/Log4r/Outputter.html +934 -0
- data/doc/rdoc/Log4r/Outputter/OutputterFactory.html +218 -0
- data/doc/rdoc/Log4r/Outputter/consoleoutputters_rb.html +57 -0
- data/doc/rdoc/Log4r/Outputter/datefileoutputter_rb.html +93 -0
- data/doc/rdoc/Log4r/Outputter/emailoutputter_rb.html +179 -0
- data/doc/rdoc/Log4r/Outputter/fileoutputter_rb.html +64 -0
- data/doc/rdoc/Log4r/Outputter/iooutputter_rb.html +59 -0
- data/doc/rdoc/Log4r/Outputter/outputter_rb.html +222 -0
- data/doc/rdoc/Log4r/Outputter/outputterfactory_rb.html +62 -0
- data/doc/rdoc/Log4r/Outputter/remoteoutputter_rb.html +59 -0
- data/doc/rdoc/Log4r/Outputter/rollingfileoutputter_rb.html +66 -0
- data/doc/rdoc/Log4r/Outputter/staticoutputter_rb.html +55 -0
- data/doc/rdoc/Log4r/Outputter/syslogoutputter_rb.html +110 -0
- data/doc/rdoc/Log4r/Outputter/udpoutputter_rb.html +220 -0
- data/doc/rdoc/Log4r/PatternFormatter.html +404 -0
- data/doc/rdoc/Log4r/ROMPClient.html +211 -0
- data/doc/rdoc/Log4r/ROMPServer.html +211 -0
- data/doc/rdoc/Log4r/RemoteOutputter.html +402 -0
- data/doc/rdoc/Log4r/RollingFileOutputter.html +551 -0
- data/doc/rdoc/Log4r/RootLogger.html +530 -0
- data/doc/rdoc/Log4r/SimpleFormatter.html +276 -0
- data/doc/rdoc/Log4r/StderrOutputter.html +268 -0
- data/doc/rdoc/Log4r/StdoutOutputter.html +268 -0
- data/doc/rdoc/Log4r/SyslogOutputter.html +551 -0
- data/doc/rdoc/Log4r/UDPOutputter.html +379 -0
- data/doc/rdoc/Log4r/YamlConfigurator.html +966 -0
- data/doc/rdoc/Log4r/base_rb.html +57 -0
- data/doc/rdoc/Log4r/config_rb.html +122 -0
- data/doc/rdoc/Log4r/configurator_rb.html +370 -0
- data/doc/rdoc/Log4r/formatter/formatter_rb.html +121 -0
- data/doc/rdoc/Log4r/formatter/log4jxmlformatter_rb.html +64 -0
- data/doc/rdoc/Log4r/formatter/patternformatter_rb.html +239 -0
- data/doc/rdoc/Log4r/lib/drbloader_rb.html +57 -0
- data/doc/rdoc/Log4r/lib/xmlloader_rb.html +57 -0
- data/doc/rdoc/Log4r/logevent_rb.html +55 -0
- data/doc/rdoc/Log4r/logger_rb.html +293 -0
- data/doc/rdoc/Log4r/loggerfactory_rb.html +66 -0
- data/doc/rdoc/Log4r/logserver_rb.html +161 -0
- data/doc/rdoc/Log4r/rdoc/GDC.html +175 -0
- data/doc/rdoc/Log4r/rdoc/MDC.html +178 -0
- data/doc/rdoc/Log4r/rdoc/NDC.html +207 -0
- data/doc/rdoc/Log4r/rdoc/configurator.html +462 -0
- data/doc/rdoc/Log4r/rdoc/emailoutputter.html +279 -0
- data/doc/rdoc/Log4r/rdoc/formatter.html +218 -0
- data/doc/rdoc/Log4r/rdoc/log4r.html +286 -0
- data/doc/rdoc/Log4r/rdoc/logger.html +382 -0
- data/doc/rdoc/Log4r/rdoc/logserver.html +265 -0
- data/doc/rdoc/Log4r/rdoc/outputter.html +313 -0
- data/doc/rdoc/Log4r/rdoc/patternformatter.html +331 -0
- data/doc/rdoc/Log4r/rdoc/syslogoutputter.html +197 -0
- data/doc/rdoc/Log4r/rdoc/win32eventoutputter.html +165 -0
- data/doc/rdoc/Log4r/rdoc/yamlconfigurator.html +187 -0
- data/doc/rdoc/Log4r/repository_rb.html +74 -0
- data/doc/rdoc/Log4r/staticlogger_rb.html +55 -0
- data/doc/rdoc/Log4r/yamlconfigurator_rb.html +95 -0
- data/doc/rdoc/REXML.html +211 -0
- data/doc/rdoc/created.rid +1 -0
- data/doc/rdoc/images/brick.png +0 -0
- data/doc/rdoc/images/brick_link.png +0 -0
- data/doc/rdoc/images/bug.png +0 -0
- data/doc/rdoc/images/bullet_black.png +0 -0
- data/doc/rdoc/images/bullet_toggle_minus.png +0 -0
- data/doc/rdoc/images/bullet_toggle_plus.png +0 -0
- data/doc/rdoc/images/date.png +0 -0
- data/doc/rdoc/images/find.png +0 -0
- data/doc/rdoc/images/loadingAnimation.gif +0 -0
- data/doc/rdoc/images/macFFBgHack.png +0 -0
- data/doc/rdoc/images/package.png +0 -0
- data/doc/rdoc/images/page_green.png +0 -0
- data/doc/rdoc/images/page_white_text.png +0 -0
- data/doc/rdoc/images/page_white_width.png +0 -0
- data/doc/rdoc/images/plugin.png +0 -0
- data/doc/rdoc/images/ruby.png +0 -0
- data/doc/rdoc/images/tag_green.png +0 -0
- data/doc/rdoc/images/wrench.png +0 -0
- data/doc/rdoc/images/wrench_orange.png +0 -0
- data/doc/rdoc/images/zoom.png +0 -0
- data/doc/rdoc/index.html +585 -0
- data/doc/rdoc/js/darkfish.js +116 -0
- data/doc/rdoc/js/jquery.js +32 -0
- data/doc/rdoc/js/quicksearch.js +114 -0
- data/doc/rdoc/js/thickbox-compressed.js +10 -0
- data/doc/rdoc/log4r-rdoc.css +696 -0
- data/doc/rdoc/log4r_rb.html +207 -0
- data/doc/rdoc/rdoc.css +696 -0
- data/examples/rdoc-gen +2 -0
- data/src/log4r.rb +2 -2
- data/src/log4r/formatter/patternformatter.rb +15 -15
- data/src/log4r/outputter/udpoutputter.rb +4 -4
- data/tests/testchainsaw.rb +1 -1
- metadata +123 -8
- data/src/log4r/outputter/datefileoutputter.patch +0 -24
- data/src/log4r/outputter/diff +0 -14
- data/src/log4r/outputter/new-datefileoutputter.rb +0 -117
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="utf-8"?>
|
|
2
|
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
3
|
+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
4
|
+
|
|
5
|
+
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
6
|
+
<head>
|
|
7
|
+
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
|
|
8
|
+
|
|
9
|
+
<title>File: base.rb [1.1.7 Log4r API]</title>
|
|
10
|
+
|
|
11
|
+
<link type="text/css" media="screen" href="../rdoc.css" rel="stylesheet" />
|
|
12
|
+
|
|
13
|
+
<script src="../js/jquery.js" type="text/javascript"
|
|
14
|
+
charset="utf-8"></script>
|
|
15
|
+
<script src="../js/thickbox-compressed.js" type="text/javascript"
|
|
16
|
+
charset="utf-8"></script>
|
|
17
|
+
<script src="../js/quicksearch.js" type="text/javascript"
|
|
18
|
+
charset="utf-8"></script>
|
|
19
|
+
<script src="../js/darkfish.js" type="text/javascript"
|
|
20
|
+
charset="utf-8"></script>
|
|
21
|
+
</head>
|
|
22
|
+
|
|
23
|
+
<body class="file file-popup">
|
|
24
|
+
<div id="metadata">
|
|
25
|
+
<dl>
|
|
26
|
+
<dt class="modified-date">Last Modified</dt>
|
|
27
|
+
<dd class="modified-date">Thu Mar 18 19:31:06 -0800 2004</dd>
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
<dt class="requires">Requires</dt>
|
|
31
|
+
<dd class="requires">
|
|
32
|
+
<ul>
|
|
33
|
+
|
|
34
|
+
<li>log4r/config</li>
|
|
35
|
+
|
|
36
|
+
</ul>
|
|
37
|
+
</dd>
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
</dl>
|
|
42
|
+
</div>
|
|
43
|
+
|
|
44
|
+
<div id="documentation">
|
|
45
|
+
|
|
46
|
+
<div class="description">
|
|
47
|
+
<h2>Description</h2>
|
|
48
|
+
<p>
|
|
49
|
+
:nodoc:
|
|
50
|
+
</p>
|
|
51
|
+
|
|
52
|
+
</div>
|
|
53
|
+
|
|
54
|
+
</div>
|
|
55
|
+
</body>
|
|
56
|
+
</html>
|
|
57
|
+
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="utf-8"?>
|
|
2
|
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
3
|
+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
4
|
+
|
|
5
|
+
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
6
|
+
<head>
|
|
7
|
+
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
|
|
8
|
+
|
|
9
|
+
<title>File: config.rb [1.1.7 Log4r API]</title>
|
|
10
|
+
|
|
11
|
+
<link type="text/css" media="screen" href="../rdoc.css" rel="stylesheet" />
|
|
12
|
+
|
|
13
|
+
<script src="../js/jquery.js" type="text/javascript"
|
|
14
|
+
charset="utf-8"></script>
|
|
15
|
+
<script src="../js/thickbox-compressed.js" type="text/javascript"
|
|
16
|
+
charset="utf-8"></script>
|
|
17
|
+
<script src="../js/quicksearch.js" type="text/javascript"
|
|
18
|
+
charset="utf-8"></script>
|
|
19
|
+
<script src="../js/darkfish.js" type="text/javascript"
|
|
20
|
+
charset="utf-8"></script>
|
|
21
|
+
</head>
|
|
22
|
+
|
|
23
|
+
<body class="file file-popup">
|
|
24
|
+
<div id="metadata">
|
|
25
|
+
<dl>
|
|
26
|
+
<dt class="modified-date">Last Modified</dt>
|
|
27
|
+
<dd class="modified-date">Thu Mar 18 19:31:06 -0800 2004</dd>
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
<dt class="requires">Requires</dt>
|
|
31
|
+
<dd class="requires">
|
|
32
|
+
<ul>
|
|
33
|
+
|
|
34
|
+
</ul>
|
|
35
|
+
</dd>
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
</dl>
|
|
40
|
+
</div>
|
|
41
|
+
|
|
42
|
+
<div id="documentation">
|
|
43
|
+
|
|
44
|
+
<div class="description">
|
|
45
|
+
<h2>Description</h2>
|
|
46
|
+
<pre>
|
|
47
|
+
:nodoc:
|
|
48
|
+
Version:: $Id: config.rb,v 1.1.1.1 2004/03/19 03:31:06 fando Exp $
|
|
49
|
+
---
|
|
50
|
+
TODO: catch unparsed parameters #{FOO} and die
|
|
51
|
+
---
|
|
52
|
+
</pre>
|
|
53
|
+
<p>
|
|
54
|
+
:nodoc:
|
|
55
|
+
</p>
|
|
56
|
+
<pre>
|
|
57
|
+
---
|
|
58
|
+
</pre>
|
|
59
|
+
<p>
|
|
60
|
+
:nodoc:
|
|
61
|
+
</p>
|
|
62
|
+
<pre>
|
|
63
|
+
---
|
|
64
|
+
:nodoc:
|
|
65
|
+
---
|
|
66
|
+
= NDC
|
|
67
|
+
|
|
68
|
+
The NDC class implements a copy of the Nested Diagnostic Context, which
|
|
69
|
+
is part of the Apache Log4j library. Nested Diagnostic Contexts were
|
|
70
|
+
derived from Neil Harrison's article on "Patterns for Logging
|
|
71
|
+
Diagnostic Messages", part of the book "Pattern Languages of Program
|
|
72
|
+
Design 3" edited by Martin et al.
|
|
73
|
+
|
|
74
|
+
NDCs in Log4r are thread safe.
|
|
75
|
+
|
|
76
|
+
NDCs in log4r are close enough to NDCs in Log4j that I include its
|
|
77
|
+
documentation directly:
|
|
78
|
+
|
|
79
|
+
...
|
|
80
|
+
A Nested Diagnostic Context, or NDC in short, is an instrument to
|
|
81
|
+
distinguish interleaved log output from different sources. Log output
|
|
82
|
+
is typically interleaved when a server handles multiple clients
|
|
83
|
+
near-simultaneously.
|
|
84
|
+
|
|
85
|
+
Interleaved log output can still be meaningful if each log entry from
|
|
86
|
+
different contexts had a distinctive stamp. This is where NDCs come into
|
|
87
|
+
play.
|
|
88
|
+
|
|
89
|
+
Note that NDCs are managed on a per thread basis. NDC operations such as
|
|
90
|
+
push, pop(), clear(), getDepth() and setMaxDepth(int) affect the NDC of
|
|
91
|
+
the current thread only. NDCs of other threads remain unaffected.
|
|
92
|
+
...
|
|
93
|
+
|
|
94
|
+
An important difference between NDCs in Log4r vs Log4j is that you
|
|
95
|
+
do not have to called NDC.remove() when exiting a thread.
|
|
96
|
+
|
|
97
|
+
This class will automatically create Thread specific storage for the
|
|
98
|
+
current thread on the first call to any of its methods, i.e.
|
|
99
|
+
|
|
100
|
+
NDC.push( "client accept" );
|
|
101
|
+
|
|
102
|
+
New threads may inherit the NDC of the parent thread by making use of
|
|
103
|
+
the clone_stack() and inherit() methods. By default, the NDC is not
|
|
104
|
+
inherited automatically. This is unlike MDCs, which will inherit from
|
|
105
|
+
the main thread.
|
|
106
|
+
|
|
107
|
+
== Other Info
|
|
108
|
+
|
|
109
|
+
Version:: $Id: NDC.rb,v 1.5 2010/02/03 05:20:05 colbygk Exp $
|
|
110
|
+
Author:: Colby Gutierrez-Kraybill <colby(at)astro.berkeley.edu>
|
|
111
|
+
---
|
|
112
|
+
:nodoc:
|
|
113
|
+
---
|
|
114
|
+
:nodoc:
|
|
115
|
+
</pre>
|
|
116
|
+
|
|
117
|
+
</div>
|
|
118
|
+
|
|
119
|
+
</div>
|
|
120
|
+
</body>
|
|
121
|
+
</html>
|
|
122
|
+
|
|
@@ -0,0 +1,370 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="utf-8"?>
|
|
2
|
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
3
|
+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
4
|
+
|
|
5
|
+
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
6
|
+
<head>
|
|
7
|
+
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
|
|
8
|
+
|
|
9
|
+
<title>File: configurator.rb [1.1.7 Log4r API]</title>
|
|
10
|
+
|
|
11
|
+
<link type="text/css" media="screen" href="../rdoc.css" rel="stylesheet" />
|
|
12
|
+
|
|
13
|
+
<script src="../js/jquery.js" type="text/javascript"
|
|
14
|
+
charset="utf-8"></script>
|
|
15
|
+
<script src="../js/thickbox-compressed.js" type="text/javascript"
|
|
16
|
+
charset="utf-8"></script>
|
|
17
|
+
<script src="../js/quicksearch.js" type="text/javascript"
|
|
18
|
+
charset="utf-8"></script>
|
|
19
|
+
<script src="../js/darkfish.js" type="text/javascript"
|
|
20
|
+
charset="utf-8"></script>
|
|
21
|
+
</head>
|
|
22
|
+
|
|
23
|
+
<body class="file file-popup">
|
|
24
|
+
<div id="metadata">
|
|
25
|
+
<dl>
|
|
26
|
+
<dt class="modified-date">Last Modified</dt>
|
|
27
|
+
<dd class="modified-date">Thu Mar 18 19:31:06 -0800 2004</dd>
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
<dt class="requires">Requires</dt>
|
|
31
|
+
<dd class="requires">
|
|
32
|
+
<ul>
|
|
33
|
+
|
|
34
|
+
<li>log4r/logger</li>
|
|
35
|
+
|
|
36
|
+
<li>log4r/outputter/staticoutputter</li>
|
|
37
|
+
|
|
38
|
+
<li>log4r/lib/xmlloader</li>
|
|
39
|
+
|
|
40
|
+
<li>log4r/logserver</li>
|
|
41
|
+
|
|
42
|
+
<li>log4r/outputter/remoteoutputter</li>
|
|
43
|
+
|
|
44
|
+
</ul>
|
|
45
|
+
</dd>
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
</dl>
|
|
50
|
+
</div>
|
|
51
|
+
|
|
52
|
+
<div id="documentation">
|
|
53
|
+
|
|
54
|
+
<div class="description">
|
|
55
|
+
<h2>Description</h2>
|
|
56
|
+
<h1>Configuring <a href="../Log4r.html">Log4r</a> with <a href="../Log4r/Configurator.html">Log4r::Configurator</a></h1>
|
|
57
|
+
<p>
|
|
58
|
+
The Configurator class allows one to set up <a
|
|
59
|
+
href="../Log4r.html">Log4r</a> via XML. Additionally, Configurator contains
|
|
60
|
+
methods to configure any <a href="../Log4r.html">Log4r</a> defaults. In
|
|
61
|
+
particular, Configurator provides a method to customize the logging levels.
|
|
62
|
+
</p>
|
|
63
|
+
<p>
|
|
64
|
+
<a href="../Log4r.html">Log4r</a> is also configurable using YAML. For
|
|
65
|
+
that, there is a class similar to Configurator called <a
|
|
66
|
+
href="../Log4r/YamlConfigurator.html">Log4r::YamlConfigurator</a>. Please
|
|
67
|
+
see <a href="yamlconfigurator_rb.html">log4r/yamlconfigurator.rb</a> for
|
|
68
|
+
details.
|
|
69
|
+
</p>
|
|
70
|
+
<p>
|
|
71
|
+
REXML is required for XML configuration. Get REXML at <a
|
|
72
|
+
href="http://www.ruby-lang.org/en/raa-list.rhtml?name=REXML">www.ruby-lang.org/en/raa-list.rhtml?name=REXML</a>
|
|
73
|
+
</p>
|
|
74
|
+
<p>
|
|
75
|
+
To use the Configurator class,
|
|
76
|
+
</p>
|
|
77
|
+
<pre>
|
|
78
|
+
require 'log4r/configurator'
|
|
79
|
+
</pre>
|
|
80
|
+
<h2>Custom Levels</h2>
|
|
81
|
+
<p>
|
|
82
|
+
Suppose you want the following levels and ranks:
|
|
83
|
+
</p>
|
|
84
|
+
<pre>
|
|
85
|
+
Foo < Bar < Baz
|
|
86
|
+
</pre>
|
|
87
|
+
<p>
|
|
88
|
+
This is easily accomplished:
|
|
89
|
+
</p>
|
|
90
|
+
<pre>
|
|
91
|
+
Configurator.custom_levels('Foo', 'Bar', :Baz)
|
|
92
|
+
</pre>
|
|
93
|
+
<p>
|
|
94
|
+
The method accepts strings or symbols. However, custom levels must have
|
|
95
|
+
names that are valid for Ruby constants. Also, custom levels should be set
|
|
96
|
+
before anything else is done with <a href="../Log4r.html">Log4r</a>,
|
|
97
|
+
otherwise the default levels will be loaded.
|
|
98
|
+
</p>
|
|
99
|
+
<p>
|
|
100
|
+
You can set custom levels in XML. That’s covered in the following
|
|
101
|
+
section.
|
|
102
|
+
</p>
|
|
103
|
+
<h2>XML Configuration</h2>
|
|
104
|
+
<p>
|
|
105
|
+
If you have REXML, you can configure <a href="../Log4r.html">Log4r</a> with
|
|
106
|
+
XML. To do this, first write an XML configuration (which you can learn by
|
|
107
|
+
studying this document and the examples provided in the distribution) and
|
|
108
|
+
then load up the XML from within your program as follows:
|
|
109
|
+
</p>
|
|
110
|
+
<pre>
|
|
111
|
+
Configurator.load_xml_file('/path/to/file.xml')
|
|
112
|
+
</pre>
|
|
113
|
+
<p>
|
|
114
|
+
The <a href="../Log4r.html">Log4r</a> XML configuration system is very
|
|
115
|
+
flexible and powerful. In fact, it is somewhat preferable to configuring <a
|
|
116
|
+
href="../Log4r.html">Log4r</a> in Ruby. In order to take full advantage of
|
|
117
|
+
this feature, there are several concepts one must know. They are covered in
|
|
118
|
+
the following three sections.
|
|
119
|
+
</p>
|
|
120
|
+
<h3>Concept: XML Directives</h3>
|
|
121
|
+
<p>
|
|
122
|
+
The expressive power of Ruby has enabled a feature I call <em>XML
|
|
123
|
+
directives</em>. An XML directive is a name-value pair belonging to some
|
|
124
|
+
element. It may be represented as an attribute (name=“value”)
|
|
125
|
+
of the element, or as a child (<name>value</name>) of the element.
|
|
126
|
+
Therefore, you are free to specify information about an object as either an
|
|
127
|
+
attribute or an element. An example should clarify:
|
|
128
|
+
</p>
|
|
129
|
+
<pre>
|
|
130
|
+
<object data="value"/>
|
|
131
|
+
</pre>
|
|
132
|
+
<p>
|
|
133
|
+
Is equivalent to:
|
|
134
|
+
</p>
|
|
135
|
+
<pre>
|
|
136
|
+
<object>
|
|
137
|
+
<data>value</data>
|
|
138
|
+
</object>
|
|
139
|
+
</pre>
|
|
140
|
+
<p>
|
|
141
|
+
You can assume this behavior except where noted elsewhere in the API.
|
|
142
|
+
</p>
|
|
143
|
+
<h3>Concept: XML Parameters</h3>
|
|
144
|
+
<p>
|
|
145
|
+
A scheme which I call <em>XML parameters</em> enables one to utilize the
|
|
146
|
+
XML configuratin system for custom Outputters and Formatters. This requires
|
|
147
|
+
<b>no</b> extra work on your part, so long as your objects are set up using
|
|
148
|
+
hash arguments and can decode string values. That is, once you’ve
|
|
149
|
+
written a custom Outputter, it is automatically configurable in XML without
|
|
150
|
+
having to write any extra code.
|
|
151
|
+
</p>
|
|
152
|
+
<p>
|
|
153
|
+
An XML parameter is analogous to a hash argument to some object’s
|
|
154
|
+
<tt>new</tt> method. Consider these hash arguments to FileOutputter:
|
|
155
|
+
</p>
|
|
156
|
+
<pre>
|
|
157
|
+
:filename => '/path/to/logs/my.log'
|
|
158
|
+
:trunc => 'true'
|
|
159
|
+
</pre>
|
|
160
|
+
<p>
|
|
161
|
+
We can specify them in XML like this:
|
|
162
|
+
</p>
|
|
163
|
+
<pre>
|
|
164
|
+
<outputter type="FileOutputter" trunc="true">
|
|
165
|
+
<filename>/path/to/logs/my.log</filename>
|
|
166
|
+
...
|
|
167
|
+
</pre>
|
|
168
|
+
<p>
|
|
169
|
+
The name of the element/attribute is just the name of the parameter. Note
|
|
170
|
+
that the input will be a string, thus it’s wise to convert the data
|
|
171
|
+
in from strings in any custom classes (to_i for integers, etc). Now
|
|
172
|
+
let’s suppose you have defined a custom Outputter named MyOutputter
|
|
173
|
+
with the following additional hash args:
|
|
174
|
+
</p>
|
|
175
|
+
<pre>
|
|
176
|
+
:myarg1 => 'foo'
|
|
177
|
+
:myarg2 => 123
|
|
178
|
+
</pre>
|
|
179
|
+
<p>
|
|
180
|
+
Automagically, you can configure your Outputter like so:
|
|
181
|
+
</p>
|
|
182
|
+
<pre>
|
|
183
|
+
<outputter type="MyOutputter" myarg2="123">
|
|
184
|
+
<myarg1>foo</myarg1>
|
|
185
|
+
...
|
|
186
|
+
</pre>
|
|
187
|
+
<p>
|
|
188
|
+
Isn’t that nice? <tt>:-)</tt>
|
|
189
|
+
</p>
|
|
190
|
+
<h3>Concept: Variable Substitution</h3>
|
|
191
|
+
<p>
|
|
192
|
+
To kill the need for preprocessors, Configurator provides a means of
|
|
193
|
+
variable substitution for XML parameters at runtime. If you specify
|
|
194
|
+
<tt>#{foo}</tt> in an XML parameter value, Configurator will replace it
|
|
195
|
+
with the value of ‘foo’ in its parameter hashtable. The primary
|
|
196
|
+
idea is that you can figure stuff out in your program, say the log path,
|
|
197
|
+
and relay that information to the XML while it’s being loaded.
|
|
198
|
+
Secondarily, it is a way to have aliases within an XML document.
|
|
199
|
+
</p>
|
|
200
|
+
<p>
|
|
201
|
+
There are two ways to tell Configurator about these variables. The first
|
|
202
|
+
method we’ll cover is done within a Ruby program with Configurator[].
|
|
203
|
+
</p>
|
|
204
|
+
<pre>
|
|
205
|
+
Configurator['logpath'] = '/path/to/logs'
|
|
206
|
+
</pre>
|
|
207
|
+
<p>
|
|
208
|
+
Thereafter, any occurence of <tt>#{logpath}</tt> in each and every XML
|
|
209
|
+
parameter will be substituted with ‘/path/to/logs’. For
|
|
210
|
+
example:
|
|
211
|
+
</p>
|
|
212
|
+
<pre>
|
|
213
|
+
<filename>#{logpath}/mylog.log</filename>
|
|
214
|
+
</pre>
|
|
215
|
+
<p>
|
|
216
|
+
Becomes,
|
|
217
|
+
</p>
|
|
218
|
+
<pre>
|
|
219
|
+
<filename>/path/to/logs/mylog.log</filename>
|
|
220
|
+
</pre>
|
|
221
|
+
<p>
|
|
222
|
+
Aside from Configurator[], another way to define XML parameter variables is
|
|
223
|
+
to define <tt>parameters</tt> under the <tt><pre_config></tt> element
|
|
224
|
+
of an XML configuration:
|
|
225
|
+
</p>
|
|
226
|
+
<pre>
|
|
227
|
+
<pre_config>
|
|
228
|
+
<parameter name="logpath" value="/path/to/logs'/>
|
|
229
|
+
<parameter name="other" value="somethingelse'/>
|
|
230
|
+
...
|
|
231
|
+
</pre_config>
|
|
232
|
+
</pre>
|
|
233
|
+
<p>
|
|
234
|
+
Alternatively,
|
|
235
|
+
</p>
|
|
236
|
+
<pre>
|
|
237
|
+
<pre_config>
|
|
238
|
+
<parameters>
|
|
239
|
+
<logpath>/path/to/logs</logpath>
|
|
240
|
+
<other>somethingelse</other>
|
|
241
|
+
...
|
|
242
|
+
</parameters>
|
|
243
|
+
...
|
|
244
|
+
</pre>
|
|
245
|
+
<p>
|
|
246
|
+
The end result is the same as using Configurator[]. However, this method is
|
|
247
|
+
not dynamic. Configurator[] should be used when you want to set variables
|
|
248
|
+
from within Ruby.
|
|
249
|
+
</p>
|
|
250
|
+
<h1>XML Grammar</h1>
|
|
251
|
+
<p>
|
|
252
|
+
And now, here’s the XML grammar we use to configure <a
|
|
253
|
+
href="../Log4r.html">Log4r</a>.
|
|
254
|
+
</p>
|
|
255
|
+
<h2>Root Element</h2>
|
|
256
|
+
<p>
|
|
257
|
+
The root element is <tt><log4r_config></tt>. It can be embedded as a
|
|
258
|
+
node of any other element in an XML file. For instance:
|
|
259
|
+
</p>
|
|
260
|
+
<pre>
|
|
261
|
+
<my-xml-thing>
|
|
262
|
+
<customize-libraries>
|
|
263
|
+
<log4r_config>
|
|
264
|
+
<!-- log4r configuratin goes here -->
|
|
265
|
+
</log4r_config>
|
|
266
|
+
...
|
|
267
|
+
</pre>
|
|
268
|
+
<h2>Pre-config element</h2>
|
|
269
|
+
<p>
|
|
270
|
+
The pre_config element is a child of log4r_config and contains:
|
|
271
|
+
</p>
|
|
272
|
+
<ul>
|
|
273
|
+
<li>‘custom_levels’ element
|
|
274
|
+
|
|
275
|
+
</li>
|
|
276
|
+
<li>‘global’ element
|
|
277
|
+
|
|
278
|
+
</li>
|
|
279
|
+
<li>‘parameters’ element
|
|
280
|
+
|
|
281
|
+
</li>
|
|
282
|
+
<li>any number of ‘parameter’ elements
|
|
283
|
+
|
|
284
|
+
</li>
|
|
285
|
+
</ul>
|
|
286
|
+
<h3>Pre_config: Custom Levels</h3>
|
|
287
|
+
<p>
|
|
288
|
+
The custom_levels element is not an <em>XML directive</em> of pre_config.
|
|
289
|
+
It <b>must</b> be specified like this:
|
|
290
|
+
</p>
|
|
291
|
+
<pre>
|
|
292
|
+
<custom_levels>Foo, Bar, Baz</custom_levels>
|
|
293
|
+
</pre>
|
|
294
|
+
<p>
|
|
295
|
+
And <b>not</b> like this:
|
|
296
|
+
</p>
|
|
297
|
+
<pre>
|
|
298
|
+
<!-- NOT SUPPORTED -->
|
|
299
|
+
<custom_levels levels="Foo, Bar, Baz"/>
|
|
300
|
+
</pre>
|
|
301
|
+
<h3>Pre_config: Global Level</h3>
|
|
302
|
+
<pre>
|
|
303
|
+
<global level="DEBUG"/>
|
|
304
|
+
</pre>
|
|
305
|
+
<p>
|
|
306
|
+
or
|
|
307
|
+
</p>
|
|
308
|
+
<pre>
|
|
309
|
+
<global><level>DEBUG</level></global>
|
|
310
|
+
</pre>
|
|
311
|
+
<p>
|
|
312
|
+
Here, level is an XML directive of global.
|
|
313
|
+
</p>
|
|
314
|
+
<h3>Pre_config: Parameters</h3>
|
|
315
|
+
<p>
|
|
316
|
+
Parameters are variables that will be substituted later on. Please see the
|
|
317
|
+
<b>Concept: Variable Substitution</b> section above. Parameters are <em>XML
|
|
318
|
+
Directives</em>, which means they can be expressed using elements or
|
|
319
|
+
attributes. Here is an example:
|
|
320
|
+
</p>
|
|
321
|
+
<pre>
|
|
322
|
+
<parameter name="param name 1" value="param value 1">
|
|
323
|
+
<parameter name="param name 2" value="param value 2">
|
|
324
|
+
...
|
|
325
|
+
<parameters>
|
|
326
|
+
<param3>value3</param3>
|
|
327
|
+
<param4>value3</param4>
|
|
328
|
+
...
|
|
329
|
+
</pre>
|
|
330
|
+
<h3>Pre_config: Complete Example</h3>
|
|
331
|
+
<pre>
|
|
332
|
+
<log4r_config>
|
|
333
|
+
|
|
334
|
+
<pre_config>
|
|
335
|
+
<custom_levels>
|
|
336
|
+
Foo,Bar, Baz
|
|
337
|
+
</custom_levels>
|
|
338
|
+
<global level="Bar"/>
|
|
339
|
+
<parameters>
|
|
340
|
+
<logpath>/var/log/foo</logpath>
|
|
341
|
+
<mypattern>%l [%d] %m</mypattern>
|
|
342
|
+
</parameters>
|
|
343
|
+
</pre_config>
|
|
344
|
+
|
|
345
|
+
<!-- define some outputters and loggers -->
|
|
346
|
+
|
|
347
|
+
</log4r_config>
|
|
348
|
+
</pre>
|
|
349
|
+
<h2>Configuring <a href="../Log4r.html">Log4r</a> Objects</h2>
|
|
350
|
+
<p>
|
|
351
|
+
The XML configuration grammar for Loggers, Outputters and the like are
|
|
352
|
+
covered in the usage guidelines for those classes.
|
|
353
|
+
</p>
|
|
354
|
+
<h2>Order Doesn’t Matter</h2>
|
|
355
|
+
<p>
|
|
356
|
+
You can (it is hoped) define any of the XML objects in any order desired.
|
|
357
|
+
</p>
|
|
358
|
+
<h2>Other Info</h2>
|
|
359
|
+
<table>
|
|
360
|
+
<tr><td valign="top">Version:</td><td>$Id: configurator.rb,v 1.1.1.1 2004/03/19 03:31:06 fando Exp $
|
|
361
|
+
|
|
362
|
+
</td></tr>
|
|
363
|
+
</table>
|
|
364
|
+
|
|
365
|
+
</div>
|
|
366
|
+
|
|
367
|
+
</div>
|
|
368
|
+
</body>
|
|
369
|
+
</html>
|
|
370
|
+
|