0
# Bean and Object Manipulation
1

2
Comprehensive bean and object utilities through the `BeanUtil` and `ObjectUtil` classes, providing property access, copying, conversion, and dynamic manipulation.
3

4
## Import
5

6
```java
7
import cn.hutool.core.bean.BeanUtil;
8
import cn.hutool.core.util.ObjectUtil;
9
import cn.hutool.core.bean.DynaBean;
10
import cn.hutool.core.convert.Convert;
11
```
12

13
## Bean Property Operations
14

15
### Property Access
16

17
```java { .api }
18
// Get property values
19
public static Object getProperty(Object bean, String expression);
20
public static <T> T getProperty(Object bean, String expression, Class<T> targetType);
21

22
// Set property values
23
public static void setProperty(Object bean, String expression, Object value);
24
public static void setProperty(Object bean, String expression, Object value, boolean ignoreError);
25

26
// Check if property exists
27
public static boolean hasProperty(Object bean, String expression);
28
```
29

30
### Property Descriptors
31

32
```java { .api }
33
// Get property descriptors
34
public static PropertyDescriptor[] getPropertyDescriptors(Class<?> beanClass);
35
public static PropertyDescriptor getPropertyDescriptor(Class<?> beanClass, String propertyName);
36

37
// Get property names
38
public static String[] getPropertyNames(Class<?> beanClass);
39
public static Collection<String> getPropertyNames(Object bean);
40
```
41

42
**Usage Examples:**
43

44
```java
45
User user = new User();
46
user.setName("John");
47
user.getAddress().setCity("New York");
48

49
// Get properties
50
String name = BeanUtil.getProperty(user, "name");           // "John"
51
String city = BeanUtil.getProperty(user, "address.city");   // "New York"
52

53
// Set properties
54
BeanUtil.setProperty(user, "age", 30);
55
BeanUtil.setProperty(user, "address.zipCode", "10001");
56

57
// Check property existence
58
boolean hasName = BeanUtil.hasProperty(user, "name");       // true
59
boolean hasEmail = BeanUtil.hasProperty(user, "email");     // depends on User class
60
```
61

62
## Bean Copying and Conversion
63

64
### Bean Copying
65

66
```java { .api }
67
// Copy properties between beans
68
public static void copyProperties(Object source, Object target);
69
public static void copyProperties(Object source, Object target, String... ignoreProperties);
70
public static void copyProperties(Object source, Object target, CopyOptions copyOptions);
71

72
// Copy with type conversion
73
public static <T> T copyProperties(Object source, Class<T> targetClass);
74
public static <T> T copyProperties(Object source, Class<T> targetClass, String... ignoreProperties);
75
```
76

77
### Bean to Map Conversion
78

79
```java { .api }
80
// Bean to Map
81
public static Map<String, Object> beanToMap(Object bean);
82
public static Map<String, Object> beanToMap(Object bean, boolean ignoreNullValue, 
83
                                           boolean ignoreError);
84

85
// Map to Bean
86
public static <T> T mapToBean(Map<?, ?> map, Class<T> beanClass, boolean ignoreError);
87
public static <T> T mapToBean(Map<?, ?> map, Class<T> beanClass, CopyOptions copyOptions);
88

89
// Fill bean from map
90
public static <T> T fillBean(T bean, Map<?, ?> map, boolean ignoreError);
91
```
92

93
**Usage Examples:**
94

95
```java
96
// Copy between beans
97
User sourceUser = new User("John", 30);
98
User targetUser = new User();
99
BeanUtil.copyProperties(sourceUser, targetUser);
100

101
// Copy to different type
102
UserDTO dto = BeanUtil.copyProperties(sourceUser, UserDTO.class);
103

104
// Copy with exclusions
105
BeanUtil.copyProperties(sourceUser, targetUser, "password", "lastLogin");
106

107
// Bean to Map
108
Map<String, Object> userMap = BeanUtil.beanToMap(sourceUser);
109
// Result: {"name": "John", "age": 30, ...}
110

111
// Map to Bean
112
Map<String, Object> data = MapUtil.of("name", "Jane", "age", 25);
113
User user = BeanUtil.mapToBean(data, User.class, false);
114
```
115

