0
# Bean Utilities
1

2
Specialized utilities for JavaBean manipulation including high-performance property copying, Map-like access to bean properties, and dynamic bean generation at runtime.
3

4
## Core Imports
5

6
```java
7
import net.sf.cglib.beans.BeanCopier;
8
import net.sf.cglib.beans.BeanMap;
9
import net.sf.cglib.beans.BeanGenerator;
10
import net.sf.cglib.beans.ImmutableBean;
11
import net.sf.cglib.beans.BulkBean;
12
import net.sf.cglib.core.NamingPolicy;
13
import java.util.HashMap;
14
import java.util.Set;
15
import java.io.Serializable;
16
```
17

18
## Capabilities
19

20
### BeanCopier
21

22
High-performance utility for copying properties between JavaBean objects, much faster than reflection-based approaches.
23

24
```java { .api }
25
/**
26
 * High-performance bean copying utility
27
 */
28
public abstract class BeanCopier {
29
    /**
30
     * Create BeanCopier for copying between source and target types
31
     * @param source - Source class type
32
     * @param target - Target class type  
33
     * @param useConverter - Whether to use a converter for type conversion
34
     * @return BeanCopier instance
35
     */
36
    public static BeanCopier create(Class source, Class target, boolean useConverter);
37
    
38
    /**
39
     * Copy properties from source to target object
40
     * @param from - Source object
41
     * @param to - Target object  
42
     * @param converter - Converter for type conversion (null if useConverter was false)
43
     */
44
    public abstract void copy(Object from, Object to, Converter converter);
45
    
46
    /**
47
     * Converter interface for custom type conversion during copying
48
     */
49
    public interface Converter {
50
        /**
51
         * Convert value from source type to target type
52
         * @param value - Source value
53
         * @param target - Target property type
54
         * @param context - Property name for context
55
         * @return Converted value
56
         */
57
        Object convert(Object value, Class target, Object context);
58
    }
59
}
60
```
61

62
**Usage Examples:**
63

64
```java
65
import net.sf.cglib.beans.BeanCopier;
66

67
// Basic property copying (matching property names and types)
68
BeanCopier copier = BeanCopier.create(UserDto.class, User.class, false);
69
UserDto dto = new UserDto("John", "john@example.com", 25);
70
User user = new User();
71
copier.copy(dto, user, null);
72

73
// With custom converter for type conversion
74
BeanCopier converterCopier = BeanCopier.create(StringUser.class, User.class, true);
75
StringUser stringUser = new StringUser("Jane", "30", "jane@example.com");
76
User convertedUser = new User();
77

78
converterCopier.copy(stringUser, convertedUser, new BeanCopier.Converter() {
79
    @Override
80
    public Object convert(Object value, Class target, Object context) {
81
        if (target == int.class && "age".equals(context)) {
82
            return Integer.parseInt((String) value);
83
        }
84
        return value;
85
    }
86
});
87
```
88

89
### BeanMap
90

91
Provides Map-like interface for accessing JavaBean properties, allowing dynamic property access without reflection.
92

93
```java { .api }
94
/**
95
 * Map-like interface for bean property access
96
 */
97
public class BeanMap extends HashMap {
98
    /**
99
     * Create BeanMap for given bean instance
100
     * @param bean - Bean object to wrap
101
     * @return BeanMap instance
102
     */
103
    public static BeanMap create(Object bean);
104
    
105
    /**
106
     * Get the wrapped bean object
107
     * @return Bean object
108
     */
109
    public Object getBean();
110
    
111
    /**
112
     * Set new bean object to wrap
113
     * @param bean - New bean object
114
     */
115
    public void setBean(Object bean);
116
    
117
    /**
118
     * Get bean class
119
     * @return Bean class
120
     */
121
    public Class getBeanClass();
122
    
123
    /**
124
     * Get property value
125
     * @param key - Property name
126
     * @return Property value
127
     */
128
    @Override
129
    public Object get(Object key);
130
    
131
    /**
132
     * Set property value
133
     * @param key - Property name
134
     * @param value - Property value
135
     * @return Previous value
136
     */
137
    @Override
138
    public Object put(Object key, Object value);
139
    
140
    /**
141
     * Get property type
142
     * @param key - Property name
143
     * @return Property type
144
     */
145
    public Class getPropertyType(String key);
146
}
147
```
148

149
**Usage Examples:**
150

151
```java
152
import net.sf.cglib.beans.BeanMap;
153

154
// Create bean and wrap with BeanMap
155
User user = new User("Alice", "alice@example.com", 28);
156
BeanMap beanMap = BeanMap.create(user);
157

158
// Access properties like Map
159
String name = (String) beanMap.get("name");
160
String email = (String) beanMap.get("email");
161
Integer age = (Integer) beanMap.get("age");
162

163
// Modify properties
164
beanMap.put("name", "Alice Smith");
165
beanMap.put("age", 29);
166

167
// Check property types
168
Class nameType = beanMap.getPropertyType("name"); // Returns String.class
169
Class ageType = beanMap.getPropertyType("age");   // Returns int.class
170

171
// Iterate over properties
172
for (Object key : beanMap.keySet()) {
173
    System.out.println(key + " = " + beanMap.get(key));
174
}
175
```
176

