001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018package org.apache.commons.beanutils; 019 020import java.lang.reflect.InvocationTargetException; 021import java.util.Map; 022 023/** 024 * <p>Utility methods for populating JavaBeans properties via reflection.</p> 025 * 026 * <p>The implementations are provided by {@link BeanUtilsBean}. 027 * These static utility methods use the default instance. 028 * More sophisticated behaviour can be provided by using a <code>BeanUtilsBean</code> instance.</p> 029 * 030 * @see BeanUtilsBean 031 */ 032public class BeanUtils { 033 034 /** 035 * The debugging detail level for this component. 036 * 037 * Note that this static variable will have unexpected side-effects if 038 * this class is deployed in a shared classloader within a container. 039 * However as it is actually completely ignored by this class due to its 040 * deprecated status, it doesn't do any actual harm. 041 * 042 * @deprecated BeanUtils now uses commons-logging for all log messages. 043 * Use your favorite logging tool to configure logging for 044 * this class. 045 */ 046 @Deprecated 047 private static int debug; 048 049 /** 050 * <p>Clone a bean based on the available property getters and setters, 051 * even if the bean class itself does not implement Cloneable.</p> 052 * 053 * <p>For more details see <code>BeanUtilsBean</code>.</p> 054 * 055 * @param bean Bean to be cloned 056 * @return the cloned bean 057 * @throws IllegalAccessException if the caller does not have 058 * access to the property accessor method 059 * @throws InstantiationException if a new instance of the bean's 060 * class cannot be instantiated 061 * @throws InvocationTargetException if the property accessor method 062 * throws an exception 063 * @throws NoSuchMethodException if an accessor method for this 064 * property cannot be found 065 * @see BeanUtilsBean#cloneBean 066 */ 067 public static Object cloneBean(final Object bean) 068 throws IllegalAccessException, InstantiationException, 069 InvocationTargetException, NoSuchMethodException { 070 return BeanUtilsBean.getInstance().cloneBean(bean); 071 } 072 073 /** 074 * <p>Copy property values from the origin bean to the destination bean 075 * for all cases where the property names are the same.</p> 076 * 077 * <p>For more details see <code>BeanUtilsBean</code>.</p> 078 * 079 * @param dest Destination bean whose properties are modified 080 * @param orig Origin bean whose properties are retrieved 081 * @throws IllegalAccessException if the caller does not have 082 * access to the property accessor method 083 * @throws IllegalArgumentException if the <code>dest</code> or 084 * <code>orig</code> argument is null or if the <code>dest</code> 085 * property type is different from the source type and the relevant 086 * converter has not been registered. 087 * @throws InvocationTargetException if the property accessor method 088 * throws an exception 089 * @see BeanUtilsBean#copyProperties 090 */ 091 public static void copyProperties(final Object dest, final Object orig) 092 throws IllegalAccessException, InvocationTargetException { 093 BeanUtilsBean.getInstance().copyProperties(dest, orig); 094 } 095 096 /** 097 * <p>Copy the specified property value to the specified destination bean, 098 * performing any type conversion that is required.</p> 099 * 100 * <p>For more details see <code>BeanUtilsBean</code>.</p> 101 * 102 * @param bean Bean on which setting is to be performed 103 * @param name Property name (can be nested/indexed/mapped/combo) 104 * @param value Value to be set 105 * @throws IllegalAccessException if the caller does not have 106 * access to the property accessor method 107 * @throws InvocationTargetException if the property accessor method 108 * throws an exception 109 * @see BeanUtilsBean#copyProperty 110 */ 111 public static void copyProperty(final Object bean, final String name, final Object value) 112 throws IllegalAccessException, InvocationTargetException { 113 BeanUtilsBean.getInstance().copyProperty(bean, name, value); 114 } 115 116 /** 117 * Create a cache. 118 * @param <K> the key type of the cache 119 * @param <V> the value type of the cache 120 * @return a new cache 121 * @since 1.8.0 122 */ 123 public static <K, V> Map<K, V> createCache() { 124 return new WeakFastHashMap<>(); 125 } 126 127 /** 128 * <p>Return the entire set of properties for which the specified bean 129 * provides a read method.</p> 130 * 131 * <p>For more details see <code>BeanUtilsBean</code>.</p> 132 * 133 * @param bean Bean whose properties are to be extracted 134 * @return Map of property descriptors 135 * @throws IllegalAccessException if the caller does not have 136 * access to the property accessor method 137 * @throws InvocationTargetException if the property accessor method 138 * throws an exception 139 * @throws NoSuchMethodException if an accessor method for this 140 * property cannot be found 141 * @see BeanUtilsBean#describe 142 */ 143 public static Map<String, String> describe(final Object bean) 144 throws IllegalAccessException, InvocationTargetException, 145 NoSuchMethodException { 146 return BeanUtilsBean.getInstance().describe(bean); 147 } 148 149 /** 150 * <p>Return the value of the specified array property of the specified 151 * bean, as a String array.</p> 152 * 153 * <p>For more details see <code>BeanUtilsBean</code>.</p> 154 * 155 * @param bean Bean whose property is to be extracted 156 * @param name Name of the property to be extracted 157 * @return The array property value 158 * @throws IllegalAccessException if the caller does not have 159 * access to the property accessor method 160 * @throws InvocationTargetException if the property accessor method 161 * throws an exception 162 * @throws NoSuchMethodException if an accessor method for this 163 * property cannot be found 164 * @see BeanUtilsBean#getArrayProperty 165 */ 166 public static String[] getArrayProperty(final Object bean, final String name) 167 throws IllegalAccessException, InvocationTargetException, 168 NoSuchMethodException { 169 return BeanUtilsBean.getInstance().getArrayProperty(bean, name); 170 } 171 172 /** 173 * Return whether a Map is fast 174 * @param map The map 175 * @return Whether it is fast or not. 176 * @since 1.8.0 177 */ 178 public static boolean getCacheFast(final Map<?, ?> map) { 179 if (map instanceof WeakFastHashMap) { 180 return ((WeakFastHashMap<?, ?>) map).getFast(); 181 } 182 return false; 183 } 184 185 /** 186 * The <code>debug</code> static property is no longer used 187 * @return debug property 188 * @deprecated BeanUtils now uses commons-logging for all log messages. 189 * Use your favorite logging tool to configure logging for 190 * this class. 191 */ 192 @Deprecated 193 public static int getDebug() { 194 return debug; 195 } 196 197 /** 198 * <p>Return the value of the specified indexed property of the specified 199 * bean, as a String.</p> 200 * 201 * <p>For more details see <code>BeanUtilsBean</code>.</p> 202 * 203 * @param bean Bean whose property is to be extracted 204 * @param name <code>propertyname[index]</code> of the property value 205 * to be extracted 206 * @return The indexed property's value, converted to a String 207 * @throws IllegalAccessException if the caller does not have 208 * access to the property accessor method 209 * @throws InvocationTargetException if the property accessor method 210 * throws an exception 211 * @throws NoSuchMethodException if an accessor method for this 212 * property cannot be found 213 * @see BeanUtilsBean#getIndexedProperty(Object, String) 214 */ 215 public static String getIndexedProperty(final Object bean, final String name) 216 throws IllegalAccessException, InvocationTargetException, 217 NoSuchMethodException { 218 return BeanUtilsBean.getInstance().getIndexedProperty(bean, name); 219 } 220 221 /** 222 * Return the value of the specified indexed property of the specified 223 * bean, as a String. The index is specified as a method parameter and 224 * must *not* be included in the property name expression 225 * 226 * <p>For more details see <code>BeanUtilsBean</code>.</p> 227 * 228 * @param bean Bean whose property is to be extracted 229 * @param name Simple property name of the property value to be extracted 230 * @param index Index of the property value to be extracted 231 * @return The indexed property's value, converted to a String 232 * @throws IllegalAccessException if the caller does not have 233 * access to the property accessor method 234 * @throws InvocationTargetException if the property accessor method 235 * throws an exception 236 * @throws NoSuchMethodException if an accessor method for this 237 * property cannot be found 238 * @see BeanUtilsBean#getIndexedProperty(Object, String, int) 239 */ 240 public static String getIndexedProperty(final Object bean, 241 final String name, final int index) 242 throws IllegalAccessException, InvocationTargetException, 243 NoSuchMethodException { 244 return BeanUtilsBean.getInstance().getIndexedProperty(bean, name, index); 245 246 } 247 248 /** 249 * <p>Return the value of the specified indexed property of the specified 250 * bean, as a String.</p> 251 * 252 * <p>For more details see <code>BeanUtilsBean</code>.</p> 253 * 254 * @param bean Bean whose property is to be extracted 255 * @param name <code>propertyname(index)</code> of the property value 256 * to be extracted 257 * @return The mapped property's value, converted to a String 258 * @throws IllegalAccessException if the caller does not have 259 * access to the property accessor method 260 * @throws InvocationTargetException if the property accessor method 261 * throws an exception 262 * @throws NoSuchMethodException if an accessor method for this 263 * property cannot be found 264 * @see BeanUtilsBean#getMappedProperty(Object, String) 265 */ 266 public static String getMappedProperty(final Object bean, final String name) 267 throws IllegalAccessException, InvocationTargetException, 268 NoSuchMethodException { 269 return BeanUtilsBean.getInstance().getMappedProperty(bean, name); 270 } 271 272 /** 273 * <p>Return the value of the specified mapped property of the specified 274 * bean, as a String.</p> 275 * 276 * <p>For more details see <code>BeanUtilsBean</code>.</p> 277 * 278 * @param bean Bean whose property is to be extracted 279 * @param name Simple property name of the property value to be extracted 280 * @param key Lookup key of the property value to be extracted 281 * @return The mapped property's value, converted to a String 282 * @throws IllegalAccessException if the caller does not have 283 * access to the property accessor method 284 * @throws InvocationTargetException if the property accessor method 285 * throws an exception 286 * @throws NoSuchMethodException if an accessor method for this 287 * property cannot be found 288 * @see BeanUtilsBean#getMappedProperty(Object, String, String) 289 */ 290 public static String getMappedProperty(final Object bean, 291 final String name, final String key) 292 throws IllegalAccessException, InvocationTargetException, 293 NoSuchMethodException { 294 return BeanUtilsBean.getInstance().getMappedProperty(bean, name, key); 295 296 } 297 298 /** 299 * <p>Return the value of the (possibly nested) property of the specified 300 * name, for the specified bean, as a String.</p> 301 * 302 * <p>For more details see <code>BeanUtilsBean</code>.</p> 303 * 304 * @param bean Bean whose property is to be extracted 305 * @param name Possibly nested name of the property to be extracted 306 * @return The nested property's value, converted to a String 307 * @throws IllegalAccessException if the caller does not have 308 * access to the property accessor method 309 * @throws IllegalArgumentException if a nested reference to a 310 * property returns null 311 * @throws InvocationTargetException if the property accessor method 312 * throws an exception 313 * @throws NoSuchMethodException if an accessor method for this 314 * property cannot be found 315 * @see BeanUtilsBean#getNestedProperty 316 */ 317 public static String getNestedProperty(final Object bean, final String name) 318 throws IllegalAccessException, InvocationTargetException, 319 NoSuchMethodException { 320 return BeanUtilsBean.getInstance().getNestedProperty(bean, name); 321 322 } 323 324 /** 325 * <p>Return the value of the specified property of the specified bean, 326 * no matter which property reference format is used, as a String.</p> 327 * 328 * <p>For more details see <code>BeanUtilsBean</code>.</p> 329 * 330 * @param bean Bean whose property is to be extracted 331 * @param name Possibly indexed and/or nested name of the property 332 * to be extracted 333 * @return The property's value, converted to a String 334 * @throws IllegalAccessException if the caller does not have 335 * access to the property accessor method 336 * @throws InvocationTargetException if the property accessor method 337 * throws an exception 338 * @throws NoSuchMethodException if an accessor method for this 339 * property cannot be found 340 * @see BeanUtilsBean#getProperty 341 */ 342 public static String getProperty(final Object bean, final String name) 343 throws IllegalAccessException, InvocationTargetException, 344 NoSuchMethodException { 345 return BeanUtilsBean.getInstance().getProperty(bean, name); 346 } 347 348 /** 349 * <p>Return the value of the specified simple property of the specified 350 * bean, converted to a String.</p> 351 * 352 * <p>For more details see <code>BeanUtilsBean</code>.</p> 353 * 354 * @param bean Bean whose property is to be extracted 355 * @param name Name of the property to be extracted 356 * @return The property's value, converted to a String 357 * @throws IllegalAccessException if the caller does not have 358 * access to the property accessor method 359 * @throws InvocationTargetException if the property accessor method 360 * throws an exception 361 * @throws NoSuchMethodException if an accessor method for this 362 * property cannot be found 363 * @see BeanUtilsBean#getSimpleProperty 364 */ 365 public static String getSimpleProperty(final Object bean, final String name) 366 throws IllegalAccessException, InvocationTargetException, 367 NoSuchMethodException { 368 return BeanUtilsBean.getInstance().getSimpleProperty(bean, name); 369 } 370 371 /** 372 * If we're running on JDK 1.4 or later, initialize the cause for the given throwable. 373 * 374 * @param throwable The throwable. 375 * @param cause The cause of the throwable. 376 * @return always true in 1.10.0. 377 * @since 1.8.0 378 * @deprecated Use {@link Throwable#initCause(Throwable)}. 379 * @see Throwable#initCause(Throwable) 380 */ 381 @Deprecated 382 public static boolean initCause(final Throwable throwable, final Throwable cause) { 383 throwable.initCause(cause); 384 return true; 385 } 386 387 /** 388 * <p>Populate the JavaBeans properties of the specified bean, based on 389 * the specified name/value pairs.</p> 390 * 391 * <p>For more details see <code>BeanUtilsBean</code>.</p> 392 * 393 * @param bean JavaBean whose properties are being populated 394 * @param properties Map keyed by property name, with the 395 * corresponding (String or String[]) value(s) to be set 396 * 397 * @throws IllegalAccessException if the caller does not have 398 * access to the property accessor method 399 * @throws InvocationTargetException if the property accessor method 400 * throws an exception 401 * @see BeanUtilsBean#populate 402 */ 403 public static void populate(final Object bean, final Map<String, ? extends Object> properties) 404 throws IllegalAccessException, InvocationTargetException { 405 BeanUtilsBean.getInstance().populate(bean, properties); 406 } 407 408 /** 409 * Set whether fast on a Map 410 * @param map The map 411 * @param fast Whether it should be fast or not. 412 * @since 1.8.0 413 */ 414 public static void setCacheFast(final Map<?, ?> map, final boolean fast) { 415 if (map instanceof WeakFastHashMap) { 416 ((WeakFastHashMap<?, ?>)map).setFast(fast); 417 } 418 } 419 420 /** 421 * The <code>debug</code> static property is no longer used 422 * @param newDebug debug property 423 * @deprecated BeanUtils now uses commons-logging for all log messages. 424 * Use your favorite logging tool to configure logging for 425 * this class. 426 */ 427 @Deprecated 428 public static void setDebug(final int newDebug) { 429 debug = newDebug; 430 } 431 432 /** 433 * <p>Set the specified property value, performing type conversions as 434 * required to conform to the type of the destination property.</p> 435 * 436 * <p>For more details see <code>BeanUtilsBean</code>.</p> 437 * 438 * @param bean Bean on which setting is to be performed 439 * @param name Property name (can be nested/indexed/mapped/combo) 440 * @param value Value to be set 441 * @throws IllegalAccessException if the caller does not have 442 * access to the property accessor method 443 * @throws InvocationTargetException if the property accessor method 444 * throws an exception 445 * @see BeanUtilsBean#setProperty 446 */ 447 public static void setProperty(final Object bean, final String name, final Object value) 448 throws IllegalAccessException, InvocationTargetException { 449 BeanUtilsBean.getInstance().setProperty(bean, name, value); 450 } 451}