1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<head>
<name>Advanced Usage of GroboCoverage</name>
<doc-version>$Date: 2004/04/17 08:24:40 $</doc-version>
<author>Matt Albrecht</author>
</head>
<body>
<section>How GroboCoverage Works</section>
<p>
GroboCoverage works by inserting "probes" into the post-compiled class files.
These probes call out to a logger (more on that later), telling it which
class, method index, and probe index was invoked.
</p>
<p>
During the post-compilation of the class files, a set of data files get
generated, which record what a method index and probe index translate into
with regards to the source file.
</p>
<p>
The reporting phase combines the post-compilation data files with the log
data from the loggers to generate XML reports, and from that HTML reports
using XSL-T.
</p>
<section>The Logger</section>
<p>
The base logger class
(<code>net.sourceforge.groboutils.codecoverage.v2.logger.CoverageLogger</code>)
gets called at each probe point through invoking its <code>cover</code>
method, and redirects these invocations to the different registered channels
(a channel in the logger corresponds to an analysis measure during
post-compilation).
</p>
<p>
This static class discovers the registered channels at class load time through
the <code>/grobocoverage.properties</code> file (relative to the
classpath). If that resource isn't found, then the initialization uses
the system properties.
</p>
<p>
The initialization routine creates a number of channels from the
specified logger factory (whose fully-qualified class name is given in the
properties with the key "factory"). The number of channels comes from the
key "channel-count". All property keys starting with "logger." are passed
to the factory class for initialization.
</p>
<p>
Currently, all logger implementations output the probe information to
plain text files in a logging directory (specified by the key
"logger.dir"), one file per class. The format of this file is simply a
series of lines, each specifying a single probe:
<pre>
<i>methodIndex</i>,<i>probeIndex</i>
</pre>
</p>
<p>
There can be duplicates of these method/probe pairs, which will be condensed
down during report parsing. The filename reflects the class name with a
CRC check (so different class files with the same name don't confuse the
logger), and each channel outputs to its own sub-directory in this logging
directory.
</p>
<p>
This means that if you have several coverage runs, logging to different
directories (or even across machines), all you need to do is concatenate
the files with the same name together (order isn't important), and copy
the one-off log files into those directories. The reporting task will
do the rest
</p>
<p>
However, an alternate logger style, called the "single" style, puts all the
logging data into a single file. It requires modifying the
<code><grobo-report></code> task slightly, but makes for a much
easier merge on the files. In order to prevent some classloader problems, this
style can create multiple output files inside the log directory. Due to
this, the report filter will scan that directory for all "single" files.
This makes the task of merging multiple files moot - just copy all the
"single" style files into the log directory, and generate the report.
The output format looks like:
<pre>
<i>channel</i>,<i>class signature</i>,<i>methodIndex</i>,<i>probeIndex</i>
</pre>
per line.
</p>
<section>The Probes</section>
<p>
Each probe added to the post-compiled class files adds several instructions
to the bytecode. They setup the invocation to the static method in the
<code>CoverageLogger</code> (see above) to reflect the current probe
and current method.
</p>
<!--
<section>Customizing Your Reports</section>
<p>
Are the generated reports not what you want? ...
</p>
<p>
<i>Describe how to use the style tag to make your own reports with your own
XSL files.</i>
</p>
-->
</body>
</document>
|