116
## Dynamic Bean (DynaBean)
117

118
### DynaBean Class
119

120
```java { .api }
121
public class DynaBean {
122
    // Creation  
123
    public static DynaBean create(Object bean);
124
    public static DynaBean create(Class<?> beanClass, Object... params);
125
    
126
    // Property access
127
    public Object get(String name);
128
    public <T> T get(String name, Class<T> type);
129
    public DynaBean set(String name, Object value);
130
    
131
    // Invoke methods
132
    public Object invoke(String methodName, Object... params);
133
    
134
    // Check existence
135
    public boolean containsKey(String name);
136
    
137
    // Get underlying bean
138
    public Object getBean();
139
    public Class<?> getBeanClass();
140
}
141
```
142

143
**Usage Examples:**
144

145
```java
146
// Create dynamic bean wrapper
147
User user = new User();
148
DynaBean dynaBean = DynaBean.create(user);
149

150
// Dynamic property access
151
dynaBean.set("name", "John")
152
        .set("age", 30)
153
        .set("email", "john@example.com");
154

155
String name = dynaBean.get("name", String.class);
156

157
// Dynamic method invocation
158
dynaBean.invoke("setActive", true);
159
Boolean active = dynaBean.invoke("isActive");
160

161
// Create bean dynamically
162
DynaBean newBean = DynaBean.create(User.class);
163
newBean.set("name", "Dynamic User");
164
User actualUser = (User) newBean.getBean();
165
```
166

167
## Object Utilities
168

169
### Object Validation
170

171
```java { .api }
172
// Null checks
173
public static boolean isNull(Object obj);
174
public static boolean isNotNull(Object obj);
175
public static boolean hasNull(Object... objs);
176
public static boolean isAllNull(Object... objs);
177

178
// Empty checks (for collections, arrays, strings)
179
public static boolean isEmpty(Object obj);
180
public static boolean isNotEmpty(Object obj);
181

182
// Default value operations
183
public static <T> T defaultIfNull(T object, T defaultValue);
184
public static <T> T defaultIfEmpty(T object, T defaultValue);
185
```
186

187
### Object Comparison
188

189
```java { .api }
190
// Equality checks
191
public static boolean equals(Object obj1, Object obj2);
192
public static boolean notEquals(Object obj1, Object obj2);
193

194
// Length/size operations
195
public static int length(Object obj);
196
public static boolean contains(Object obj, Object element);
197
```
198

199
### Object Cloning
200

201
```java { .api }
202
// Deep cloning
203
public static <T> T clone(T obj);
204
public static <T> T cloneIfPossible(T obj);
205

206
// Shallow cloning
207
public static <T> T cloneByStream(T obj);
208
```
209

210
**Usage Examples:**
211

212
```java
213
// Null safety
214
String value = ObjectUtil.defaultIfNull(getName(), "Unknown");
215
boolean hasData = ObjectUtil.isNotEmpty(getDataList());
216

217
// Safe comparison
218
boolean same = ObjectUtil.equals(user1.getId(), user2.getId());
219

220
// Object length
221
int size = ObjectUtil.length(userList);      // Works with collections
222
int arrayLen = ObjectUtil.length(userArray); // Works with arrays
223
int strLen = ObjectUtil.length("hello");     // Works with strings
224

225
// Deep cloning
226
User originalUser = new User("John", Arrays.asList("skill1", "skill2"));
227
User clonedUser = ObjectUtil.clone(originalUser);
228
clonedUser.getSkills().add("skill3"); // Won't affect original
229
```
230

231
## Type Conversion
232

233
### Convert Class
234

