0
# Transformation Utilities
1

2
Bytecode transformation utilities for modifying classes at load time or generating transformed versions of existing classes. These utilities provide the foundation for advanced class manipulation and dynamic behavior modification.
3

4
## Core Imports
5

6
```java
7
import net.sf.cglib.transform.TransformingClassLoader;
8
import net.sf.cglib.transform.ClassTransformer;
9
import net.sf.cglib.transform.ClassFilter;
10
import net.sf.cglib.transform.ClassTransformerFactory;
11
import net.sf.cglib.transform.MethodFilter;
12
```
13

14
## Capabilities
15

16
### TransformingClassLoader
17

18
Class loader that applies transformations to classes as they are loaded.
19

20
```java { .api }
21
/**
22
 * Class loader that applies transformations to classes as they are loaded
23
 */
24
public class TransformingClassLoader extends AbstractClassLoader {
25
    /**
26
     * Create transforming class loader
27
     * @param parent Parent class loader
28
     * @param filter Filter for classes to transform
29
     * @param t Factory for creating transformers
30
     */
31
    public TransformingClassLoader(ClassLoader parent, ClassFilter filter, ClassTransformerFactory t);
32
}
33
```
34

35
**Usage Examples:**
36

37
```java
38
// Create filter for classes to transform
39
ClassFilter filter = new ClassFilter() {
40
    public boolean accept(String className) {
41
        return className.startsWith("com.mycompany.");
42
    }
43
};
44

45
// Create transformer factory
46
ClassTransformerFactory factory = new ClassTransformerFactory() {
47
    public ClassTransformer newInstance() {
48
        return new MyCustomTransformer();
49
    }
50
};
51

52
// Create transforming class loader
53
TransformingClassLoader loader = new TransformingClassLoader(
54
    Thread.currentThread().getContextClassLoader(),
55
    filter,
56
    factory
57
);
58

59
// Load and use transformed classes
60
Class<?> transformedClass = loader.loadClass("com.mycompany.MyClass");
61
Object instance = transformedClass.newInstance();
62
```
63

64
### ClassTransformer
65

66
Abstract base class for implementing class transformations.
67

68
```java { .api }
69
/**
70
 * Abstract base class for class transformations
71
 */
72
public abstract class ClassTransformer extends ClassVisitor {
73
    /**
74
     * Default constructor
75
     */
76
    public ClassTransformer();
77
    
78
    /**
79
     * Constructor with ASM API version
80
     * @param opcode ASM API version
81
     */
82
    public ClassTransformer(int opcode);
83
    
84
    /**
85
     * Set the target visitor for the transformation chain
86
     * @param target Target class visitor
87
     */
88
    public abstract void setTarget(ClassVisitor target);
89
}
90
```
91

92
### ClassFilter
93

94
Interface for filtering classes during transformation.
95

96
```java { .api }
97
/**
98
 * Interface for filtering classes during transformation
99
 */
100
public interface ClassFilter {
101
    /**
102
     * Determine if a class should be processed
103
     * @param className Fully qualified class name
104
     * @return true if class should be processed
105
     */
106
    boolean accept(String className);
107
}
108
```
109

110
**Usage Examples:**
111

112
```java
113
// Filter by package prefix
114
ClassFilter packageFilter = new ClassFilter() {
115
    public boolean accept(String className) {
116
        return className.startsWith("com.myapp.");
117
    }
118
};
119

120
// Filter by class name pattern
121
ClassFilter patternFilter = new ClassFilter() {
122
    public boolean accept(String className) {
123
        return className.endsWith("Service") || className.endsWith("Repository");
124
    }
125
};
126

127
// Combine filters
128
ClassFilter combinedFilter = new ClassFilter() {
129
    public boolean accept(String className) {
130
        return packageFilter.accept(className) && patternFilter.accept(className);
131
    }
132
};
133
```
134

135
### ClassTransformerFactory
136

137
Factory interface for creating class transformers.
138

139
```java { .api }
140
/**
141
 * Factory for creating class transformers
142
 */
143
public interface ClassTransformerFactory {
144
    /**
145
     * Create new transformer instance
146
     * @return New ClassTransformer instance
147
     */
148
    ClassTransformer newInstance();
149
}
150
```
151

152
### MethodFilter
153

154
Interface for filtering methods during transformation.
155

156
```java { .api }
157
/**
158
 * Interface for filtering methods during transformation
159
 */
160
public interface MethodFilter {
161
    /**
162
     * Determine if a method should be processed
163
     * @param access Method access flags
164
     * @param name Method name
165
     * @param desc Method descriptor
166
     * @param signature Method signature (may be null)
167
     * @param exceptions Exception types thrown (may be null)
168
     * @return true if method should be processed
169
     */
170
    boolean accept(int access, String name, String desc, String signature, String[] exceptions);
171
}
172
```
173

