0
# Proxy Generation
1

2
Core proxy and class enhancement functionality for creating dynamic subclasses with method interception. This is the primary feature of CGLib used by most frameworks for AOP, testing, and ORM implementations.
3

4
## Core Imports
5

6
```java
7
import net.sf.cglib.proxy.Enhancer;
8
import net.sf.cglib.proxy.MethodInterceptor;
9
import net.sf.cglib.proxy.MethodProxy;
10
import net.sf.cglib.proxy.Callback;
11
import net.sf.cglib.proxy.CallbackFilter;
12
import net.sf.cglib.proxy.Factory;
13
import net.sf.cglib.proxy.FixedValue;
14
import net.sf.cglib.proxy.NoOp;
15
import net.sf.cglib.proxy.LazyLoader;
16
import net.sf.cglib.proxy.Dispatcher;
17
import net.sf.cglib.proxy.ProxyRefDispatcher;
18
import net.sf.cglib.proxy.InvocationHandler;
19
import net.sf.cglib.proxy.UndeclaredThrowableException;
20
import net.sf.cglib.core.NamingPolicy;
21
import java.lang.reflect.Method;
22
import java.io.Serializable;
23
```
24

25
## Capabilities
26

27
### Enhancer
28

29
Main class for creating enhanced subclasses and proxy objects. The Enhancer generates a new class that extends the target class and allows method interception through callbacks.
30

31
```java { .api }
32
/**
33
 * Main class for creating enhanced subclasses and proxy objects
34
 */
35
public class Enhancer extends AbstractClassGenerator {
36
    /**
37
     * Set the class to be enhanced (superclass of generated class)
38
     * @param superclass - The class to extend
39
     */
40
    public void setSuperclass(Class superclass);
41
    
42
    /**
43
     * Set interfaces to be implemented by generated class
44
     * @param interfaces - Array of interfaces to implement
45
     */
46
    public void setInterfaces(Class[] interfaces);
47
    
48
    /**
49
     * Set single callback for all methods
50
     * @param callback - Callback to handle method calls
51
     */
52
    public void setCallback(Callback callback);
53
    
54
    /**
55
     * Set multiple callbacks for different methods
56
     * @param callbacks - Array of callbacks
57
     */
58
    public void setCallbacks(Callback[] callbacks);
59
    
60
    /**
61
     * Set filter to determine which callback to use for each method
62
     * @param filter - CallbackFilter implementation
63
     */
64
    public void setCallbackFilter(CallbackFilter filter);
65
    
66
    /**
67
     * Create instance using default constructor
68
     * @return Enhanced instance
69
     */
70
    public Object create();
71
    
72
    /**
73
     * Create instance using specific constructor
74
     * @param argumentTypes - Constructor parameter types
75
     * @param arguments - Constructor arguments
76
     * @return Enhanced instance
77
     */
78
    public Object create(Class[] argumentTypes, Object[] arguments);
79
    
80
    /**
81
     * Set naming policy for generated classes
82
     * @param namingPolicy - Strategy for naming generated classes
83
     */
84
    public void setNamingPolicy(NamingPolicy namingPolicy);
85
    
86
    /**
87
     * Set class loader for generated classes
88
     * @param loader - ClassLoader to use
89
     */
90
    public void setClassLoader(ClassLoader loader);
91
}
92
```
93

94
**Usage Examples:**
95

96
```java
97
import net.sf.cglib.proxy.*;
98
import java.lang.reflect.Method;
99

100
// Basic method interception
101
Enhancer enhancer = new Enhancer();
102
enhancer.setSuperclass(UserService.class);
103
enhancer.setCallback(new MethodInterceptor() {
104
    @Override
105
    public Object intercept(Object obj, Method method, Object[] args, 
106
                          MethodProxy proxy) throws Throwable {
107
        System.out.println("Before: " + method.getName());
108
        Object result = proxy.invokeSuper(obj, args);
109
        System.out.println("After: " + method.getName());
110
        return result;
111
    }
112
});
113

114
UserService service = (UserService) enhancer.create();
115

116
// Multiple callbacks with filter
117
enhancer.setCallbacks(new Callback[] {
118
    new MethodInterceptor() { /* logging interceptor */ },
119
    NoOp.INSTANCE  // no interception
120
});
121
enhancer.setCallbackFilter(new CallbackFilter() {
122
    @Override
123
    public int accept(Method method) {
124
        return method.getName().startsWith("get") ? 1 : 0;
125
    }
126
});
127
```
128

129
### MethodInterceptor
130

131
Primary callback interface for intercepting method calls on proxy objects.
132

