0
# AspectJ Weaver
1
2
The AspectJ Weaver applies aspects to Java classes and supports load-time weaving (LTW) during class loading. It provides both Java agent capabilities for transparent weaving and programmatic APIs for embedding weaving into applications. The weaver includes a comprehensive caching system for improved performance and supports multi-classloader and OSGi environments.
3
4
## Package Information
5
6
- **Package Name**: org.aspectj:aspectjweaver
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**:
10
```xml
11
<dependency>
12
<groupId>org.aspectj</groupId>
13
<artifactId>aspectjweaver</artifactId>
14
<version>1.9.24</version>
15
</dependency>
16
```
17
18
## Core Imports
19
20
```java
21
import org.aspectj.weaver.loadtime.Agent;
22
import org.aspectj.weaver.loadtime.Aj;
23
import org.aspectj.weaver.tools.WeavingAdaptor;
24
import org.aspectj.weaver.tools.cache.WeavedClassCache;
25
```
26
27
## Basic Usage
28
29
### Java Agent Usage
30
31
Run your application with the AspectJ weaver as a Java agent:
32
33
```bash
34
java -javaagent:aspectjweaver.jar MyApplication
35
```
36
37
The agent automatically initializes and applies load-time weaving to classes as they are loaded.
38
39
### Programmatic Usage
40
41
```java
42
import org.aspectj.weaver.tools.WeavingAdaptor;
43
import java.net.URL;
44
45
// Create weaving adaptor
46
WeavingAdaptor adaptor = new WeavingAdaptor(classLoader);
47
48
// Weave a class
49
byte[] originalBytes = getClassBytes(className);
50
byte[] wovenBytes = adaptor.weaveClass(className, originalBytes);
51
52
// Use the woven bytes
53
defineClass(className, wovenBytes);
54
```
55
56
## Architecture
57
58
The AspectJ Weaver is organized into several key components:
59
60
- **Agent System**: Java agent entry point for transparent load-time weaving
61
- **Core Weaving**: Programmatic weaving APIs and class transformation
62
- **Caching System**: Performance optimization through class caching
63
- **Context Management**: Multi-classloader and OSGi environment support
64
65
## Capabilities
66
67
### Java Agent Integration
68
69
Entry point for using AspectJ weaver as a Java agent with `-javaagent` parameter.
70
71
```java { .api }
72
public static void premain(String options, Instrumentation instrumentation);
73
public static void agentmain(String options, Instrumentation instrumentation);
74
public static Instrumentation getInstrumentation();
75
```
76
77
[Java Agent Integration](./java-agent.md)
78
79
### Programmatic Weaving
80
81
Core APIs for embedding AspectJ weaving capabilities into applications.
82
83
```java { .api }
84
public WeavingAdaptor(WeavingClassLoader loader);
85
public byte[] weaveClass(String name, byte[] bytes) throws IOException;
86
public byte[] weaveClass(String name, byte[] bytes, boolean mustWeave) throws IOException;
87
```
88
89
[Programmatic Weaving](./programmatic-weaving.md)
90
91
### Class Caching
92
93
High-performance caching system for weaved and generated classes across JVM restarts.
94
95
```java { .api }
96
public static WeavedClassCache createCache(ClassLoader loader, List<String> aspects,
97
GeneratedClassHandler handler, IMessageHandler messageHandler);
98
public void put(CachedClassReference ref, byte[] classBytes, byte[] weavedBytes);
99
public CachedClassEntry get(CachedClassReference ref, byte[] classBytes);
100
```
101
102
[Class Caching](./caching.md)
103
104
### Multi-Classloader Support
105
106
Support for complex classloader hierarchies, OSGi environments, and multi-module applications.
107
108
```java { .api }
109
public interface IWeavingContext {
110
Enumeration<URL> getResources(String name) throws IOException;
111
String getClassLoaderName();
112
boolean isLocallyDefined(String classname);
113
}
114
```
115
116
[Multi-Classloader Support](./multi-classloader.md)
117
118
## Types
119
120
### Core Interfaces
121
122
```java { .api }
123
public interface ClassPreProcessor {
124
void initialize();
125
byte[] preProcess(String className, byte[] bytes, ClassLoader classLoader,
126
ProtectionDomain protectionDomain);
127
void prepareForRedefinition(ClassLoader loader, String className);
128
}
129
130
public interface IClassFileProvider {
131
Iterator<UnwovenClassFile> getClassFileIterator();
132
IWeaveRequestor getRequestor();
133
boolean isApplyAtAspectJMungersOnly();
134
}
135
```
136
137
### Cache Types
138
139
```java { .api }
140
public interface CacheFactory {
141
CacheKeyResolver createResolver();
142
CacheBacking createBacking(String scope);
143
}
144
145
public interface CacheKeyResolver {
146
CachedClassReference generatedKey(String className);
147
CachedClassReference weavedKey(String className, byte[] original_bytes);
148
String keyToClass(String key);
149
}
150
151
public interface CacheBacking {
152
String[] getKeys(String regex);
153
void remove(CachedClassReference ref);
154
CachedClassEntry get(CachedClassReference ref, byte[] originalBytes);
155
void put(CachedClassEntry entry, byte[] originalBytes);
156
}
157
```
158
159
### Message Handling Types
160
161
```java { .api }
162
public interface IMessageHandler {
163
boolean handleMessage(IMessage message) throws AbortException;
164
boolean isIgnoring(IMessage.Kind kind);
165
void dontIgnore(IMessage.Kind kind);
166
void ignore(IMessage.Kind kind);
167
}
168
169
public class AbortException extends RuntimeException {
170
// Exception thrown to abort weaving operations
171
}
172
173
public interface IMessageHolder {
174
boolean hasAnyMessage(IMessage.Kind kind, boolean orGreater);
175
int numMessages(IMessage.Kind kind, boolean orGreater);
176
IMessage[] getMessages(IMessage.Kind kind, boolean orGreater);
177
}
178
179
public interface IMessage {
180
enum Kind { ABORT, ERROR, WARNING, INFO, DEBUG, TASKTAG, USAGE, WEAVEINFO }
181
Kind getKind();
182
String getMessage();
183
ISourceLocation getSourceLocation();
184
Throwable getThrown();
185
}
186
187
public interface ISourceLocation {
188
java.io.File getSourceFile();
189
int getLine();
190
int getColumn();
191
String getContext();
192
}
193
```
194
195
### Data Types
196
197
```java { .api }
198
public class CachedClassReference {
199
// Reference to a cached class with key information
200
}
201
202
public class CachedClassEntry {
203
// Represents a cached class entry with type information
204
}
205
206
public class CacheStatistics {
207
// Statistics tracking for cache operations
208
}
209
210
public interface GeneratedClassHandler {
211
void acceptClass(String name, byte[] originalBytes, byte[] wovenBytes);
212
}
213
214
public class Definition {
215
// Represents weaving definition configuration from aop.xml files
216
}
217
```
218
219
## Error Handling
220
221
The AspectJ Weaver throws several types of exceptions:
222
223
- **`IllegalClassFormatException`**: When class transformation fails
224
- **`IOException`**: During file operations and weaving
225
- **`UnsupportedOperationException`**: When agent is not properly initialized
226
- **`ExceptionInInitializerError`**: During ClassPreProcessorAgentAdapter initialization
227
228
Example error handling:
229
230
```java
231
try {
232
byte[] wovenBytes = adaptor.weaveClass(className, originalBytes);
233
} catch (IOException e) {
234
// Handle weaving failure
235
System.err.println("Failed to weave class " + className + ": " + e.getMessage());
236
}
237
```