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
```