177
### BeanGenerator
178

179
Runtime generation of JavaBean classes with dynamic properties.
180

181
```java { .api }
182
/**
183
 * Runtime generation of bean classes with properties
184
 */
185
public class BeanGenerator extends AbstractClassGenerator {
186
    /**
187
     * Add property to generated bean class
188
     * @param name - Property name
189
     * @param type - Property type
190
     */
191
    public void addProperty(String name, Class type);
192
    
193
    /**
194
     * Create instance of generated bean class
195
     * @return Bean instance
196
     */
197
    public Object create();
198
    
199
    /**
200
     * Create instance with specific ClassLoader
201
     * @param loader - ClassLoader to use
202
     * @return Bean instance
203
     */
204
    public Object createClass(ClassLoader loader);
205
    
206
    /**
207
     * Set naming policy for generated class
208
     * @param namingPolicy - Naming policy
209
     */
210
    public void setNamingPolicy(NamingPolicy namingPolicy);
211
}
212
```
213

214
**Usage Examples:**
215

216
```java
217
import net.sf.cglib.beans.BeanGenerator;
218
import net.sf.cglib.beans.BeanMap;
219

220
// Generate bean class at runtime
221
BeanGenerator generator = new BeanGenerator();
222
generator.addProperty("firstName", String.class);
223
generator.addProperty("lastName", String.class);
224
generator.addProperty("age", Integer.class);
225

226
// Create instance
227
Object dynamicBean = generator.create();
228

229
// Use BeanMap to set properties
230
BeanMap beanMap = BeanMap.create(dynamicBean);
231
beanMap.put("firstName", "Dynamic");
232
beanMap.put("lastName", "User");
233
beanMap.put("age", 35);
234

235
System.out.println("Generated bean: " + beanMap);
236
```
237

238
### ImmutableBean
239

240
Creates immutable wrappers around mutable JavaBean objects.
241

242
```java { .api }
243
/**
244
 * Creates immutable wrappers around mutable beans
245
 */
246
public class ImmutableBean {
247
    /**
248
     * Create immutable wrapper for given bean
249
     * @param bean - Bean to make immutable
250
     * @return Immutable wrapper
251
     */
252
    public static Object create(Object bean);
253
}
254
```
255

256
**Usage Examples:**
257

258
```java
259
import net.sf.cglib.beans.ImmutableBean;
260

261
// Create mutable bean
262
User mutableUser = new User("John", "john@example.com", 30);
263

264
// Create immutable wrapper
265
User immutableUser = (User) ImmutableBean.create(mutableUser);
266

267
// Reading works normally
268
String name = immutableUser.getName();
269
String email = immutableUser.getEmail();
270

271
// Attempts to modify will throw UnsupportedOperationException
272
try {
273
    immutableUser.setName("Jane"); // Throws exception
274
} catch (UnsupportedOperationException e) {
275
    System.out.println("Cannot modify immutable bean");
276
}
277
```
278

279
### BulkBean
280

281
Provides bulk property access for multiple properties at once, useful for performance-critical scenarios.
282

283
```java { .api }
284
/**
285
 * Bulk property access for multiple properties
286
 */
287
public abstract class BulkBean {
288
    /**
289
     * Create BulkBean for specific properties of a class
290
     * @param target - Target class
291
     * @param getters - Property getter names
292
     * @param setters - Property setter names  
293
     * @param types - Property types
294
     * @return BulkBean instance
295
     */
296
    public static BulkBean create(Class target, String[] getters, String[] setters, Class[] types);
297
    
298
    /**
299
     * Get all property values at once
300
     * @param bean - Bean instance
301
     * @param values - Array to store values (must be correct size)
302
     */
303
    public abstract void getPropertyValues(Object bean, Object[] values);
304
    
305
    /**
306
     * Set all property values at once
307
     * @param bean - Bean instance
308
     * @param values - Values to set
309
     */
310
    public abstract void setPropertyValues(Object bean, Object[] values);
311
}
312
```
313

314
**Usage Examples:**
315

316
```java
317
import net.sf.cglib.beans.BulkBean;
318

319
// Define properties for bulk access
320
String[] getters = {"getName", "getEmail", "getAge"};
321
String[] setters = {"setName", "setEmail", "setAge"};
322
Class[] types = {String.class, String.class, int.class};
323

324
// Create BulkBean
325
BulkBean bulkBean = BulkBean.create(User.class, getters, setters, types);
326

327
// Get all properties at once
328
User user = new User("Bob", "bob@example.com", 25);
329
Object[] values = new Object[3];
330
bulkBean.getPropertyValues(user, values);
331
// values now contains ["Bob", "bob@example.com", 25]
332

333
// Set all properties at once
334
Object[] newValues = {"Robert", "robert@example.com", 26};
335
bulkBean.setPropertyValues(user, newValues);
336
```