174
**Usage Examples:**
175

176
```java
177
// Filter public methods only
178
MethodFilter publicMethodFilter = new MethodFilter() {
179
    public boolean accept(int access, String name, String desc, String signature, String[] exceptions) {
180
        return (access & Opcodes.ACC_PUBLIC) != 0;
181
    }
182
};
183

184
// Filter by method name
185
MethodFilter nameFilter = new MethodFilter() {
186
    public boolean accept(int access, String name, String desc, String signature, String[] exceptions) {
187
        return name.startsWith("get") || name.startsWith("set");
188
    }
189
};
190

191
// Filter by return type
192
MethodFilter returnTypeFilter = new MethodFilter() {
193
    public boolean accept(int access, String name, String desc, String signature, String[] exceptions) {
194
        return desc.endsWith(")V"); // void return type
195
    }
196
};
197
```
198

199
### ClassTransformerChain
200

201
Chains multiple class transformers together.
202

203
```java { .api }
204
/**
205
 * Chains multiple class transformers together
206
 */
207
public class ClassTransformerChain extends AbstractClassTransformer {
208
    /**
209
     * Create transformation chain
210
     * @param transformers Array of transformers to chain
211
     */
212
    public ClassTransformerChain(ClassTransformer[] transformers);
213
}
214
```
215

216
### MethodFilterTransformer
217

218
Applies method filtering during class transformation.
219

220
```java { .api }
221
/**
222
 * Applies method filtering during class transformation
223
 */
224
public class MethodFilterTransformer extends AbstractClassTransformer {
225
    /**
226
     * Create method filter transformer
227
     * @param filter Method filter to apply
228
     * @param transformer Transformer for filtered methods
229
     */
230
    public MethodFilterTransformer(MethodFilter filter, MethodTransformer transformer);
231
}
232
```
233

234
### ClassVisitorTee
235

236
Duplicates class visitor calls to multiple targets.
237

238
```java { .api }
239
/**
240
 * Duplicates class visitor calls to multiple targets
241
 */
242
public class ClassVisitorTee extends ClassVisitor {
243
    /**
244
     * Create visitor tee
245
     * @param cv1 First class visitor
246
     * @param cv2 Second class visitor
247
     */
248
    public ClassVisitorTee(ClassVisitor cv1, ClassVisitor cv2);
249
}
250
```
251

252
### MethodVisitorTee
253

254
Duplicates method visitor calls to multiple targets.
255

256
```java { .api }
257
/**
258
 * Duplicates method visitor calls to multiple targets
259
 */
260
public class MethodVisitorTee extends MethodVisitor {
261
    /**
262
     * Create method visitor tee
263
     * @param mv1 First method visitor
264
     * @param mv2 Second method visitor
265
     */
266
    public MethodVisitorTee(MethodVisitor mv1, MethodVisitor mv2);
267
}
268
```
269

270
### FieldVisitorTee
271

272
Duplicates field visitor calls to multiple targets.
273

274
```java { .api }
275
/**
276
 * Duplicates field visitor calls to multiple targets
277
 */
278
public class FieldVisitorTee extends FieldVisitor {
279
    /**
280
     * Create field visitor tee
281
     * @param fv1 First field visitor
282
     * @param fv2 Second field visitor
283
     */
284
    public FieldVisitorTee(FieldVisitor fv1, FieldVisitor fv2);
285
}
286
```
287

288
## Usage Patterns
289

290
### Basic Class Transformation
291

292
```java
293
// Create custom transformer
294
public class LoggingTransformer extends ClassTransformer {
295
    public void setTarget(ClassVisitor target) {
296
        // Implementation here
297
    }
298
    
299
    @Override
300
    public MethodVisitor visitMethod(int access, String name, String desc, 
301
                                   String signature, String[] exceptions) {
302
        MethodVisitor mv = super.visitMethod(access, name, desc, signature, exceptions);
303
        return new LoggingMethodVisitor(mv, name);
304
    }
305
}
306

307
// Use with transforming class loader
308
ClassFilter filter = className -> className.startsWith("com.example.");
309
ClassTransformerFactory factory = () -> new LoggingTransformer();
310
TransformingClassLoader loader = new TransformingClassLoader(
311
    getClass().getClassLoader(), filter, factory);
312
```
313

314
### Method Filtering and Transformation
315

316
```java
317
// Filter methods for transformation
318
MethodFilter filter = (access, name, desc, signature, exceptions) -> {
319
    return (access & Opcodes.ACC_PUBLIC) != 0 && !name.equals("<init>");
320
};
321

322
// Apply transformation to filtered methods
323
MethodFilterTransformer transformer = new MethodFilterTransformer(
324
    filter, 
325
    new TimingMethodTransformer()
326
);
327
```