Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 1 | <?xml version="1.0" encoding="ISO-8859-1" ?>
|
| 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
| 3 | <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
|
| 4 | <head>
|
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 6 | <link rel="stylesheet" href=".resources/doc.css" charset="ISO-8859-1" type="text/css" />
|
Marc R. Hoffmann | a760f32 | 2010-03-10 22:23:52 +0000 | [diff] [blame] | 7 | <link rel="stylesheet" href="../coverage/.resources/prettify.css" charset="ISO-8859-1" type="text/css" />
|
Marc R. Hoffmann | d7d2f75 | 2010-05-06 21:12:31 +0000 | [diff] [blame^] | 8 | <link rel="shortcut icon" href=".resources/report.gif" type="image/gif" />
|
Marc R. Hoffmann | a760f32 | 2010-03-10 22:23:52 +0000 | [diff] [blame] | 9 | <script type="text/javascript" src="../coverage/.resources/prettify.js"></script>
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 10 | <title>JaCoCo - Implementation Design</title>
|
| 11 | </head>
|
Marc R. Hoffmann | a760f32 | 2010-03-10 22:23:52 +0000 | [diff] [blame] | 12 | <body onload="prettyPrint()">
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 13 |
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 14 | <div class="breadcrumb">
|
Marc R. Hoffmann | d7d2f75 | 2010-05-06 21:12:31 +0000 | [diff] [blame^] | 15 | <a href="../index.html" class="el_report">JaCoCo</a> >
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 16 | <a href="index.html" class="el_group">Documentation</a> >
|
| 17 | <span class="el_source">Implementation Design</span>
|
| 18 | </div>
|
Marc R. Hoffmann | 17be269 | 2010-02-02 05:44:47 +0000 | [diff] [blame] | 19 | <div id="content">
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 20 |
|
| 21 | <h1>Implementation Design</h1>
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 22 |
|
| 23 | <p>
|
| 24 | This is a unordered list of implementation design decisions. Each topic tries
|
| 25 | to follow this structure:
|
| 26 | </p>
|
| 27 |
|
| 28 | <ul>
|
| 29 | <li>Problem statement</li>
|
| 30 | <li>Proposed Solution</li>
|
| 31 | <li>Alternatives and Discussion</li>
|
| 32 | </ul>
|
| 33 |
|
| 34 |
|
| 35 | <h2>Coverage Analysis Mechanism</h2>
|
| 36 |
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 37 | <p class="intro">
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 38 | Coverage information has to be collected at runtime. For this purpose JaCoCo
|
| 39 | creates instrumented versions of the original class definitions. The
|
| 40 | instrumentation process happens on-the-fly during class loading using so
|
| 41 | called Java agents.
|
| 42 | </p>
|
| 43 |
|
| 44 | <p>
|
| 45 | There are several different approaches to collect coverage information. For
|
| 46 | each approach different implementation techniques are known. The following
|
| 47 | diagram gives an overview with the techniques used by JaCoCo highlighted:
|
| 48 | </p>
|
| 49 |
|
| 50 | <ul>
|
| 51 | <li>Runtime Profiling
|
| 52 | <ul>
|
| 53 | <li>Java Virtual Machine Profiler Interface (JVMPI), until Java 1.4</li>
|
| 54 | <li>Java Virtual Machine Tool Interface (JVMTI), since Java 1.5</li>
|
| 55 | </ul>
|
| 56 | </li>
|
Marc R. Hoffmann | e52a0ef | 2009-06-16 20:28:45 +0000 | [diff] [blame] | 57 | <li><span class="high">Instrumentation*</span>
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 58 | <ul>
|
| 59 | <li>Java Source Instrumentation</li>
|
Marc R. Hoffmann | c4b2078 | 2009-10-02 13:28:46 +0000 | [diff] [blame] | 60 | <li><span class="high">Byte Code Instrumentation*</span>
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 61 | <ul>
|
| 62 | <li>Offline
|
| 63 | <ul>
|
| 64 | <li>Replace Original Classes In-Place</li>
|
| 65 | <li>Inject Instrumented Classes into the Class Path</li>
|
| 66 | </ul>
|
| 67 | </li>
|
Marc R. Hoffmann | e52a0ef | 2009-06-16 20:28:45 +0000 | [diff] [blame] | 68 | <li><span class="high">On-The-Fly*</span>
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 69 | <ul>
|
| 70 | <li>Special Classloader Implementions or Framework Specific Hooks</li>
|
Marc R. Hoffmann | e52a0ef | 2009-06-16 20:28:45 +0000 | [diff] [blame] | 71 | <li><span class="high">Java Agent*</span></li>
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 72 | </ul>
|
| 73 | </li>
|
| 74 | </ul>
|
| 75 | </li>
|
| 76 | </ul>
|
| 77 | </li>
|
| 78 | </ul>
|
| 79 |
|
| 80 | <p>
|
| 81 | Byte code instrumentation is very fast, can be implemented in pure Java and
|
| 82 | works with every Java VM. On-the-fly instrumentation with the Java agent
|
| 83 | hook can be added to the JVM without any modification of the target
|
| 84 | application.
|
| 85 | </p>
|
| 86 |
|
| 87 | <p>
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 88 | The Java agent hook requires at least 1.5 JVMs. Class files compiled with
|
| 89 | debug information (line numbers) allow for source code highlighting. Unluckily
|
| 90 | some Java language constructs get compiled to byte code that produces
|
| 91 | unexpected highlighting results, especially in case of implicitly generated
|
| 92 | code like default constructors or control structures for finally statements.
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 93 | </p>
|
| 94 |
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 95 |
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 96 | <h2>Instrumentation Approach</h2>
|
| 97 |
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 98 | <p class="intro">
|
Marc R. Hoffmann | 872290a | 2009-07-06 15:33:15 +0000 | [diff] [blame] | 99 | Instrumentation means inserting probes at certain check points in the Java
|
Marc R. Hoffmann | c4b2078 | 2009-10-02 13:28:46 +0000 | [diff] [blame] | 100 | byte code. A probe is a generated piece of byte code that records the fact
|
| 101 | that it has been executed. JaCoCo inserts probes at the end of every basic
|
| 102 | block.
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 103 | </p>
|
| 104 |
|
| 105 | <p>
|
Marc R. Hoffmann | 872290a | 2009-07-06 15:33:15 +0000 | [diff] [blame] | 106 | A basic block is a piece of byte code that has a single entry point (the first
|
| 107 | byte code instruction) and a single exit point (like <code>jump</code>,
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 108 | <code>throw</code> or <code>return</code>). A basic block must not contain jump
|
Marc R. Hoffmann | 872290a | 2009-07-06 15:33:15 +0000 | [diff] [blame] | 109 | targets except the entry point. One can think of basic blocks as the nodes in
|
| 110 | a control flow graph of a method. Using basic block boundaries to insert code
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 111 | coverage probes has been very successfully utilized by
|
Marc R. Hoffmann | 872290a | 2009-07-06 15:33:15 +0000 | [diff] [blame] | 112 | <a href="http://emma.sourceforge.net/">EMMA</a>.
|
| 113 | </p>
|
| 114 |
|
| 115 | <p>
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 116 | Basic block instrumentation works regardless of whether the class files have been
|
Marc R. Hoffmann | 872290a | 2009-07-06 15:33:15 +0000 | [diff] [blame] | 117 | compiled with debug information for source lines. Source code highlighting
|
| 118 | will of course not be possible without this debug information, but percentages
|
| 119 | on method level can still be calculated. Basic block probes result in
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 120 | reasonable overhead regarding class file size and performance. Partial line
|
| 121 | coverage can occur if a line contains more than one statement or a statement
|
| 122 | gets compiled into byte code forming more than one basic block (e.g. boolean
|
| 123 | assignments). Calculating basic block relies on the Java byte code only, therefore
|
Marc R. Hoffmann | 872290a | 2009-07-06 15:33:15 +0000 | [diff] [blame] | 124 | JaCoCo is independent of the source language and should also work with other
|
| 125 | Java VM based languages like <a href="http://www.scala-lang.org/">Scala</a>.
|
| 126 | </p>
|
| 127 |
|
| 128 | <p>
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 129 | The huge drawback of this approach is the fact that basic blocks are
|
Marc R. Hoffmann | 872290a | 2009-07-06 15:33:15 +0000 | [diff] [blame] | 130 | actually much smaller in the Java VM: Nearly every byte code instruction
|
| 131 | (especially method invocations) can result in an exception. In this case the
|
| 132 | block is left somewhere in the middle without hitting the probe, which leads
|
| 133 | to unexpected results for example in case of negative tests. A possible
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 134 | solution would be to add exception handlers that trigger special probes.
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 135 | </p>
|
| 136 |
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 137 | <h2>Coverage Agent Isolation</h2>
|
| 138 |
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 139 | <p class="intro">
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 140 | The Java agent is loaded by the application class loader. Therefore the
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 141 | classes of the agent live in the same name space like the application classes
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 142 | which can result in clashes especially with the third party library ASM. The
|
| 143 | JoCoCo build therefore moves all agent classes into a unique package.
|
| 144 | </p>
|
| 145 |
|
| 146 | <p>
|
| 147 | The JaCoCo build renames all classes contained in the
|
| 148 | <code>jacocoagent.jar</code> into classes with a
|
Marc R. Hoffmann | a942c89 | 2010-03-10 21:33:26 +0000 | [diff] [blame] | 149 | <code>org.jacoco.agent.rt_<randomid></code> prefix, including the
|
| 150 | required ASM library classes. The identifier is created from a random number.
|
| 151 | As the agent does not provide any API, no one should be affected by this
|
| 152 | renaming. This trick also allows that JaCoCo tests can be verified with
|
| 153 | JaCoCo.
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 154 | </p>
|
| 155 |
|
| 156 |
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 157 | <h2>Minimal Java Version</h2>
|
| 158 |
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 159 | <p class="intro">
|
Marc R. Hoffmann | e52a0ef | 2009-06-16 20:28:45 +0000 | [diff] [blame] | 160 | JaCoCo requires Java 1.5.
|
| 161 | </p>
|
| 162 |
|
| 163 | <p>
|
| 164 | The Java agent mechanism used for on-the-fly instrumentation became available
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 165 | with Java 1.5 VMs. Coding and testing with Java 1.5 language level is more
|
| 166 | efficient, less error-prone – and more fun than with older versions.
|
| 167 | JaCoCo will still allow to run against Java code compiled for these.
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 168 | </p>
|
| 169 |
|
| 170 |
|
| 171 | <h2>Byte Code Manipulation</h2>
|
| 172 |
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 173 | <p class="intro">
|
Marc R. Hoffmann | e52a0ef | 2009-06-16 20:28:45 +0000 | [diff] [blame] | 174 | Instrumentation requires mechanisms to modify and generate Java byte code.
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 175 | JaCoCo uses the ASM library for this purpose internally.
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 176 | </p>
|
| 177 |
|
Marc R. Hoffmann | e52a0ef | 2009-06-16 20:28:45 +0000 | [diff] [blame] | 178 | <p>
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 179 | Implementing the Java byte code specification would be an extensive and
|
Marc R. Hoffmann | e52a0ef | 2009-06-16 20:28:45 +0000 | [diff] [blame] | 180 | error-prone task. Therefore an existing library should be used. The
|
| 181 | <a href="http://asm.objectweb.org/">ASM</a> library is lightweight, easy to
|
| 182 | use and very efficient in terms of memory and CPU usage. It is actively
|
| 183 | maintained and includes as huge regression test suite. Its simplified BSD
|
| 184 | license is approved by the Eclipse Foundation for usage with EPL products.
|
| 185 | </p>
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 186 |
|
| 187 | <h2>Java Class Identity</h2>
|
| 188 |
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 189 | <p class="intro">
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 190 | Each class loaded at runtime needs a unique identity to associate coverage data with.
|
| 191 | JaCoCo creates such identities by a CRC64 hash code of the raw class definition.
|
| 192 | </p>
|
| 193 |
|
| 194 | <p>
|
| 195 | In multi-classloader environments the plain name of a class does not
|
| 196 | unambiguously identify a class. For example OSGi allows to use different
|
| 197 | versions of the same class to be loaded within the same VM. In complex
|
| 198 | deployment scenarios the actual version of the test target might be different
|
| 199 | from current development version. A code coverage report should guarantee that
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 200 | the presented figures are extracted from a valid test target. A hash code of
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 201 | the class definitions allows to differentiate between classes and versions of
|
| 202 | classes. The CRC64 hash computation is simple and fast resulting in a small 64
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 203 | bit identifier.
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 204 | </p>
|
| 205 |
|
| 206 | <p>
|
| 207 | The same class definition might be loaded by class loaders which will result
|
| 208 | in different classes for the Java runtime system. For coverage analysis this
|
| 209 | distinction should be irrelevant. Class definitions might be altered by other
|
| 210 | instrumentation based technologies (e.g. AspectJ). In this case the hash code
|
| 211 | will change and identity gets lost. On the other hand code coverage analysis
|
| 212 | based on classes that have been somehow altered will produce unexpected
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 213 | results. The CRC64 code might produce so called <i>collisions</i>, i.e.
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 214 | creating the same hash code for two different classes. Although CRC64 is not
|
| 215 | cryptographically strong and collision examples can be easily computed, for
|
| 216 | regular class files the collision probability is very low.
|
| 217 | </p>
|
| 218 |
|
| 219 | <h2>Coverage Runtime Dependency</h2>
|
| 220 |
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 221 | <p class="intro">
|
Marc R. Hoffmann | e52a0ef | 2009-06-16 20:28:45 +0000 | [diff] [blame] | 222 | Instrumented code typically gets a dependency to a coverage runtime which is
|
| 223 | responsible for collecting and storing execution data. JaCoCo uses JRE types
|
Marc R. Hoffmann | a942c89 | 2010-03-10 21:33:26 +0000 | [diff] [blame] | 224 | only in generated instrumentation code.
|
Marc R. Hoffmann | e52a0ef | 2009-06-16 20:28:45 +0000 | [diff] [blame] | 225 | </p>
|
| 226 |
|
| 227 | <p>
|
| 228 | Making a runtime library available to all instrumented classes can be a
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 229 | painful or impossible task in frameworks that use their own class loading
|
Marc R. Hoffmann | 9263b7b | 2010-01-31 10:20:30 +0000 | [diff] [blame] | 230 | mechanisms. Since Java 1.6 <code>java.lang.instrument.Instrumentation</code>
|
| 231 | has an API to extends the bootsstrap loader. As our minimum target is Java 1.5
|
| 232 | JaCoCo decouples the instrumented classes and the coverage runtime through
|
Marc R. Hoffmann | a942c89 | 2010-03-10 21:33:26 +0000 | [diff] [blame] | 233 | official JRE API types only. The instrumented classes communicate through the
|
| 234 | <code>Object.equals(Object)</code> method with the runtime. A instrumented
|
| 235 | class can retrieve its probe array instance with the following code. Note
|
| 236 | that only JRE APIs are used:
|
| 237 | </p>
|
| 238 |
|
| 239 |
|
Marc R. Hoffmann | a760f32 | 2010-03-10 22:23:52 +0000 | [diff] [blame] | 240 | <pre class="source lang-java">
|
Marc R. Hoffmann | a942c89 | 2010-03-10 21:33:26 +0000 | [diff] [blame] | 241 | <span class="nr"> 1</span>Object access = ... // Retrieve instance
|
| 242 | <span class="nr"> 2</span>
|
| 243 | <span class="nr"> 3</span>Object[] args = new Object[3];
|
| 244 | <span class="nr"> 4</span>args[0] = Long.valueOf(8060044182221863588); // class id
|
| 245 | <span class="nr"> 5</span>args[1] = "com/example/MyClass"; // class name
|
| 246 | <span class="nr"> 6</span>args[2] = Integer.valueOf(24); // probe count
|
| 247 | <span class="nr"> 7</span>
|
| 248 | <span class="nr"> 8</span>access.equals(args);
|
| 249 | <span class="nr"> 9</span>
|
| 250 | <span class="nr"> 10</span>boolean[] probes = (boolean[]) args[0];
|
| 251 | </pre>
|
| 252 |
|
| 253 | <p>
|
| 254 | The most tricky part takes place in line 1 and is not shown in the snippet
|
| 255 | above. The object instance providing access to the coverage runtime through
|
| 256 | its <code>equals()</code> method has to be obtained. Different approaches have
|
| 257 | been implemented and tested so far:
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 258 | </p>
|
| 259 |
|
Marc R. Hoffmann | 402370f | 2009-08-10 14:02:23 +0000 | [diff] [blame] | 260 | <ul>
|
Marc R. Hoffmann | a942c89 | 2010-03-10 21:33:26 +0000 | [diff] [blame] | 261 | <li><b><code>SystemPropertiesRuntime</code></b>: This approach stores the
|
| 262 | object instance under a system property. This solution breaks the contract
|
| 263 | that system properties must only contain <code>java.lang.String</code>
|
| 264 | values and therefore causes trouble in applications that rely on this
|
| 265 | definition (e.g. Ant).</li>
|
Marc R. Hoffmann | 9263b7b | 2010-01-31 10:20:30 +0000 | [diff] [blame] | 266 | <li><b><code>LoggerRuntime</code></b>: Here we use a shared
|
Marc R. Hoffmann | a942c89 | 2010-03-10 21:33:26 +0000 | [diff] [blame] | 267 | <code>java.util.logging.Logger</code> and communicate through the logging
|
| 268 | parameter array instead of a <code>equals()</code> method. The coverage
|
| 269 | runtime registers a custom <code>Handler</code> to receive the parameter
|
| 270 | array. This approach might break environments that install their own log
|
Marc R. Hoffmann | 9263b7b | 2010-01-31 10:20:30 +0000 | [diff] [blame] | 271 | managers (e.g. Glassfish).</li>
|
Marc R. Hoffmann | a942c89 | 2010-03-10 21:33:26 +0000 | [diff] [blame] | 272 | <li><b><code>ModifiedSystemClassRuntime</code></b>: This approach adds a
|
| 273 | public static field to an existing JRE class through instrumentation. Unlike
|
| 274 | the other methods above this is only possible for environments where a Java
|
Marc R. Hoffmann | 9263b7b | 2010-01-31 10:20:30 +0000 | [diff] [blame] | 275 | agent is active.</li>
|
Marc R. Hoffmann | 402370f | 2009-08-10 14:02:23 +0000 | [diff] [blame] | 276 | </ul>
|
| 277 |
|
Marc R. Hoffmann | 9263b7b | 2010-01-31 10:20:30 +0000 | [diff] [blame] | 278 | <p>
|
| 279 | The current JaCoCo Java agent implementation uses the
|
Marc R. Hoffmann | a942c89 | 2010-03-10 21:33:26 +0000 | [diff] [blame] | 280 | <code>ModifiedSystemClassRuntime</code> adding a field to the class
|
Marc R. Hoffmann | 6751fe4 | 2010-02-01 18:18:24 +0000 | [diff] [blame] | 281 | <code>java.sql.Types</code>.
|
Marc R. Hoffmann | 9263b7b | 2010-01-31 10:20:30 +0000 | [diff] [blame] | 282 | </p>
|
| 283 |
|
Marc R. Hoffmann | 402370f | 2009-08-10 14:02:23 +0000 | [diff] [blame] | 284 |
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 285 | <h2>Memory Usage</h2>
|
| 286 |
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 287 | <p class="intro">
|
Marc R. Hoffmann | 58d7621 | 2009-10-08 15:40:46 +0000 | [diff] [blame] | 288 | Coverage analysis for huge projects with several thousand classes or hundred
|
| 289 | thousand lines of code should be possible. To allow this with reasonable
|
| 290 | memory usage the coverage analysis is based on streaming patterns and
|
| 291 | "depth first" traversals.
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 292 | </p>
|
| 293 |
|
| 294 | <p>
|
Marc R. Hoffmann | 58d7621 | 2009-10-08 15:40:46 +0000 | [diff] [blame] | 295 | The complete data tree of a huge coverage report is too big to fit into a
|
| 296 | reasonable heap memory configuration. Therefore the coverage analysis and
|
| 297 | report generation is implemented as "depth first" traversals. Which means that
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 298 | at any point in time only the following data has to be held in working memory:
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 299 | </p>
|
| 300 |
|
Marc R. Hoffmann | 58d7621 | 2009-10-08 15:40:46 +0000 | [diff] [blame] | 301 | <ul>
|
| 302 | <li>A single class which is currently processed.</li>
|
| 303 | <li>The summary information of all parents of this class (package, groups).</li>
|
| 304 | </ul>
|
| 305 |
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 306 | <h2>Java Element Identifiers</h2>
|
| 307 |
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 308 | <p class="intro">
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 309 | The Java language and the Java VM use different String representation formats
|
| 310 | for Java elements. For example while a type reference in Java reads like
|
| 311 | <code>java.lang.Object</code>, the VM references the same type as
|
| 312 | <code>Ljava/lang/Object;</code>. The JaCoCo API is based on VM identifiers only.
|
| 313 | </p>
|
| 314 |
|
| 315 | <p>
|
| 316 | Using VM identifiers directly does not cause any transformation overhead at
|
| 317 | runtime. There are several programming languages based on the Java VM that
|
| 318 | might use different notations. Specific transformations should therefore only
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 319 | happen at the user interface level, for example during report generation.
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 320 | </p>
|
| 321 |
|
| 322 | <h2>Modularization of the JaCoCo implementation</h2>
|
| 323 |
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 324 | <p class="intro">
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 325 | JaCoCo is implemented in several modules providing different functionality.
|
| 326 | These modules are provided as OSGi bundles with proper manifest files. But
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 327 | there are no dependencies on OSGi itself.
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 328 | </p>
|
| 329 |
|
| 330 | <p>
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 331 | Using OSGi bundles allows well defined dependencies at development time and
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 332 | at runtime in OSGi containers. As there are no dependencies on OSGi, the
|
Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 333 | bundles can also be used like regular JAR files.
|
Marc R. Hoffmann | 5267b6c | 2009-07-05 16:34:27 +0000 | [diff] [blame] | 334 | </p>
|
| 335 |
|
Marc R. Hoffmann | 17be269 | 2010-02-02 05:44:47 +0000 | [diff] [blame] | 336 | </div>
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 337 | <div class="footer">
|
Marc R. Hoffmann | b623ffb | 2010-05-06 19:48:08 +0000 | [diff] [blame] | 338 | <span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
|
Marc R. Hoffmann | df6ff96 | 2010-04-09 15:31:22 +0000 | [diff] [blame] | 339 | <a href="license.html">Copyright</a> © @copyright.years@ Mountainminds GmbH & Co. KG and Contributors
|
Marc R. Hoffmann | 1588849 | 2009-07-30 11:46:53 +0000 | [diff] [blame] | 340 | </div>
|
Marc R. Hoffmann | a2af15d | 2009-06-07 21:15:05 +0000 | [diff] [blame] | 341 |
|
| 342 | </body>
|
| 343 | </html> |