133
```java { .api }
134
/**
135
 * Callback for intercepting method calls on proxy objects
136
 */
137
public interface MethodInterceptor extends Callback {
138
    /**
139
     * Intercept method calls on proxy objects
140
     * @param obj - Enhanced object instance
141
     * @param method - Method being called
142
     * @param args - Method arguments
143
     * @param proxy - MethodProxy for efficient super calls
144
     * @return Method result
145
     * @throws Throwable - Any exception from method execution
146
     */
147
    Object intercept(Object obj, Method method, Object[] args, MethodProxy proxy) 
148
        throws Throwable;
149
}
150
```
151

152
### Other Callback Types
153

154
Additional callback interfaces for specific proxy behaviors.
155

156
```java { .api }
157
/**
158
 * Callback that returns a fixed value for all method calls
159
 */
160
public interface FixedValue extends Callback {
161
    Object loadObject() throws Exception;
162
}
163

164
/**
165
 * Callback that performs no operation, allowing original method execution
166
 */
167
public interface NoOp extends Callback {
168
    NoOp INSTANCE = new NoOp() {};
169
}
170

171
/**
172
 * Callback for lazy initialization of proxy objects
173
 */
174
public interface LazyLoader extends Callback {
175
    Object loadObject() throws Exception;
176
}
177

178
/**
179
 * Callback that dispatches calls to different objects
180
 */
181
public interface Dispatcher extends Callback {
182
    Object loadObject() throws Exception;
183
}
184

185
/**
186
 * Dispatcher that receives reference to proxy object
187
 */
188
public interface ProxyRefDispatcher extends Callback {
189
    Object loadObject(Object proxy) throws Exception;
190
}
191

192
/**
193
 * JDK-compatible invocation handler interface
194
 */
195
public interface InvocationHandler extends Callback {
196
    Object invoke(Object proxy, Method method, Object[] args) throws Throwable;
197
}
198
```
199

200
### CallbackFilter
201

202
Interface for determining which callback to use for each method.
203

204
```java { .api }
205
/**
206
 * Interface for determining which callback to use for each method
207
 */
208
public interface CallbackFilter {
209
    /**
210
     * Determine callback index for given method
211
     * @param method - Method to filter
212
     * @return Index of callback to use (corresponds to callbacks array)
213
     */
214
    int accept(Method method);
215
}
216
```
217

218
### Factory Interface
219

220
Interface implemented by all enhanced classes for callback management.
221

222
```java { .api }
223
/**
224
 * Interface implemented by enhanced classes for callback management
225
 */
226
public interface Factory {
227
    /**
228
     * Create new instance with single callback
229
     * @param callback - Callback to use
230
     * @return New instance
231
     */
232
    Object newInstance(Callback callback);
233
    
234
    /**
235
     * Create new instance with multiple callbacks
236
     * @param callbacks - Array of callbacks
237
     * @return New instance
238
     */
239
    Object newInstance(Callback[] callbacks);
240
    
241
    /**
242
     * Create new instance with constructor arguments and callbacks
243
     * @param types - Constructor parameter types
244
     * @param args - Constructor arguments
245
     * @param callbacks - Array of callbacks
246
     * @return New instance
247
     */
248
    Object newInstance(Class[] types, Object[] args, Callback[] callbacks);
249
    
250
    /**
251
     * Set callback at specific index
252
     * @param index - Callback index
253
     * @param callback - Callback to set
254
     */
255
    void setCallback(int index, Callback callback);
256
    
257
    /**
258
     * Set all callbacks
259
     * @param callbacks - Array of callbacks
260
     */
261
    void setCallbacks(Callback[] callbacks);
262
    
263
    /**
264
     * Get callback at specific index
265
     * @param index - Callback index
266
     * @return Callback at index
267
     */
268
    Callback getCallback(int index);
269
    
270
    /**
271
     * Get all callbacks
272
     * @return Array of all callbacks
273
     */
274
    Callback[] getCallbacks();
275
}
276
```
277

278
### MethodProxy
279

280
Efficient method invocation mechanism for proxy objects.
281

282
```java { .api }
283
/**
284
 * Efficient method invocation mechanism for proxy objects
285
 */
286
public class MethodProxy {
287
    /**
288
     * Invoke super method implementation
289
     * @param obj - Object instance
290
     * @param args - Method arguments
291
     * @return Method result
292
     * @throws Throwable - Any exception from method execution
293
     */
294
    public Object invokeSuper(Object obj, Object[] args) throws Throwable;
295
    
296
    /**
297
     * Invoke original method (may cause infinite recursion if not careful)
298
     * @param obj - Object instance
299
     * @param args - Method arguments
300
     * @return Method result
301
     * @throws Throwable - Any exception from method execution
302
     */
303
    public Object invoke(Object obj, Object[] args) throws Throwable;
304
    
305
    /**
306
     * Get name of super method
307
     * @return Super method name
308
     */
309
    public String getSuperName();
310
    
311
    /**
312
     * Get index of super method
313
     * @return Super method index
314
     */
315
    public int getSuperIndex();
316
}
317
```