235
```java { .api }
236
// Basic type conversion
237
public static <T> T convert(Class<T> type, Object value);
238
public static <T> T convert(Class<T> type, Object value, T defaultValue);
239

240
// Collection conversion
241
public static <T> List<T> toList(Class<T> componentType, Object value);
242
public static <T> Set<T> toSet(Class<T> componentType, Object value);
243

244
// Array conversion
245
public static <T> T[] toArray(Class<T> componentType, Object value);
246

247
// Map conversion
248
public static <K, V> Map<K, V> toMap(Class<K> keyType, Class<V> valueType, Object value);
249
```
250

251
**Usage Examples:**
252

253
```java
254
// Type conversion
255
String numberStr = "123";
256
Integer number = Convert.convert(Integer.class, numberStr);
257

258
Date dateValue = Convert.convert(Date.class, "2023-12-25");
259
Boolean boolValue = Convert.convert(Boolean.class, "true");
260

261
// Collection conversion
262
List<String> stringValues = Arrays.asList("1", "2", "3");
263
List<Integer> intValues = Convert.toList(Integer.class, stringValues);
264

265
// Array conversion
266
String[] stringArray = {"1", "2", "3"};
267
Integer[] intArray = Convert.toArray(Integer.class, stringArray);
268

269
// Default values
270
Integer result = Convert.convert(Integer.class, "invalid", 0);
271
```
272

273
## Copy Options and Configuration
274

275
### CopyOptions Class
276

277
```java { .api }
278
public class CopyOptions {
279
    // Creation
280
    public static CopyOptions create();
281
    
282
    // Configuration
283
    public CopyOptions setIgnoreNullValue(boolean ignoreNullValue);
284
    public CopyOptions setIgnoreError(boolean ignoreError);
285
    public CopyOptions setIgnoreCase(boolean ignoreCase);
286
    public CopyOptions setFieldNameEditor(Editor<String> fieldNameEditor);
287
    public CopyOptions setPropertiesFilter(Filter<Field> propertiesFilter);
288
    
289
    // Field mapping
290
    public CopyOptions setFieldMapping(Map<String, String> fieldMapping);
291
    public CopyOptions addFieldMapping(String srcFieldName, String destFieldName);
292
    
293
    // Ignored properties
294
    public CopyOptions setIgnoreProperties(String... ignoreProperties);
295
}
296
```
297

298
**Usage Examples:**
299

300
```java
301
// Custom copy options
302
CopyOptions options = CopyOptions.create()
303
    .setIgnoreNullValue(true)
304
    .setIgnoreError(true)
305
    .setIgnoreCase(true)
306
    .addFieldMapping("userName", "name")
307
    .setIgnoreProperties("password", "lastLogin");
308

309
// Copy with custom options
310
UserDTO dto = new UserDTO();
311
BeanUtil.copyProperties(user, dto, options);
312

313
// Field name transformation
314
CopyOptions transformOptions = CopyOptions.create()
315
    .setFieldNameEditor(fieldName -> StrUtil.toCamelCase(fieldName));
316

317
BeanUtil.copyProperties(sourceMap, targetBean, transformOptions);
318
```
319

320
## Bean Validation and Introspection
321

322
### Bean Utilities
323

324
```java { .api }
325
// Check if object is a bean
326
public static boolean isBean(Class<?> clazz);
327
public static boolean hasProperty(Class<?> beanClass, String propertyName);
328

329
// Get readable/writable properties
330
public static Set<String> getReadablePropertyNames(Class<?> beanClass);
331
public static Set<String> getWritablePropertyNames(Class<?> beanClass);
332

333
// Property type information
334
public static Class<?> getPropertyType(Class<?> beanClass, String propertyName);
335
```
336

337
All bean operations handle edge cases gracefully:
338
- **Null Safety**: Methods handle null beans and properties appropriately
339
- **Type Safety**: Automatic type conversion where possible
340
- **Error Handling**: Options to ignore errors or throw exceptions
341
- **Performance**: Efficient caching of reflection metadata
342
- **Flexibility**: Support for nested properties using dot notation
343

344
The bean utilities provide a complete solution for working with Java objects dynamically, supporting both compile-time type safety and runtime flexibility.