0
# Core Utilities
1

2
Core internal classes and utilities that provide foundational functionality for CGLib's bytecode generation. While primarily internal, some classes offer public APIs for advanced use cases and integration with other bytecode generation scenarios.
3

4
## Capabilities
5

6
### Signature
7

8
Represents method and constructor signatures for bytecode generation, providing a structured way to handle method identification and comparison.
9

10
```java { .api }
11
/**
12
 * Represents method signatures for bytecode generation
13
 */
14
public class Signature {
15
    /**
16
     * Create method signature
17
     * @param name - Method name
18
     * @param returnType - Return type descriptor
19
     * @param argumentTypes - Argument type descriptors
20
     */
21
    public Signature(String name, String returnType, String[] argumentTypes);
22
    
23
    /**
24
     * Get method name
25
     * @return Method name
26
     */
27
    public String getName();
28
    
29
    /**
30
     * Get return type descriptor
31
     * @return Return type descriptor string
32
     */
33
    public String getReturnType();
34
    
35
    /**
36
     * Get argument type descriptors
37
     * @return Array of argument type descriptor strings
38
     */
39
    public String[] getArgumentTypes();
40
    
41
    /**
42
     * Get method descriptor string
43
     * @return Complete method descriptor
44
     */
45
    public String getDescriptor();
46
    
47
    /**
48
     * Check equality with another signature
49
     * @param obj - Object to compare
50
     * @return true if signatures are equal
51
     */
52
    @Override
53
    public boolean equals(Object obj);
54
    
55
    /**
56
     * Get hash code for signature
57
     * @return Hash code
58
     */
59
    @Override
60
    public int hashCode();
61
    
62
    /**
63
     * Get string representation
64
     * @return String representation of signature
65
     */
66
    @Override
67
    public String toString();
68
}
69
```
70

71
**Usage Examples:**
72

73
```java
74
import net.sf.cglib.core.Signature;
75

76
// Create signature for method: String getName()
77
Signature getterSig = new Signature("getName", "Ljava/lang/String;", new String[0]);
78

79
// Create signature for method: void setAge(int age)
80
Signature setterSig = new Signature("setAge", "V", new String[]{"I"});
81

82
// Create signature for method: List<String> findItems(String query, int limit)
83
Signature findSig = new Signature("findItems", 
84
    "Ljava/util/List;", 
85
    new String[]{"Ljava/lang/String;", "I"});
86

87
// Compare signatures
88
boolean isEqual = getterSig.equals(otherSignature);
89

90
// Use in collections (implements proper hashCode/equals)
91
Set<Signature> methodSignatures = new HashSet<>();
92
methodSignatures.add(getterSig);
93
methodSignatures.add(setterSig);
94
```
95

96
### ClassGenerator
97

98
Low-level class generation utilities providing foundational bytecode generation capabilities used by higher-level CGLib components.
99

100
```java { .api }
101
/**
102
 * Low-level class generation utilities
103
 */
104
public abstract class ClassGenerator extends AbstractClassGenerator {
105
    /**
106
     * Generate class bytecode
107
     * @param strategy - Generation strategy
108
     * @return Generated class
109
     * @throws Exception - If generation fails
110
     */
111
    protected abstract Class generate(ClassLoaderData data) throws Exception;
112
    
113
    /**
114
     * Get default ClassLoader
115
     * @return Default ClassLoader
116
     */
117
    protected ClassLoader getDefaultClassLoader();
118
    
119
    /**
120
     * Generate class name
121
     * @return Generated class name
122
     */
123
    protected String generateClassName();
124
    
125
    /**
126
     * Create class generator
127
     * @param source - Source object for generation context
128
     */
129
    protected ClassGenerator(Source source);
130
}
131
```
132

133
### AbstractClassGenerator
134

135
Base class for all CGLib class generators, providing common functionality for bytecode generation.
136

137
```java { .api }
138
/**
139
 * Base class for all CGLib class generators
140
 */
141
public abstract class AbstractClassGenerator implements ClassGenerator {
142
    /**
143
     * Set class loader for generated classes
144
     * @param classLoader - ClassLoader to use
145
     */
146
    public void setClassLoader(ClassLoader classLoader);
147
    
148
    /**
149
     * Get class loader for generated classes
150
     * @return ClassLoader being used
151
     */
152
    public ClassLoader getClassLoader();
153
    
154
    /**
155
     * Set naming policy for generated classes
156
     * @param namingPolicy - NamingPolicy implementation
157
     */
158
    public void setNamingPolicy(NamingPolicy namingPolicy);
159
    
160
    /**
161
     * Get naming policy
162
     * @return Current NamingPolicy
163
     */
164
    public NamingPolicy getNamingPolicy();
165
    
166
    /**
167
     * Set generation strategy
168
     * @param strategy - GeneratorStrategy implementation
169
     */
170
    public void setStrategy(GeneratorStrategy strategy);
171
    
172
    /**
173
     * Get generation strategy
174
     * @return Current GeneratorStrategy
175
     */
176
    public GeneratorStrategy getStrategy();
177
    
178
    /**
179
     * Create instance of generated class
180
     * @param key - Cache key for class generation
181
     * @return Generated class instance
182
     */
183
    protected Object create(Object key);
184
}
185
```
186

