0
# Bean Utilities
1

2
High-performance JavaBean manipulation utilities including property copying, dynamic bean generation, Map-based bean access, and bulk operations. These utilities provide alternatives to reflection-based bean operations with significantly better performance.
3

4
## Capabilities
5

6
### BeanCopier
7

8
High-performance copying of JavaBean properties between objects of different types.
9

10
```java { .api }
11
/**
12
 * High-performance copying of JavaBean properties between objects
13
 */
14
public abstract class BeanCopier {
15
    /**
16
     * Create a BeanCopier for copying between specific types
17
     * @param source Source class
18
     * @param target Target class  
19
     * @param useConverter Whether to use a Converter
20
     * @return BeanCopier instance
21
     */
22
    public static BeanCopier create(Class source, Class target, boolean useConverter);
23
    
24
    /**
25
     * Copy properties from source to target object
26
     * @param from Source object
27
     * @param to Target object
28
     * @param converter Converter for property transformation (or null)
29
     */
30
    public abstract void copy(Object from, Object to, Converter converter);
31
}
32
```
33

34
**Usage Examples:**
35

36
```java
37
// Simple property copying
38
BeanCopier copier = BeanCopier.create(SourceBean.class, TargetBean.class, false);
39
SourceBean source = new SourceBean();
40
source.setName("John");
41
source.setAge(30);
42

43
TargetBean target = new TargetBean();
44
copier.copy(source, target, null);
45
// target now has name="John", age=30
46

47
// Using converter for type transformation
48
BeanCopier converterCopier = BeanCopier.create(User.class, UserDTO.class, true);
49
Converter dateConverter = new Converter() {
50
    public Object convert(Object value, Class target, Object context) {
51
        if (value instanceof Date && target == String.class) {
52
            return new SimpleDateFormat("yyyy-MM-dd").format((Date) value);
53
        }
54
        return value;
55
    }
56
};
57

58
User user = new User();
59
user.setBirthDate(new Date());
60
UserDTO dto = new UserDTO();
61
converterCopier.copy(user, dto, dateConverter);
62
```
63

64
### BeanMap
65

66
Provides a Map-based view of JavaBean objects, allowing property access via Map operations.
67

68
```java { .api }
69
/**
70
 * Map-based view of JavaBean objects
71
 */
72
public abstract class BeanMap implements Map {
73
    // Property access flags
74
    public static final int REQUIRE_GETTER = 1;
75
    public static final int REQUIRE_SETTER = 2;
76
    
77
    /**
78
     * Create BeanMap for an object
79
     * @param bean Target bean object
80
     * @return BeanMap instance
81
     */
82
    public static BeanMap create(Object bean);
83
    
84
    /**
85
     * Create new BeanMap instance for different bean
86
     * @param bean New target bean
87
     * @return New BeanMap instance
88
     */
89
    public abstract BeanMap newInstance(Object bean);
90
    
91
    /**
92
     * Get property type
93
     * @param name Property name
94
     * @return Property type
95
     */
96
    public abstract Class getPropertyType(String name);
97
    
98
    /**
99
     * Get property value from specific bean
100
     * @param bean Target bean
101
     * @param key Property name
102
     * @return Property value
103
     */
104
    public abstract Object get(Object bean, Object key);
105
    
106
    /**
107
     * Set property value on specific bean
108
     * @param bean Target bean
109
     * @param key Property name  
110
     * @param value New value
111
     * @return Previous value
112
     */
113
    public abstract Object put(Object bean, Object key, Object value);
114
    
115
    /**
116
     * Set the target bean for this map
117
     * @param bean Target bean
118
     */
119
    public void setBean(Object bean);
120
    
121
    /**
122
     * Get the current target bean
123
     * @return Current bean
124
     */
125
    public Object getBean();
126
    
127
    // Map interface methods inherited:
128
    // Object get(Object key)
129
    // Object put(Object key, Object value) 
130
    // boolean containsKey(Object key)
131
    // boolean containsValue(Object value)
132
    // int size()
133
    // boolean isEmpty()
134
    // Set keySet()
135
    // Collection values()
136
    // Set entrySet()
137
    // void clear()
138
    // Object remove(Object key)
139
    // void putAll(Map m)
140
}
141
```
142

143
**Usage Examples:**
144

145
```java
146
// Use bean as a Map
147
Person person = new Person("Alice", 25);
148
BeanMap map = BeanMap.create(person);
149

150
// Get properties via Map interface
151
String name = (String) map.get("name"); // "Alice"
152
Integer age = (Integer) map.get("age");  // 25
153

154
// Set properties via Map interface
155
map.put("name", "Bob");
156
map.put("age", 30);
157
// person object now has name="Bob", age=30
158

159
// Iterate over properties
160
for (Object key : map.keySet()) {
161
    System.out.println(key + " = " + map.get(key));
162
}
163

164
// Check property types
165
Class nameType = map.getPropertyType("name"); // String.class
166
Class ageType = map.getPropertyType("age");   // Integer.class
167

168
// Use same BeanMap with different bean
169
Person person2 = new Person();
170
BeanMap map2 = map.newInstance(person2);
171
map2.put("name", "Charlie");
172
```
173

