1*7e63c127SSorin Basca<?xml version="1.0" encoding="UTF-8" ?> 2*7e63c127SSorin Basca<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3*7e63c127SSorin Basca<html xmlns="http://www.w3.org/1999/xhtml" lang="en"> 4*7e63c127SSorin Basca<head> 5*7e63c127SSorin Basca <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6*7e63c127SSorin Basca <link rel="stylesheet" href="resources/doc.css" charset="UTF-8" type="text/css" /> 7*7e63c127SSorin Basca <link rel="shortcut icon" href="resources/report.gif" type="image/gif" /> 8*7e63c127SSorin Basca <title>JaCoCo - Java Agent</title> 9*7e63c127SSorin Basca</head> 10*7e63c127SSorin Basca<body> 11*7e63c127SSorin Basca 12*7e63c127SSorin Basca<div class="breadcrumb"> 13*7e63c127SSorin Basca <a href="../index.html" class="el_report">JaCoCo</a> > 14*7e63c127SSorin Basca <a href="index.html" class="el_group">Documentation</a> > 15*7e63c127SSorin Basca <span class="el_source">Java Agent</span> 16*7e63c127SSorin Basca</div> 17*7e63c127SSorin Basca<div id="content"> 18*7e63c127SSorin Basca 19*7e63c127SSorin Basca<h1>Java Agent</h1> 20*7e63c127SSorin Basca 21*7e63c127SSorin Basca<p> 22*7e63c127SSorin Basca JaCoCo uses class file instrumentation to record execution coverage data. 23*7e63c127SSorin Basca Class files are instrumented on-the-fly using a so called Java agent. This 24*7e63c127SSorin Basca mechanism allows in-memory pre-processing of all class files during class 25*7e63c127SSorin Basca loading independent of the application framework. 26*7e63c127SSorin Basca</p> 27*7e63c127SSorin Basca 28*7e63c127SSorin Basca<p class="hint"> 29*7e63c127SSorin Basca If you use the <a href="ant.html">JaCoCo Ant tasks</a> or 30*7e63c127SSorin Basca <a href="maven.html">JaCoCo Maven plug-in</a> you don't have to care about the 31*7e63c127SSorin Basca agent and its options directly. This is transparently handled by the them. 32*7e63c127SSorin Basca</p> 33*7e63c127SSorin Basca 34*7e63c127SSorin Basca<p> 35*7e63c127SSorin Basca The JaCoCo agent collects execution information and dumps it on request or 36*7e63c127SSorin Basca when the JVM exits. There are three different modes for execution data output: 37*7e63c127SSorin Basca</p> 38*7e63c127SSorin Basca 39*7e63c127SSorin Basca<ul> 40*7e63c127SSorin Basca <li>File System: At JVM termination execution data is written to a local 41*7e63c127SSorin Basca file.</li> 42*7e63c127SSorin Basca <li>TCP Socket Server: External tools can connect to the JVM and retrieve 43*7e63c127SSorin Basca execution data over the socket connection. Optional execution data reset 44*7e63c127SSorin Basca and execution data dump on VM exit is possible.</li> 45*7e63c127SSorin Basca <li>TCP Socket Client: At startup the JaCoCo agent connects to a given TCP 46*7e63c127SSorin Basca endpoint. Execution data is written to the socket connection on request. 47*7e63c127SSorin Basca Optional execution data reset and execution data dump on VM exit is 48*7e63c127SSorin Basca possible.</li> 49*7e63c127SSorin Basca</ul> 50*7e63c127SSorin Basca 51*7e63c127SSorin Basca<p> 52*7e63c127SSorin Basca The agent <code>jacocoagent.jar</code> is part of the JaCoCo distribution and 53*7e63c127SSorin Basca includes all required dependencies. A Java agent can be activated with the 54*7e63c127SSorin Basca following JVM option: 55*7e63c127SSorin Basca</p> 56*7e63c127SSorin Basca 57*7e63c127SSorin Basca<pre> 58*7e63c127SSorin Basca -javaagent:<i>[yourpath/]</i>jacocoagent.jar=<i>[option1]</i>=<i>[value1]</i>,<i>[option2]</i>=<i>[value2]</i> 59*7e63c127SSorin Basca</pre> 60*7e63c127SSorin Basca 61*7e63c127SSorin Basca<p> 62*7e63c127SSorin Basca The JaCoCo agent accepts the following options: 63*7e63c127SSorin Basca</p> 64*7e63c127SSorin Basca 65*7e63c127SSorin Basca<table class="coverage"> 66*7e63c127SSorin Basca <thead> 67*7e63c127SSorin Basca <tr> 68*7e63c127SSorin Basca <td>Option</td> 69*7e63c127SSorin Basca <td>Description</td> 70*7e63c127SSorin Basca <td>Default</td> 71*7e63c127SSorin Basca </tr> 72*7e63c127SSorin Basca </thead> 73*7e63c127SSorin Basca <tbody> 74*7e63c127SSorin Basca <tr> 75*7e63c127SSorin Basca <td><code>destfile</code></td> 76*7e63c127SSorin Basca <td>Path to the output file for execution data.</td> 77*7e63c127SSorin Basca <td><code>jacoco.exec</code></td> 78*7e63c127SSorin Basca </tr> 79*7e63c127SSorin Basca <tr> 80*7e63c127SSorin Basca <td><code>append</code></td> 81*7e63c127SSorin Basca <td>If set to <code>true</code> and the execution data file already 82*7e63c127SSorin Basca exists, coverage data is appended to the existing file. If set to 83*7e63c127SSorin Basca <code>false</code>, an existing execution data file will be replaced. 84*7e63c127SSorin Basca </td> 85*7e63c127SSorin Basca <td><code>true</code></td> 86*7e63c127SSorin Basca </tr> 87*7e63c127SSorin Basca <tr> 88*7e63c127SSorin Basca <td><code>includes</code></td> 89*7e63c127SSorin Basca <td>A list of class names that should be included in execution analysis. 90*7e63c127SSorin Basca The list entries are separated by a colon (<code>:</code>) and 91*7e63c127SSorin Basca may use wildcard characters (<code>*</code> and <code>?</code>). 92*7e63c127SSorin Basca Except for performance optimization or technical corner cases this 93*7e63c127SSorin Basca option is normally not required. 94*7e63c127SSorin Basca </td> 95*7e63c127SSorin Basca <td><code>*</code> (all classes)</td> 96*7e63c127SSorin Basca </tr> 97*7e63c127SSorin Basca <tr> 98*7e63c127SSorin Basca <td><code>excludes</code></td> 99*7e63c127SSorin Basca <td>A list of class names that should be excluded from execution analysis. 100*7e63c127SSorin Basca The list entries are separated by a colon (<code>:</code>) and 101*7e63c127SSorin Basca may use wildcard characters (<code>*</code> and <code>?</code>). 102*7e63c127SSorin Basca Except for performance optimization or technical corner cases this 103*7e63c127SSorin Basca option is normally not required. If you want to exclude classes from 104*7e63c127SSorin Basca the report please configure the respective report generation tool 105*7e63c127SSorin Basca accordingly. 106*7e63c127SSorin Basca </td> 107*7e63c127SSorin Basca <td><i>empty</i> (no excluded classes)</td> 108*7e63c127SSorin Basca </tr> 109*7e63c127SSorin Basca <tr> 110*7e63c127SSorin Basca <td><code>exclclassloader</code></td> 111*7e63c127SSorin Basca <td>A list of class loader names that should be excluded from execution 112*7e63c127SSorin Basca analysis. The list entries are separated by a colon 113*7e63c127SSorin Basca (<code>:</code>) and may use wildcard characters (<code>*</code> and 114*7e63c127SSorin Basca <code>?</code>). This option might be required in case of special 115*7e63c127SSorin Basca frameworks that conflict with JaCoCo code instrumentation, in 116*7e63c127SSorin Basca particular class loaders that do not have access to the Java runtime 117*7e63c127SSorin Basca classes. 118*7e63c127SSorin Basca </td> 119*7e63c127SSorin Basca <td><code>sun.reflect.DelegatingClassLoader</code></td> 120*7e63c127SSorin Basca </tr> 121*7e63c127SSorin Basca <tr> 122*7e63c127SSorin Basca <td><code>inclbootstrapclasses</code></td> 123*7e63c127SSorin Basca <td>Specifies whether also classes from the bootstrap classloader should 124*7e63c127SSorin Basca be instrumented. Use this feature with caution, it needs heavy 125*7e63c127SSorin Basca includes/excludes tuning. 126*7e63c127SSorin Basca </td> 127*7e63c127SSorin Basca <td><code>false</code></td> 128*7e63c127SSorin Basca </tr> 129*7e63c127SSorin Basca <tr> 130*7e63c127SSorin Basca <td><code>inclnolocationclasses</code></td> 131*7e63c127SSorin Basca <td>Specifies whether also classes without a source location should be 132*7e63c127SSorin Basca instrumented. Normally such classes are generated at runtime e.g. by 133*7e63c127SSorin Basca mocking frameworks and are therefore excluded by default. 134*7e63c127SSorin Basca </td> 135*7e63c127SSorin Basca <td><code>false</code></td> 136*7e63c127SSorin Basca </tr> 137*7e63c127SSorin Basca <tr> 138*7e63c127SSorin Basca <td><code>sessionid</code></td> 139*7e63c127SSorin Basca <td>A session identifier that is written with the execution data. Without 140*7e63c127SSorin Basca this parameter a random identifier is created by the agent. 141*7e63c127SSorin Basca </td> 142*7e63c127SSorin Basca <td><i>auto-generated</i></td> 143*7e63c127SSorin Basca </tr> 144*7e63c127SSorin Basca <tr> 145*7e63c127SSorin Basca <td><code>dumponexit</code></td> 146*7e63c127SSorin Basca <td>If set to <code>true</code> coverage data will be written on VM 147*7e63c127SSorin Basca shutdown. The dump can only be written if either <code>file</code> is 148*7e63c127SSorin Basca specified or the output is <code>tcpserver</code>/<code>tcpclient</code> 149*7e63c127SSorin Basca and a connection is open at the time when the VM terminates. 150*7e63c127SSorin Basca </td> 151*7e63c127SSorin Basca <td><code>true</code></td> 152*7e63c127SSorin Basca </tr> 153*7e63c127SSorin Basca <tr> 154*7e63c127SSorin Basca <td><code>output</code></td> 155*7e63c127SSorin Basca <td>Output method to use for writing coverage data. Valid options are: 156*7e63c127SSorin Basca <ul> 157*7e63c127SSorin Basca <li><code>file</code>: At VM termination execution data is written to 158*7e63c127SSorin Basca the file specified in the <code>destfile</code> attribute.</li> 159*7e63c127SSorin Basca <li><code>tcpserver</code>: The agent listens for incoming connections 160*7e63c127SSorin Basca on the TCP port specified by the <code>address</code> and 161*7e63c127SSorin Basca <code>port</code> attribute. Execution data is written to this 162*7e63c127SSorin Basca TCP connection.</li> 163*7e63c127SSorin Basca <li><code>tcpclient</code>: At startup the agent connects to the TCP 164*7e63c127SSorin Basca port specified by the <code>address</code> and <code>port</code> 165*7e63c127SSorin Basca attribute. Execution data is written to this TCP connection.</li> 166*7e63c127SSorin Basca <li><code>none</code>: Do not produce any output.</li> 167*7e63c127SSorin Basca </ul> 168*7e63c127SSorin Basca Please see the security considerations below. 169*7e63c127SSorin Basca </td> 170*7e63c127SSorin Basca <td><code>file</code></td> 171*7e63c127SSorin Basca </tr> 172*7e63c127SSorin Basca <tr> 173*7e63c127SSorin Basca <td><code>address</code></td> 174*7e63c127SSorin Basca <td>IP address or hostname to bind to when the output method is 175*7e63c127SSorin Basca <code>tcpserver</code> or connect to when the output method is 176*7e63c127SSorin Basca <code>tcpclient</code>. In <code>tcpserver</code> mode the value 177*7e63c127SSorin Basca "<code>*</code>" causes the agent to accept connections on any local 178*7e63c127SSorin Basca address. 179*7e63c127SSorin Basca </td> 180*7e63c127SSorin Basca <td><i>loopback interface</i></td> 181*7e63c127SSorin Basca </tr> 182*7e63c127SSorin Basca <tr> 183*7e63c127SSorin Basca <td><code>port</code></td> 184*7e63c127SSorin Basca <td>Port to bind to when the output method is <code>tcpserver</code> or 185*7e63c127SSorin Basca connect to when the output method is <code>tcpclient</code>. In 186*7e63c127SSorin Basca <code>tcpserver</code> mode the port must be available, which means 187*7e63c127SSorin Basca that if multiple JaCoCo agents should run on the same machine, 188*7e63c127SSorin Basca different ports have to be specified. 189*7e63c127SSorin Basca </td> 190*7e63c127SSorin Basca <td><code>6300</code></td> 191*7e63c127SSorin Basca </tr> 192*7e63c127SSorin Basca <tr> 193*7e63c127SSorin Basca <td><code>classdumpdir</code></td> 194*7e63c127SSorin Basca <td>Location relative to the working directory where all class files seen 195*7e63c127SSorin Basca by the agent are dumped to. This can be useful for debugging purposes 196*7e63c127SSorin Basca or in case of dynamically created classes for example when scripting 197*7e63c127SSorin Basca engines are used. 198*7e63c127SSorin Basca </td> 199*7e63c127SSorin Basca <td><i>no dumps</i></td> 200*7e63c127SSorin Basca </tr> 201*7e63c127SSorin Basca <tr> 202*7e63c127SSorin Basca <td><code>jmx</code></td> 203*7e63c127SSorin Basca <td>If set to <code>true</code> the agent exposes 204*7e63c127SSorin Basca <a href="./api/org/jacoco/agent/rt/IAgent.html">functionality</a> via 205*7e63c127SSorin Basca JMX under the name <code>org.jacoco:type=Runtime</code>. Please see 206*7e63c127SSorin Basca the security considerations below. 207*7e63c127SSorin Basca </td> 208*7e63c127SSorin Basca <td><code>false</code></td> 209*7e63c127SSorin Basca </tr> 210*7e63c127SSorin Basca </tbody> 211*7e63c127SSorin Basca</table> 212*7e63c127SSorin Basca 213*7e63c127SSorin Basca<h2>Security Consideration for Remote Agent Control</h2> 214*7e63c127SSorin Basca 215*7e63c127SSorin Basca<p> 216*7e63c127SSorin Basca The ports and connections opened in <code>tcpserver</code> and 217*7e63c127SSorin Basca <code>tcpclient</code> mode and the JMX interface do not provide any 218*7e63c127SSorin Basca authentication mechanism. If you run JaCoCo on production systems make sure 219*7e63c127SSorin Basca that no untrusted sources have access to the TCP server port, or JaCoCo TCP 220*7e63c127SSorin Basca clients only connect to trusted targets. Otherwise internal information of the 221*7e63c127SSorin Basca application might be revealed or DOS attacks are possible. 222*7e63c127SSorin Basca</p> 223*7e63c127SSorin Basca 224*7e63c127SSorin Basca</div> 225*7e63c127SSorin Basca<div class="footer"> 226*7e63c127SSorin Basca <span class="right"><a href="${jacoco.home.url}">JaCoCo</a> ${qualified.bundle.version}</span> 227*7e63c127SSorin Basca <a href="license.html">Copyright</a> © ${copyright.years} Mountainminds GmbH & Co. KG and Contributors 228*7e63c127SSorin Basca</div> 229*7e63c127SSorin Basca 230*7e63c127SSorin Basca</body> 231*7e63c127SSorin Basca</html> 232
