0
# Java Agent Integration
1
2
The AspectJ Weaver provides Java agent capabilities for transparent load-time weaving using the standard Java instrumentation API. This allows aspects to be applied to classes as they are loaded by the JVM without requiring code changes.
3
4
## Core Agent Class
5
6
### Agent
7
8
Main entry point for Java agent functionality.
9
10
```java { .api }
11
public class Agent {
12
public static void premain(String options, Instrumentation instrumentation);
13
public static void agentmain(String options, Instrumentation instrumentation);
14
public static Instrumentation getInstrumentation();
15
}
16
```
17
18
#### premain
19
20
JSR-163 preMain agent entry method called when using `-javaagent` parameter.
21
22
```java { .api }
23
public static void premain(String options, Instrumentation instrumentation)
24
```
25
26
**Parameters:**
27
- `options` - Agent options string (can be null)
28
- `instrumentation` - JVM instrumentation instance
29
30
**Usage:**
31
```bash
32
java -javaagent:aspectjweaver.jar MyApplication
33
java -javaagent:aspectjweaver.jar=options MyApplication
34
```
35
36
#### agentmain
37
38
Agent attachment entry method for dynamic agent loading via VirtualMachine.loadAgent.
39
40
```java { .api }
41
public static void agentmain(String options, Instrumentation instrumentation)
42
```
43
44
**Parameters:**
45
- `options` - Agent options string (can be null)
46
- `instrumentation` - JVM instrumentation instance
47
48
#### getInstrumentation
49
50
Returns the system-level Instrumentation instance.
51
52
```java { .api }
53
public static Instrumentation getInstrumentation()
54
```
55
56
**Returns:** The Instrumentation instance provided by the JVM
57
58
**Throws:** `UnsupportedOperationException` if the agent was not started via `-javaagent` or attached via `VirtualMachine.loadAgent`
59
60
## Class File Transformation
61
62
### ClassPreProcessorAgentAdapter
63
64
Adapter implementing ClassFileTransformer for Java agent integration.
65
66
```java { .api }
67
public class ClassPreProcessorAgentAdapter implements ClassFileTransformer {
68
public byte[] transform(ClassLoader loader, String className, Class<?> classBeingRedefined,
69
ProtectionDomain protectionDomain, byte[] bytes) throws IllegalClassFormatException;
70
}
71
```
72
73
#### transform
74
75
Transforms class bytes using the AspectJ weaver.
76
77
```java { .api }
78
public byte[] transform(ClassLoader loader, String className, Class<?> classBeingRedefined,
79
ProtectionDomain protectionDomain, byte[] bytes) throws IllegalClassFormatException
80
```
81
82
**Parameters:**
83
- `loader` - The defining class loader
84
- `className` - Name of class being loaded (in internal form, e.g., "com/example/MyClass")
85
- `classBeingRedefined` - Set when hotswap is being attempted
86
- `protectionDomain` - Protection domain for the class being loaded
87
- `bytes` - Original class bytes before weaving
88
89
**Returns:** Woven class bytes or null if no transformation applied
90
91
**throws:** `IllegalClassFormatException` if class format is invalid
92
93
## Usage Examples
94
95
### Basic Agent Usage
96
97
```bash
98
# Basic load-time weaving
99
java -javaagent:aspectjweaver.jar com.example.MyApp
100
101
# With custom options
102
java -javaagent:aspectjweaver.jar=verbose com.example.MyApp
103
```
104
105
### Programmatic Agent Check
106
107
```java
108
import org.aspectj.weaver.loadtime.Agent;
109
import java.lang.instrument.Instrumentation;
110
111
public class MyApplication {
112
public static void main(String[] args) {
113
try {
114
Instrumentation inst = Agent.getInstrumentation();
115
System.out.println("AspectJ agent is active");
116
System.out.println("Can redefine classes: " + inst.isRedefineClassesSupported());
117
} catch (UnsupportedOperationException e) {
118
System.out.println("AspectJ agent not active: " + e.getMessage());
119
}
120
}
121
}
122
```
123
124
### Dynamic Agent Attachment
125
126
```java
127
import com.sun.tools.attach.VirtualMachine;
128
import java.lang.management.ManagementFactory;
129
130
public class AgentAttacher {
131
public static void attachAgent() throws Exception {
132
String pid = ManagementFactory.getRuntimeMXBean().getName().split("@")[0];
133
VirtualMachine vm = VirtualMachine.attach(pid);
134
vm.loadAgent("/path/to/aspectjweaver.jar");
135
vm.detach();
136
}
137
}
138
```
139
140
## Configuration
141
142
The agent supports various configuration options through system properties and aop.xml files:
143
144
### System Properties
145
146
- **`aj.weaving.verbose`**: Enable verbose weaving output
147
- **`org.aspectj.weaver.showWeaveInfo`**: Show weave information
148
- **`org.aspectj.tracing.messages`**: Enable message tracing
149
150
### AOP Configuration
151
152
Create `META-INF/aop.xml` in your classpath:
153
154
```xml
155
<?xml version="1.0" encoding="UTF-8"?>
156
<aspectj>
157
<weaver options="-verbose -showWeaveInfo">
158
<include within="com.example..*"/>
159
</weaver>
160
<aspects>
161
<aspect name="com.example.MyAspect"/>
162
</aspects>
163
</aspectj>
164
```
165
166
## Troubleshooting
167
168
### Common Issues
169
170
1. **Agent Not Loading**: Ensure the aspectjweaver.jar path is correct
171
2. **No Weaving Occurring**: Check that aspects are on the classpath and properly configured
172
3. **Class Redefinition Errors**: Some classes cannot be redefined after initial loading
173
174
### Debugging
175
176
Enable verbose output to see what the agent is doing:
177
178
```bash
179
java -javaagent:aspectjweaver.jar -Daj.weaving.verbose=true MyApp
180
```
181
182
### Error Handling
183
184
```java
185
public class AgentErrorHandler {
186
public static void checkAgentStatus() {
187
try {
188
Instrumentation inst = Agent.getInstrumentation();
189
if (!inst.isRedefineClassesSupported()) {
190
System.err.println("Warning: Class redefinition not supported");
191
}
192
} catch (UnsupportedOperationException e) {
193
System.err.println("AspectJ agent not initialized: " + e.getMessage());
194
// Handle non-agent execution
195
}
196
}
197
}
198
```