187
### NamingPolicy
188

189
Policy interface for generating names of dynamically created classes.
190

191
```java { .api }
192
/**
193
 * Policy interface for generating names of dynamically created classes
194
 */
195
public interface NamingPolicy {
196
    /**
197
     * Generate class name
198
     * @param prefix - Prefix for class name
199
     * @param source - Source class name
200
     * @param key - Generation key object
201
     * @param names - Predicate to check for name conflicts
202
     * @return Generated class name
203
     */
204
    String getClassName(String prefix, String source, Object key, Predicate names);
205
    
206
    /**
207
     * Default naming policy instance
208
     */
209
    NamingPolicy DEFAULT = new DefaultNamingPolicy();
210
}
211
```
212

213
**Usage Examples:**
214

215
```java
216
import net.sf.cglib.core.NamingPolicy;
217
import net.sf.cglib.core.Predicate;
218

219
// Custom naming policy
220
NamingPolicy customPolicy = new NamingPolicy() {
221
    @Override
222
    public String getClassName(String prefix, String source, Object key, Predicate names) {
223
        return "com.mycompany.generated." + prefix + "$$" + source + "$$" + key.hashCode();
224
    }
225
};
226

227
// Use with Enhancer
228
Enhancer enhancer = new Enhancer();
229
enhancer.setSuperclass(MyClass.class);
230
enhancer.setNamingPolicy(customPolicy);
231
enhancer.setCallback(interceptor);
232
Object proxy = enhancer.create();
233
```
234

235
## Exception Types
236

237
```java { .api }
238
/**
239
 * Runtime exception for undeclared checked exceptions in proxy methods
240
 */
241
public class UndeclaredThrowableException extends RuntimeException {
242
    /**
243
     * Create exception with undeclared throwable
244
     * @param undeclaredThrowable - The undeclared exception
245
     */
246
    public UndeclaredThrowableException(Throwable undeclaredThrowable);
247
    
248
    /**
249
     * Get the undeclared throwable
250
     * @return Undeclared throwable cause
251
     */
252
    public Throwable getUndeclaredThrowable();
253
}
254

255
/**
256
 * Exception thrown when code generation fails
257
 */
258
public class CodeGenerationException extends RuntimeException {
259
    /**
260
     * Create exception with message
261
     * @param message - Error message
262
     */
263
    public CodeGenerationException(String message);
264
    
265
    /**
266
     * Create exception with message and cause
267
     * @param message - Error message
268
     * @param cause - Underlying cause
269
     */
270
    public CodeGenerationException(String message, Throwable cause);
271
}
272
```
273

274
## Types
275

276
```java { .api }
277
import org.objectweb.asm.ClassWriter;
278
import org.objectweb.asm.ClassVisitor;
279

280
/**
281
 * Strategy interface for generating classes
282
 */
283
public interface GeneratorStrategy {
284
    /**
285
     * Generate class bytecode
286
     * @param cg - ClassGenerator instance
287
     * @return Generated class bytecode
288
     * @throws Exception - If generation fails
289
     */
290
    byte[] generate(ClassGenerator cg) throws Exception;
291
    
292
    /**
293
     * Default strategy instance
294
     */
295
    GeneratorStrategy DEFAULT = new DefaultGeneratorStrategy();
296
}
297

298
/**
299
 * Predicate interface for filtering operations
300
 */
301
public interface Predicate {
302
    /**
303
     * Evaluate predicate
304
     * @param arg - Argument to evaluate
305
     * @return true if predicate matches, false otherwise
306
     */
307
    boolean evaluate(Object arg);
308
}
309
```
310

311
## Usage Notes
312

313
- **Internal APIs**: These classes are primarily for internal use but provide extension points for advanced users
314
- **ASM Integration**: Core utilities work directly with ASM framework for bytecode manipulation
315
- **Caching**: Class generation results are cached for performance using these core utilities
316
- **Thread Safety**: Most core utilities are thread-safe, but class generation itself should be synchronized