174
### BeanGenerator
175

176
Dynamically creates JavaBean classes with specified properties at runtime.
177

178
```java { .api }
179
/**
180
 * Dynamically creates JavaBean classes with properties
181
 */
182
public class BeanGenerator {
183
    /**
184
     * Default constructor
185
     */
186
    public BeanGenerator();
187
    
188
    /**
189
     * Set superclass for generated bean
190
     * @param superclass Superclass to extend
191
     */
192
    public void setSuperclass(Class superclass);
193
    
194
    /**
195
     * Add property to generated bean
196
     * @param name Property name
197
     * @param type Property type
198
     */
199
    public void addProperty(String name, Class type);
200
    
201
    /**
202
     * Create instance of generated bean class
203
     * @return Bean instance
204
     */
205
    public Object create();
206
    
207
    /**
208
     * Create the bean class (without instantiating)
209
     * @return Generated class
210
     */
211
    public Object createClass();
212
    
213
    /**
214
     * Add properties from a Map
215
     * @param gen BeanGenerator instance
216
     * @param props Map of property names to types
217
     */
218
    public static void addProperties(BeanGenerator gen, Map props);
219
    
220
    /**
221
     * Add properties from existing class
222
     * @param gen BeanGenerator instance
223
     * @param type Class to copy properties from
224
     */
225
    public static void addProperties(BeanGenerator gen, Class type);
226
    
227
    /**
228
     * Add properties from PropertyDescriptors
229
     * @param gen BeanGenerator instance
230
     * @param descriptors Array of PropertyDescriptors
231
     */
232
    public static void addProperties(BeanGenerator gen, PropertyDescriptor[] descriptors);
233
}
234
```
235

236
**Usage Examples:**
237

238
```java
239
// Create dynamic bean class
240
BeanGenerator generator = new BeanGenerator();
241
generator.addProperty("name", String.class);
242
generator.addProperty("age", Integer.class);
243
generator.addProperty("active", Boolean.class);
244

245
// Create instance
246
Object bean = generator.create();
247

248
// Use with BeanMap for property access
249
BeanMap map = BeanMap.create(bean);
250
map.put("name", "Dynamic Bean");
251
map.put("age", 42);
252
map.put("active", true);
253

254
System.out.println(map.get("name")); // "Dynamic Bean"
255

256
// Create bean extending existing class
257
BeanGenerator extendingGen = new BeanGenerator();
258
extendingGen.setSuperclass(BaseEntity.class);
259
extendingGen.addProperty("customField", String.class);
260
Object extendedBean = extendingGen.create();
261

262
// Add properties from existing class
263
BeanGenerator copyGen = new BeanGenerator();
264
BeanGenerator.addProperties(copyGen, Person.class);
265
copyGen.addProperty("extraField", Date.class);
266
Object enrichedBean = copyGen.create();
267

268
// Add properties from Map
269
Map<String, Class> propertyMap = new HashMap<>();
270
propertyMap.put("title", String.class);
271
propertyMap.put("score", Double.class);
272
BeanGenerator mapGen = new BeanGenerator();
273
BeanGenerator.addProperties(mapGen, propertyMap);
274
Object mapBean = mapGen.create();
275
```
276

277
### BulkBean
278

279
Efficient bulk property access operations for JavaBeans using arrays.
280

281
```java { .api }
282
/**
283
 * Efficient bulk property access for JavaBeans
284
 */
285
public abstract class BulkBean {
286
    /**
287
     * Create BulkBean for specific class and properties
288
     * @param target Target class
289
     * @param getters Array of getter method names
290
     * @param setters Array of setter method names  
291
     * @param types Array of property types
292
     * @return BulkBean instance
293
     */
294
    public static BulkBean create(Class target, String[] getters, String[] setters, Class[] types);
295
    
296
    /**
297
     * Get all property values into array
298
     * @param bean Target bean
299
     * @param values Array to fill with values
300
     */
301
    public abstract void getPropertyValues(Object bean, Object[] values);
302
    
303
    /**
304
     * Set all property values from array
305
     * @param bean Target bean
306
     * @param values Array of values to set
307
     */
308
    public abstract void setPropertyValues(Object bean, Object[] values);
309
    
310
    /**
311
     * Get property values as new array
312
     * @param bean Target bean
313
     * @return Array of property values
314
     */
315
    public Object[] getPropertyValues(Object bean);
316
    
317
    /**
318
     * Get property types
319
     * @return Array of property types
320
     */
321
    public Class[] getPropertyTypes();
322
    
323
    /**
324
     * Get getter method names
325
     * @return Array of getter names
326
     */
327
    public String[] getGetters();
328
    
329
    /**
330
     * Get setter method names
331
     * @return Array of setter names
332
     */
333
    public String[] getSetters();
334
}
335
```
336

