Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / e52a0ef456236a2244846b0018ae5b947cdb8958 / . / org.jacoco.doc / docroot / doc / implementation.html
blob: 6894ead03d6d713249842f5f077cd294cf8a9b7b [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" />
6 <link rel="stylesheet" href="book.css" charset="ISO-8859-1" type="text/css" />
7 <title>JaCoCo - Implementation Design</title>
8</head>
9<body>
10
11<h1>JaCoCo - Implementation Design</h1>
12
13<p>
14 This is a unordered list of implementation design decisions. Each topic tries
15 to follow this structure:
16</p>
17
18<ul>
19 <li>Problem statement</li>
20 <li>Proposed Solution</li>
21 <li>Alternatives and Discussion</li>
22</ul>
23
24
25<h2>Coverage Analysis Mechanism</h2>
26
27<p class="Note">
28 Coverage information has to be collected at runtime. For this purpose JaCoCo
29 creates instrumented versions of the original class definitions. The
30 instrumentation process happens on-the-fly during class loading using so
31 called Java agents.
32</p>
33
34<p>
35 There are several different approaches to collect coverage information. For
36 each approach different implementation techniques are known. The following
37 diagram gives an overview with the techniques used by JaCoCo highlighted:
38</p>
39
40<ul>
41 <li>Runtime Profiling
42 <ul>
43 <li>Java Virtual Machine Profiler Interface (JVMPI), until Java 1.4</li>
44 <li>Java Virtual Machine Tool Interface (JVMTI), since Java 1.5</li>
45 </ul>
46 </li>
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame^]47 <li><span class="high">Instrumentation*</span>
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]48 <ul>
49 <li>Java Source Instrumentation</li>
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame^]50 <li><span class="high">Byte Code Instrumentation'</span>
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]51 <ul>
52 <li>Offline
53 <ul>
54 <li>Replace Original Classes In-Place</li>
55 <li>Inject Instrumented Classes into the Class Path</li>
56 </ul>
57 </li>
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame^]58 <li><span class="high">On-The-Fly*</span>
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]59 <ul>
60 <li>Special Classloader Implementions or Framework Specific Hooks</li>
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame^]61 <li><span class="high">Java Agent*</span></li>
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]62 </ul>
63 </li>
64 </ul>
65 </li>
66 </ul>
67 </li>
68</ul>
69
70<p>
71 Byte code instrumentation is very fast, can be implemented in pure Java and
72 works with every Java VM. On-the-fly instrumentation with the Java agent
73 hook can be added to the JVM without any modification of the target
74 application.
75</p>
76
77<p>
78 The Java agent hook requires at least 1.5 JVMs. For reporting class files
79 compiled with debug information (line numbers) allow a good mapping back to
80 source level. Although some Java language constructs are compiled in a way
81 that the the coverage highlighting leads to unexpected results, especially
82 in case of implicitly generated code like default constructors or control
83 structures for finally statements.
84</p>
85
86<h2>Instrumentation Approach</h2>
87
88<p class="Note">
89 Basic Block
90</p>
91
92<p>
93 Problem: Exceptions
94</p>
95
96<h2>Minimal Java Version</h2>
97
98<p class="Note">
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame^]99 JaCoCo requires Java 1.5.
100</p>
101
102<p>
103 The Java agent mechanism used for on-the-fly instrumentation became available
104 with in Java 1.5 VMs. Coding and testing with Java 1.5 language level is more
105 efficient, less error-prone &ndash; and more fun. JaCoCo will still allow to
106 run against Java code compiled with older compiler.
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]107</p>
108
109
110<h2>Byte Code Manipulation</h2>
111
112<p class="Note">
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame^]113 Instrumentation requires mechanisms to modify and generate Java byte code.
114 JaCoCo uses the ASM library for this purpose.
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]115</p>
116
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame^]117<p>
118 Implementing the Java byte code specification would be a extensive and
119 error-prone task. Therefore an existing library should be used. The
120 <a href="http://asm.objectweb.org/">ASM</a> library is lightweight, easy to
121 use and very efficient in terms of memory and CPU usage. It is actively
122 maintained and includes as huge regression test suite. Its simplified BSD
123 license is approved by the Eclipse Foundation for usage with EPL products.
124</p>
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]125
126<h2>Java Class Identity</h2>
127
128<p class="Note">
129 Each class loaded at runtime needs a unique identity to associate coverage data with.
130 JaCoCo creates such identities by a CRC64 hash code of the raw class definition.
131</p>
132
133<p>
134 In multi-classloader environments the plain name of a class does not
135 unambiguously identify a class. For example OSGi allows to use different
136 versions of the same class to be loaded within the same VM. In complex
137 deployment scenarios the actual version of the test target might be different
138 from current development version. A code coverage report should guarantee that
139 the presented figures have are extracted from a valid test target. A hash code
140 of the class definitions allows a differentiate between classes and versions
141 of a class. The CRC64 hash computation is simple and fast resulting in a small
142 64 bit identifier.
143</p>
144
145<p>
146 The same class definition might be loaded by class loaders which will result
147 in different classes for the Java runtime system. For coverage analysis this
148 distinction should be irrelevant. Class definitions might be altered by other
149 instrumentation based technologies (e.g. AspectJ). In this case the hash code
150 will change and identity gets lost. On the other hand code coverage analysis
151 based on classes that have been somehow altered will produce unexpected
152 results. The CRC64 has code might produce so called <i>collisions</i>, i.e.
153 creating the same hash code for two different classes. Although CRC64 is not
154 cryptographically strong and collision examples can be easily computed, for
155 regular class files the collision probability is very low.
156</p>
157
158<h2>Coverage Runtime Dependency</h2>
159
160<p class="Note">
Marc R. Hoffmanne52a0ef2009-06-16 20:28:45 +0000[diff] [blame^]161 Instrumented code typically gets a dependency to a coverage runtime which is
162 responsible for collecting and storing execution data. JaCoCo uses JRE types
163 and interfaces only in generated instrumentation code.
164</p>
165
166<p>
167 Making a runtime library available to all instrumented classes can be a
168 painful or impossible task in frameworks that use there own class loading
169 mechanisms. Therefore JaCoCO decouples the instrumented classes and the
170 coverage runtime through official JRE API types.
Marc R. Hoffmanna2af15d2009-06-07 21:15:05 +0000[diff] [blame]171</p>
172
173
174<hr/>
175<div style="float:right">@VERSION@</div>
176<div>Copyright &copy; 2009 Mountainminds GmbH &amp; Co. KG, Marc R. Hoffmann</div>
177
178</body>
179</html>