0
# JaCoCo Agent
1

2
JaCoCo Agent provides programmatic access to the JaCoCo runtime agent JAR file for Java code coverage analysis. This module serves as a wrapper and resource provider for the jacocoagent.jar file, offering APIs to extract, access, and deploy the coverage agent in various Java environments.
3

4
## Package Information
5

6
- **Package Name**: org.jacoco.agent
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.jacoco</groupId>
13
    <artifactId>org.jacoco.agent</artifactId>
14
    <version>0.8.13</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.jacoco.agent.AgentJar;
22
import java.io.File;
23
import java.io.InputStream;
24
import java.io.IOException;
25
import java.net.URL;
26
```
27

28
## Basic Usage
29

30
```java
31
import org.jacoco.agent.AgentJar;
32
import java.io.File;
33
import java.io.IOException;
34

35
// Get the agent JAR as a URL
36
URL agentUrl = AgentJar.getResource();
37

38
// Get the agent JAR as an InputStream
39
InputStream agentStream = AgentJar.getResourceAsStream();
40

41
// Extract agent to a temporary location
42
File tempAgent = AgentJar.extractToTempLocation();
43

44
// Extract agent to a specific location
45
File specificLocation = new File("/path/to/jacocoagent.jar");
46
AgentJar.extractTo(specificLocation);
47
```
48

49
## Capabilities
50

51
### Agent Resource Access
52

53
Access the embedded JaCoCo agent JAR file as a resource.
54

55
```java { .api }
56
/**
57
 * Returns a URL pointing to the JAR file.
58
 * @return URL of the JAR file
59
 */
60
public static URL getResource();
61

62
/**
63
 * Returns the content of the JAR file as a stream.
64
 * @return content of the JAR file
65
 */
66
public static InputStream getResourceAsStream();
67
```
68

69
**Usage Examples:**
70

71
```java
72
// Access via URL
73
URL agentUrl = AgentJar.getResource();
74
InputStream stream = agentUrl.openStream();
75

76
// Direct stream access with proper resource management
77
try (InputStream agentStream = AgentJar.getResourceAsStream()) {
78
    // Use the stream for processing
79
    // Stream is automatically closed when try block exits
80
}
81
```
82

83
### Agent Extraction
84

85
Extract the embedded agent JAR to file system locations.
86

87
```java { .api }
88
/**
89
 * Extract the JaCoCo agent JAR and put it into a temporary location. This
90
 * file should be deleted on exit, but may not if the VM is terminated
91
 * @return Location of the Agent Jar file in the local file system. The file
92
 *         should exist and be readable.
93
 * @throws IOException Unable to unpack agent jar
94
 */
95
public static File extractToTempLocation() throws IOException;
96

97
/**
98
 * Extract the JaCoCo agent JAR and put it into the specified location.
99
 * @param destination Location to write JaCoCo Agent Jar to. Must be writeable
100
 * @throws IOException Unable to unpack agent jar
101
 */
102
public static void extractTo(File destination) throws IOException;
103
```
104

105
**Usage Examples:**
106

107
```java
108
// Extract to temporary location (automatically deleted on JVM exit)
109
File tempAgentFile = AgentJar.extractToTempLocation();
110
System.out.println("Agent extracted to: " + tempAgentFile.getAbsolutePath());
111

112
// Extract to specific location
113
File agentFile = new File("./jacocoagent.jar");
114
try {
115
    AgentJar.extractTo(agentFile);
116
    System.out.println("Agent extracted to: " + agentFile.getAbsolutePath());
117
} catch (IOException e) {
118
    System.err.println("Failed to extract agent: " + e.getMessage());
119
}
120
```
121

122
## Types
123

124
```java { .api }
125
public final class AgentJar {
126
    // Private constructor - cannot be instantiated
127
    private AgentJar();
128
    
129
    // All methods are static
130
}
131
```
132

133
## Error Handling
134

135
The JaCoCo Agent API uses two main types of exceptions:
136

137
- **AssertionError**: Thrown when the embedded `/jacocoagent.jar` resource is not found. This typically indicates a build or packaging issue. The error includes a reference to `/org.jacoco.agent/README.TXT` for troubleshooting details.
138
- **IOException**: Thrown by extraction methods for I/O related failures, such as:
139
  - Destination file is not writable
140
  - Destination path does not exist
141
  - Insufficient disk space
142
  - File system permissions issues
143

144
**Error Handling Example:**
145

146
```java
147
try {
148
    // Resource access - may throw AssertionError
149
    URL agentUrl = AgentJar.getResource();
150
    
151
    // File extraction - may throw IOException  
152
    File agentFile = new File("./jacocoagent.jar");
153
    AgentJar.extractTo(agentFile);
154
    
155
} catch (AssertionError e) {
156
    System.err.println("Agent resource not found. Check build configuration.");
157
} catch (IOException e) {
158
    System.err.println("Failed to extract agent: " + e.getMessage());
159
}
160
```
161

162
## Key Characteristics
163

164
- **Utility Class**: AgentJar is a final class with only static methods and private constructor (cannot be instantiated)
165
- **Resource Provider**: Acts as a wrapper around the embedded `/jacocoagent.jar` resource within the JAR file
166
- **Thread Safety**: All methods are static and thread-safe
167
- **Self-Contained**: Includes the complete agent JAR as an embedded resource at runtime
168
- **Build Integration**: The agent JAR is created and embedded during the Maven build process
169
- **No External Dependencies**: Pure Java implementation using only standard library classes
170
- **Safe Resource Handling**: Internal implementation uses safe stream closing to prevent resource leaks
171

172
## Integration Patterns
173

174
Common usage patterns for integrating JaCoCo Agent in applications:
175

176
**Testing Framework Integration:**
177
```java
178
// Extract agent for use with JVM arguments
179
File agent = AgentJar.extractToTempLocation();
180
String javaagentArg = "-javaagent:" + agent.getAbsolutePath();
181
// Use javaagentArg when launching test JVMs
182
```
183

184
**Build Tool Integration:**
185
```java
186
// Extract to build directory for distribution
187
File buildDir = new File("target/jacoco");
188
buildDir.mkdirs();
189
File agentJar = new File(buildDir, "jacocoagent.jar");
190
AgentJar.extractTo(agentJar);
191
```
192

193
**Runtime Deployment:**
194
```java
195
// Use the built-in extraction method for deployment
196
File deploymentFile = new File("/path/to/deployment/jacocoagent.jar");
197
AgentJar.extractTo(deploymentFile);
198
// The extractTo method handles stream management and proper copying
199
```