Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / 15888492bec263e91f974f270d00e1752194e090 / . / org.jacoco.doc / docroot / doc / implementation.html
blob: e99e04907f1a752e039721e21b96f9bf10ccfa99 [file] [log] [blame]
Marc R. Hoffmanna2af15d2009-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. Hoffmann15888492009-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. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]7 <title>JaCoCo - Implementation Design</title>
8</head>
9<body>
10
Marc R. Hoffmann15888492009-07-30 11:46:53 +0000[diff] [blame^]11<div class="breadcrumb">
12 <a href="../index.html" class="el_session">JaCoCo</a> &gt;
13 <a href="index.html" class="el_group">Documentation</a> &gt;
14 <span class="el_source">Implementation Design</span>
15</div>
16
17<h1>Implementation Design</h1>
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]18
19<p>
20 This is a unordered list of implementation design decisions. Each topic tries
21 to follow this structure:
22</p>
23
24<ul>
25 <li>Problem statement</li>
26 <li>Proposed Solution</li>
27 <li>Alternatives and Discussion</li>
28</ul>
29
30
31<h2>Coverage Analysis Mechanism</h2>
32
Marc R. Hoffmann15888492009-07-30 11:46:53 +0000[diff] [blame^]33<p class="intro">
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]34 Coverage information has to be collected at runtime. For this purpose JaCoCo
35 creates instrumented versions of the original class definitions. The
36 instrumentation process happens on-the-fly during class loading using so
37 called Java agents.
38</p>
39
40<p>
41 There are several different approaches to collect coverage information. For
42 each approach different implementation techniques are known. The following
43 diagram gives an overview with the techniques used by JaCoCo highlighted:
44</p>
45
46<ul>
47 <li>Runtime Profiling
48 <ul>
49 <li>Java Virtual Machine Profiler Interface (JVMPI), until Java 1.4</li>
50 <li>Java Virtual Machine Tool Interface (JVMTI), since Java 1.5</li>
51 </ul>
52 </li>
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame]53 <li><span class="high">Instrumentation*</span>
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]54 <ul>
55 <li>Java Source Instrumentation</li>
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame]56 <li><span class="high">Byte Code Instrumentation'</span>
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]57 <ul>
58 <li>Offline
59 <ul>
60 <li>Replace Original Classes In-Place</li>
61 <li>Inject Instrumented Classes into the Class Path</li>
62 </ul>
63 </li>
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame]64 <li><span class="high">On-The-Fly*</span>
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]65 <ul>
66 <li>Special Classloader Implementions or Framework Specific Hooks</li>
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame]67 <li><span class="high">Java Agent*</span></li>
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]68 </ul>
69 </li>
70 </ul>
71 </li>
72 </ul>
73 </li>
74</ul>
75
76<p>
77 Byte code instrumentation is very fast, can be implemented in pure Java and
78 works with every Java VM. On-the-fly instrumentation with the Java agent
79 hook can be added to the JVM without any modification of the target
80 application.
81</p>
82
83<p>
84 The Java agent hook requires at least 1.5 JVMs. For reporting class files
85 compiled with debug information (line numbers) allow a good mapping back to
86 source level. Although some Java language constructs are compiled in a way
87 that the the coverage highlighting leads to unexpected results, especially
88 in case of implicitly generated code like default constructors or control
89 structures for finally statements.
90</p>
91
Marc R. Hoffmann5267b6c2009-07-05 16:34:27 +0000[diff] [blame]92
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]93<h2>Instrumentation Approach</h2>
94
Marc R. Hoffmann15888492009-07-30 11:46:53 +0000[diff] [blame^]95<p class="intro">
Marc R. Hoffmann872290a2009-07-06 15:33:15 +0000[diff] [blame]96 Instrumentation means inserting probes at certain check points in the Java
97 byte code. A probe generated piece of byte code that records the fact that it
98 has been executed. JaCoCo inserts probes at the end of every basic block.
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]99</p>
100
101<p>
Marc R. Hoffmann872290a2009-07-06 15:33:15 +0000[diff] [blame]102 A basic block is a piece of byte code that has a single entry point (the first
103 byte code instruction) and a single exit point (like <code>jump</code>,
104 <code>throw</code> or <code>return</code>). A basic code must not contain jump
105 targets except the entry point. One can think of basic blocks as the nodes in
106 a control flow graph of a method. Using basic block boundaries to insert code
107 coverage probes has been very successfully proven by
108 <a href="http://emma.sourceforge.net/">EMMA</a>.
109</p>
110
111<p>
112 Basic block instrumentation works regardless whether the class files have been
113 compiled with debug information for source lines. Source code highlighting
114 will of course not be possible without this debug information, but percentages
115 on method level can still be calculated. Basic block probes result in
116 reasonable overhead regarding class file size and execution overhead. As e.g.
117 multi-condition statements form several basic blocks partial line coverage is
118 possible. Calculating basic block relies on the Java byte code only, therefore
119 JaCoCo is independent of the source language and should also work with other
120 Java VM based languages like <a href="http://www.scala-lang.org/">Scala</a>.
121</p>
122
123<p>
124 The huge drawback of this approach is that fact, that basic blocks are
125 actually much smaller in the Java VM: Nearly every byte code instruction
126 (especially method invocations) can result in an exception. In this case the
127 block is left somewhere in the middle without hitting the probe, which leads
128 to unexpected results for example in case of negative tests. A possible
129 solutions would be to add exception handlers that trigger special probes.
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]130</p>
131
Marc R. Hoffmann5267b6c2009-07-05 16:34:27 +0000[diff] [blame]132<h2>Coverage Agent Isolation</h2>
133
Marc R. Hoffmann15888492009-07-30 11:46:53 +0000[diff] [blame^]134<p class="intro">
Marc R. Hoffmann5267b6c2009-07-05 16:34:27 +0000[diff] [blame]135 The Java agent is loaded by the application class loader. Therefore the
136 classes of the agent live in the same name space than the application classes
137 which can result in clashes especially with the third party library ASM. The
138 JoCoCo build therefore moves all agent classes into a unique package.
139</p>
140
141<p>
142 The JaCoCo build renames all classes contained in the
143 <code>jacocoagent.jar</code> into classes with a
Marc R. Hoffmann0948cb92009-07-06 09:15:28 +0000[diff] [blame]144 <code>org.jacoco.&lt;randomid&gt;</code> prefix, including the required ASM
145 library classes. The identifier is created from a random number. As the agent
146 does not provide any API, no one should be affected by this renaming. This
147 trick also allows that JaCoCo tests can be verified with JaCoCo.
Marc R. Hoffmann5267b6c2009-07-05 16:34:27 +0000[diff] [blame]148</p>
149
150
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]151<h2>Minimal Java Version</h2>
152
Marc R. Hoffmann15888492009-07-30 11:46:53 +0000[diff] [blame^]153<p class="intro">
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame]154 JaCoCo requires Java 1.5.
155</p>
156
157<p>
158 The Java agent mechanism used for on-the-fly instrumentation became available
159 with in Java 1.5 VMs. Coding and testing with Java 1.5 language level is more
160 efficient, less error-prone &ndash; and more fun. JaCoCo will still allow to
Marc R. Hoffmann5267b6c2009-07-05 16:34:27 +0000[diff] [blame]161 run against Java code compiled for older versions.
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]162</p>
163
164
165<h2>Byte Code Manipulation</h2>
166
Marc R. Hoffmann15888492009-07-30 11:46:53 +0000[diff] [blame^]167<p class="intro">
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame]168 Instrumentation requires mechanisms to modify and generate Java byte code.
169 JaCoCo uses the ASM library for this purpose.
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]170</p>
171
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame]172<p>
173 Implementing the Java byte code specification would be a extensive and
174 error-prone task. Therefore an existing library should be used. The
175 <a href="http://asm.objectweb.org/">ASM</a> library is lightweight, easy to
176 use and very efficient in terms of memory and CPU usage. It is actively
177 maintained and includes as huge regression test suite. Its simplified BSD
178 license is approved by the Eclipse Foundation for usage with EPL products.
179</p>
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]180
181<h2>Java Class Identity</h2>
182
Marc R. Hoffmann15888492009-07-30 11:46:53 +0000[diff] [blame^]183<p class="intro">
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]184 Each class loaded at runtime needs a unique identity to associate coverage data with.
185 JaCoCo creates such identities by a CRC64 hash code of the raw class definition.
186</p>
187
188<p>
189 In multi-classloader environments the plain name of a class does not
190 unambiguously identify a class. For example OSGi allows to use different
191 versions of the same class to be loaded within the same VM. In complex
192 deployment scenarios the actual version of the test target might be different
193 from current development version. A code coverage report should guarantee that
Marc R. Hoffmann5267b6c2009-07-05 16:34:27 +0000[diff] [blame]194 the presented figures are extracted from a valid test target. A hash code of
195 the class definitions allows a differentiate between classes and versions of a
196 class. The CRC64 hash computation is simple and fast resulting in a small 64
197 bit identifier.
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]198</p>
199
200<p>
201 The same class definition might be loaded by class loaders which will result
202 in different classes for the Java runtime system. For coverage analysis this
203 distinction should be irrelevant. Class definitions might be altered by other
204 instrumentation based technologies (e.g. AspectJ). In this case the hash code
205 will change and identity gets lost. On the other hand code coverage analysis
206 based on classes that have been somehow altered will produce unexpected
207 results. The CRC64 has code might produce so called <i>collisions</i>, i.e.
208 creating the same hash code for two different classes. Although CRC64 is not
209 cryptographically strong and collision examples can be easily computed, for
210 regular class files the collision probability is very low.
211</p>
212
213<h2>Coverage Runtime Dependency</h2>
214
Marc R. Hoffmann15888492009-07-30 11:46:53 +0000[diff] [blame^]215<p class="intro">
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame]216 Instrumented code typically gets a dependency to a coverage runtime which is
217 responsible for collecting and storing execution data. JaCoCo uses JRE types
218 and interfaces only in generated instrumentation code.
219</p>
220
221<p>
222 Making a runtime library available to all instrumented classes can be a
223 painful or impossible task in frameworks that use there own class loading
Marc R. Hoffmann5267b6c2009-07-05 16:34:27 +0000[diff] [blame]224 mechanisms. Therefore JaCoCo decouples the instrumented classes and the
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame]225 coverage runtime through official JRE API types.
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]226</p>
227
Marc R. Hoffmann5267b6c2009-07-05 16:34:27 +0000[diff] [blame]228<h2>Memory Usage</h2>
229
Marc R. Hoffmann15888492009-07-30 11:46:53 +0000[diff] [blame^]230<p class="intro">
Marc R. Hoffmann5267b6c2009-07-05 16:34:27 +0000[diff] [blame]231
232</p>
233
234<p>
Marc R. Hoffmann872290a2009-07-06 15:33:15 +0000[diff] [blame]235 TODO: Streaming, Deep first
Marc R. Hoffmann5267b6c2009-07-05 16:34:27 +0000[diff] [blame]236</p>
237
238<h2>Java Element Identifiers</h2>
239
Marc R. Hoffmann15888492009-07-30 11:46:53 +0000[diff] [blame^]240<p class="intro">
Marc R. Hoffmann5267b6c2009-07-05 16:34:27 +0000[diff] [blame]241 The Java language and the Java VM use different String representation formats
242 for Java elements. For example while a type reference in Java reads like
243 <code>java.lang.Object</code>, the VM references the same type as
244 <code>Ljava/lang/Object;</code>. The JaCoCo API is based on VM identifiers only.
245</p>
246
247<p>
248 Using VM identifiers directly does not cause any transformation overhead at
249 runtime. There are several programming languages based on the Java VM that
250 might use different notations. Specific transformations should therefore only
251 happen at the user interface level, for example while report generation.
252</p>
253
254<h2>Modularization of the JaCoCo implementation</h2>
255
Marc R. Hoffmann15888492009-07-30 11:46:53 +0000[diff] [blame^]256<p class="intro">
Marc R. Hoffmann5267b6c2009-07-05 16:34:27 +0000[diff] [blame]257 JaCoCo is implemented in several modules providing different functionality.
258 These modules are provided as OSGi bundles with proper manifest files. But
259 there is no dependencies on OSGi itself.
260</p>
261
262<p>
263 Using OSGi bundles allows well defines dependencies at development time and
264 at runtime in OSGi containers. As there are no dependencies on OSGi, the
265 bundles can also be used as regular JAR files.
266</p>
267
Marc R. Hoffmann15888492009-07-30 11:46:53 +0000[diff] [blame^]268<div class="footer">
269 <div style="float:right">@VERSION@</div>
270 <a href="license.html">Copyright</a> &copy; 2009 Mountainminds GmbH &amp; Co. KG and Contributors
271</div>
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]272
273</body>
274</html>