337
**Usage Examples:**
338

339
```java
340
// Create BulkBean for efficient property access
341
BulkBean bulkBean = BulkBean.create(
342
    Person.class,
343
    new String[]{"getName", "getAge", "getEmail"},  // getters
344
    new String[]{"setName", "setAge", "setEmail"},  // setters
345
    new Class[]{String.class, Integer.class, String.class}  // types
346
);
347

348
Person person = new Person("John", 30, "john@example.com");
349

350
// Get all values at once
351
Object[] values = new Object[3];
352
bulkBean.getPropertyValues(person, values);
353
// values[0] = "John", values[1] = 30, values[2] = "john@example.com"
354

355
// Or get as new array
356
Object[] allValues = bulkBean.getPropertyValues(person);
357

358
// Set all values at once
359
Person newPerson = new Person();
360
bulkBean.setPropertyValues(newPerson, new Object[]{"Jane", 25, "jane@example.com"});
361

362
// Useful for batch operations
363
List<Person> people = getPersonList();
364
for (Person p : people) {
365
    Object[] personValues = bulkBean.getPropertyValues(p);
366
    // Process values in bulk
367
    processValues(personValues);
368
}
369
```
370

371
### BulkBeanException
372

373
Exception thrown during bulk bean operations.
374

375
```java { .api }
376
/**
377
 * Exception for bulk bean operations
378
 */
379
public class BulkBeanException extends RuntimeException {
380
    /**
381
     * Constructor with message and index
382
     * @param message Error message
383
     * @param index Index of failing property
384
     */
385
    public BulkBeanException(String message, int index);
386
    
387
    /**
388
     * Constructor with cause and index
389
     * @param cause Underlying cause
390
     * @param index Index of failing property
391
     */
392
    public BulkBeanException(Throwable cause, int index);
393
    
394
    /**
395
     * Get the index of the failing property
396
     * @return Property index
397
     */
398
    public int getIndex();
399
    
400
    /**
401
     * Get the underlying cause
402
     * @return Throwable cause
403
     */
404
    public Throwable getCause();
405
}
406
```
407

408
### ImmutableBean
409

410
Creates immutable wrappers around mutable JavaBeans.
411

412
```java { .api }
413
/**
414
 * Creates immutable wrappers around mutable beans
415
 */
416
public class ImmutableBean {
417
    /**
418
     * Create immutable wrapper for a bean
419
     * @param bean Bean to wrap
420
     * @return Immutable wrapper
421
     */
422
    public static Object create(Object bean);
423
}
424
```
425

426
**Usage Example:**
427

428
```java
429
// Create mutable bean
430
Person mutablePerson = new Person("Alice", 30);
431
mutablePerson.setAge(31); // This works
432

433
// Create immutable wrapper
434
Person immutablePerson = (Person) ImmutableBean.create(mutablePerson);
435

436
// Reading works fine
437
String name = immutablePerson.getName(); // "Alice"
438
int age = immutablePerson.getAge();      // 31
439

440
// But writing throws exception
441
try {
442
    immutablePerson.setAge(32); // Throws exception
443
} catch (Exception e) {
444
    System.out.println("Cannot modify immutable bean");
445
}
446

447
// Original bean is still mutable
448
mutablePerson.setAge(35); // Still works
449
```
450

451
### FixedKeySet
452

453
Utility class providing an immutable set implementation used internally by BeanMap.
454

455
```java { .api }
456
/**
457
 * Immutable set implementation for BeanMap keys
458
 */
459
public class FixedKeySet extends AbstractSet {
460
    /**
461
     * Constructor
462
     * @param keys Array of keys
463
     */
464
    public FixedKeySet(String[] keys);
465
    
466
    /**
467
     * Get iterator over keys
468
     * @return Iterator
469
     */
470
    public Iterator iterator();
471
    
472
    /**
473
     * Get set size
474
     * @return Size
475
     */
476
    public int size();
477
}
478
```
479

480
## Type Definitions
481

482
### Converter Interface
483

484
```java { .api }
485
/**
486
 * Interface for converting values during bean copying
487
 */
488
public interface Converter {
489
    /**
490
     * Convert a value
491
     * @param value Source value
492
     * @param target Target type
493
     * @param context Context information (property name)
494
     * @return Converted value
495
     */
496
    Object convert(Object value, Class target, Object context);
497
}
498
```